package lwt

All checked builds pass
  1. Overview
  2. Docs
Promises and event-driven I/O

Install

dune-project
 Dependency

Authors

Maintainers

Sources

6.1.2.tar.gz
md5=00bc7eb2772a28530f7365a7040f0c4f
sha512=a4737a2fc44aaeedca46ec6134c07013d5cf44039a988a6e79a40715a53e43601d4c91bbf11a8e89540528d912b8fa487e3068465c136c1156a872258eb3443b

Description

A promise is a value that may become determined in the future.

Lwt provides typed, composable promises. Promises that are resolved by I/O are resolved by Lwt in parallel.

Meanwhile, OCaml code, including code creating and waiting on promises, runs in a single thread by default. This reduces the need for locks or other synchronization primitives. Code can be run in parallel on an opt-in basis.

Added to opam-repository:

README

Lwt

version GitHub Actions status

Lwt is a concurrent programming library for OCaml. It provides a single data type: the promise, which is a value that will become resolved in the future. Creating a promise spawns a computation. When that computation is I/O, Lwt runs it in parallel with your OCaml code.

OCaml code, including creating and waiting on promises, is run in a single thread by default, so you don't have to worry about locking or preemption. You can detach code to be run in separate threads on an opt-in basis.

Here is a simplistic Lwt program which requests the Google front page, and fails if the request is not completed in five seconds:

let () =
  let request =
    let%lwt addresses = Lwt_unix.getaddrinfo "google.com" "80" [] in
    let google = Lwt_unix.((List.hd addresses).ai_addr) in

    Lwt_io.(with_connection google (fun (incoming, outgoing) ->
      write outgoing "GET / HTTP/1.1\r\n";%lwt
      write outgoing "Connection: close\r\n\r\n";%lwt
      let%lwt response = read incoming in
      Lwt.return (Some response)))
  in

  let timeout =
    Lwt_unix.sleep 5.;%lwt
    Lwt.return_none
  in

  match Lwt_main.run (Lwt.pick [request; timeout]) with
  | Some response -> print_string response
  | None -> prerr_endline "Request timed out"; exit 1

(* ocamlfind opt -package lwt.unix,lwt_ppx -linkpkg example.ml && ./a.out *)

If you are not using the lwt_ppx syntax extension, you can use the let* binding opoerators from the Lwt.Syntax module instead.

let () =
  let open Lwt.Syntax in
  let request =
    let* addresses = Lwt_unix.getaddrinfo "google.com" "80" [] in
    let google = Lwt_unix.((List.hd addresses).ai_addr) in

    Lwt_io.(with_connection google (fun (incoming, outgoing) ->
      let* () = write outgoing "GET / HTTP/1.1\r\n" in
      let* () = write outgoing "Connection: close\r\n\r\n" in
      let* response = read incoming in
      Lwt.return (Some response)))
  in

  let timeout =
    let* () = Lwt_unix.sleep 5. in
    Lwt.return_none
  in

  match Lwt_main.run (Lwt.pick [request; timeout]) with
  | Some response -> print_string response
  | None -> prerr_endline "Request timed out"; exit 1

(* ocamlfind opt -package lwt.unix,lwt_ppx -linkpkg example.ml && ./a.out *)

In the program above, functions such as Lwt_io.write create promises. The let%lwt ... in construct (provided by lwt_ppx) or the let* ... in construct (provided by Lwt.Syntax) are used to wait for a promise to resolve. The code after in is scheduled to run after the code inside the let...in has resolved.

Lwt.pick races promises against each other, and behaves as the first one to complete.

Lwt_main.run forces the whole promise-computation network to be executed. All the visible OCaml code is run in a single thread, but Lwt internally uses a combination of worker threads and non-blocking file descriptors to resolve in parallel the promises that do I/O.


Overview

Lwt compiles to native code on Linux, macOS, Windows, and other systems. It's also routinely compiled to JavaScript for the front end and Node by js_of_ocaml.

In Lwt,

  • The core library Lwt provides promises...
  • ...and a few pure-OCaml helpers, such as promise-friendly mutexes, condition variables, and mvars.
  • There is a big Unix binding, Lwt_unix that binds almost every Unix system call. A higher-level module Lwt_io provides nice I/O channels.
  • Lwt_process is for subprocess handling.
  • Lwt_preemptive spawns system threads.
  • The PPX syntax allows using all of the above without going crazy!
  • There are also some other helpers, such as Lwt_react for reactive programming. See the table of contents on the linked manual pages!

Installing

  1. Use your system package manager to install a development libev package. It is often called libev-dev or libev-devel.
  2. opam install conf-libev lwt

Documentation

We are currently working on improving the Lwt documentation (drastically; we are rewriting the manual). In the meantime:

  • The current manual can be found here.
  • Mirage has a nicely-written Lwt tutorial.
  • An example of a simple server written in Lwt.
  • Concurrent Programming with Lwt is a nice source of Lwt examples. They are translations of code from the excellent Real World OCaml, but are just as useful if you are not reading the book.

Note: much of the current manual refers to 'a Lwt.t as "lightweight threads" or just "threads." This will be fixed in the new manual. 'a Lwt.t is a promise, and has nothing to do with system or preemptive threads.


Contact

Open an issue, visit Discord chat, ask on discuss.ocaml.org, or on Stack Overflow.

Release announcements are made on discuss.ocaml.org. Watching the repo for "Releases only" is also an option.


Contributing

  • CONTRIBUTING.md contains tips for working on the code, such as how to check the code out, how review works, etc. There is also a high-level outline of the code base.
  • Ask us anything, whether it's about working on Lwt, or any question at all about it :)
  • The documentation always needs proofreading and fixes.
  • You are welcome to pick up any other issue, review a PR, add your opinion, etc.
  • Any feedback is welcome, including how to make contributing easier!

Libraries to use with Lwt

Dependencies (5)

  1. ocplib-endian
  2. dune-configurator
  3. cppo build & >= "1.1"
  4. ocaml >= "4.14"
  5. dune >= "3.18"

Dev Dependencies (2)

  1. odoc with-doc & >= "2.3"
  2. ocamlfind dev & >= "1.7.3-1"

  1. 0install >= "2.15.1"
  2. aches-lwt
  3. activitypub
  4. albatross
  5. alcotest-lwt
  6. alcotest-mirage
  7. ambient-context-lwt
  8. amqp-client >= "1.1.0"
  9. amqp-client-lwt
  10. angstrom-lwt-unix >= "0.11.0"
  11. anthill
  12. anycache-lwt
  13. archi-lwt
  14. arp
  15. atproto
  16. awa-mirage
  17. aws-lwt
  18. aws-s3-lwt >= "4.8.1"
  19. awskit-lwt
  20. awskit-lwt-unix
  21. awskit-s3-lwt
  22. awskit-s3-lwt-unix
  23. awsm-lwt
  24. awso-lwt
  25. azure-cosmos-db < "0.4.0"
  26. azure-cosmos-db-lwt
  27. balancer
  28. bastet_lwt
  29. bimage-lwt
  30. bistro
  31. bitflyer
  32. bizowie-api
  33. brisk-reconciler
  34. builder
  35. builder-web
  36. bun >= "0.3.3"
  37. cachet-lwt
  38. calculon < "0.9"
  39. caldav
  40. camltc
  41. canary
  42. capnp-rpc-lwt < "2.0"
  43. capnp-rpc-unix < "2.1"
  44. caqti-lwt
  45. caqti-mirage
  46. carton < "1.0.0"
  47. carton-git
  48. carton-lwt
  49. catala-format >= "0.2.0"
  50. cf-lwt
  51. chamelon
  52. chamelon-unix
  53. chamo
  54. charrua-client
  55. charrua-unix
  56. chess_com_api
  57. ciao_lwt
  58. clz
  59. cmdtui-lambda-term
  60. coap
  61. coap-server-lwt
  62. cohttp-curl-lwt
  63. cohttp-lwt
  64. cohttp-lwt-jsoo
  65. cohttp-lwt-unix
  66. cohttp-mirage
  67. cohttp-server-lwt-unix
  68. comby
  69. comby-semantic
  70. conan-lwt
  71. conduit-lwt
  72. conduit-lwt-unix
  73. console-lwt
  74. cosmetyc_native
  75. cowabloga
  76. crunch
  77. cstruct-lwt
  78. csv-lwt
  79. ctypes >= "0.15.0" & < "0.21.1"
  80. ctypes-foreign >= "0.21.1"
  81. curl_lwt
  82. current
  83. current-albatross-deployer
  84. current_docker
  85. current_examples
  86. current_git
  87. current_github
  88. current_gitlab
  89. current_ocluster
  90. current_rpc
  91. current_slack
  92. current_web
  93. dap
  94. data-encoding < "0.1.1"
  95. devkit >= "1.2"
  96. distributed-lwt
  97. dkim-bin < "0.8.0"
  98. dkim-lwt-unix
  99. dkim-mirage
  100. dlm
  101. dmarc
  102. dns-certify
  103. dns-cli
  104. dns-client < "7.0.3"
  105. dns-client-lwt
  106. dns-client-mirage
  107. dns-forward
  108. dns-forward-lwt-unix
  109. dns-lwt
  110. dns-mirage
  111. dns-resolver
  112. dns-server
  113. dns-stub
  114. dnsrobot
  115. dnssd
  116. docker_hub
  117. docteur >= "0.0.2"
  118. docteur-solo5
  119. docteur-unix >= "0.0.5"
  120. doi2bib
  121. dream
  122. dream-httpaf
  123. dream-mirage
  124. dream-pure
  125. dream-serve < "1.0.1"
  126. dropbox
  127. dune >= "3.17.2"
  128. dune-rpc-lwt
  129. earlybird
  130. elasticsearch-cli
  131. emoji = "2.0.0"
  132. equinoxe
  133. ethernet
  134. ez_api >= "1.2.0" & < "3.0.0"
  135. ezcurl-lwt
  136. ezjs_min < "0.2"
  137. ezjsonm-lwt
  138. ezresto
  139. faraday-lwt
  140. faraday-lwt-unix
  141. fat-filesystem
  142. fiber-lwt
  143. fsevents-lwt
  144. fswatch_lwt
  145. fxmacrodata
  146. gdbprofiler
  147. git
  148. git-cohttp
  149. git-cohttp-unix
  150. git-kv >= "0.2.0"
  151. git-mirage
  152. git-net >= "0.2.4"
  153. git-paf
  154. git-unix >= "3.2.0"
  155. github
  156. github-hooks
  157. github-unix >= "4.4.0"
  158. gitlab-unix
  159. gitlab_pipeline_notifier
  160. gluten-lwt
  161. gluten-lwt-unix < "0.4.0"
  162. gluten-mirage < "0.4.0"
  163. gmocoin
  164. granary
  165. granary_repl
  166. graphql-lwt
  167. gremlin
  168. grpc-lwt
  169. guardian
  170. gufo
  171. h1
  172. h1-lwt-unix
  173. h2-lwt
  174. h2-lwt-unix < "0.10.0"
  175. h2-mirage
  176. happy-eyeballs-lwt
  177. happy-eyeballs-mirage
  178. hidapi-lwt
  179. hiredis >= "0.6"
  180. hl_yaml
  181. hockmd
  182. http-lwt-client
  183. http-mirage-client
  184. http-multipart-formdata >= "2.0.0" & < "3.0.0"
  185. httpaf-lwt-unix
  186. httpun-lwt
  187. httpun-mirage
  188. httpun-ws-lwt
  189. hvsock
  190. i3ipc
  191. influxdb-lwt
  192. inotify >= "2.4"
  193. inquire < "0.2.1"
  194. interface-prime-lwt
  195. ip2location
  196. ip2locationio
  197. ip2whois
  198. ipv6-multicast-lwt
  199. irc-client-lwt
  200. irc-client-lwt-ssl
  201. irc-client-tls
  202. irmin
  203. irmin-bench
  204. irmin-chunk
  205. irmin-cli
  206. irmin-client
  207. irmin-containers
  208. irmin-fs
  209. irmin-git
  210. irmin-graphql
  211. irmin-http
  212. irmin-indexeddb
  213. irmin-layers
  214. irmin-mirage-git
  215. irmin-mirage-graphql
  216. irmin-pack
  217. irmin-server
  218. irmin-test
  219. irmin-unix
  220. irmin-watcher
  221. joolog
  222. jose < "0.9.0"
  223. js_of_ocaml-lwt
  224. jsoo_broadcastchannel
  225. jsoo_storage
  226. jupyter
  227. jupyter-kernel
  228. kafka < "0.5"
  229. kafka_lwt
  230. kappa-library
  231. ke >= "0.5"
  232. kinetic-client
  233. kubecaml
  234. lambda-runtime
  235. lambda-term >= "3.3.3"
  236. lambda_streams_lwt
  237. launchd
  238. ldp
  239. learn-ocaml
  240. learn-ocaml-client
  241. ledgerwallet >= "0.4.0"
  242. letsencrypt < "2.0.0"
  243. letsencrypt-app
  244. letsencrypt-dns < "2.0.0"
  245. letters
  246. lichess_api
  247. links
  248. linol-lwt >= "0.11"
  249. llama
  250. lru_cache
  251. lwt-canceler
  252. lwt-dllist
  253. lwt-exit
  254. lwt-parallel
  255. lwt-pipe
  256. lwt-pipeline
  257. lwt-watcher
  258. lwt_camlp4
  259. lwt_direct >= "6.0.0"
  260. lwt_domain != "0.2.0"
  261. lwt_eio >= "0.6"
  262. lwt_log >= "1.1.3"
  263. lwt_ppx >= "6.0.0"
  264. lwt_react
  265. lwt_retry
  266. lwt_ssl
  267. mariadb >= "1.2.0"
  268. markdown_monolith
  269. markup = "0.7.6"
  270. markup-lwt
  271. mdx
  272. mechaml
  273. mehari-lwt-unix
  274. mehari-mirage < "0.5"
  275. memtrace-mirage
  276. metrics-influx
  277. metrics-lwt
  278. metrics-unix
  279. migra
  280. mimic
  281. mindstorm-lwt
  282. mirage < "4.0.0"
  283. mirage-block >= "2.0.1"
  284. mirage-block-ccm
  285. mirage-block-combinators
  286. mirage-block-lwt
  287. mirage-block-partition
  288. mirage-block-ramdisk
  289. mirage-block-solo5
  290. mirage-block-unikraft
  291. mirage-block-unix >= "2.14.2"
  292. mirage-block-xen
  293. mirage-channel >= "4.0.1"
  294. mirage-channel-lwt
  295. mirage-clock-lwt
  296. mirage-clock-unix < "4.2.0"
  297. mirage-console-lwt
  298. mirage-crypto-rng < "0.11.3"
  299. mirage-crypto-rng-lwt
  300. mirage-crypto-rng-mirage
  301. mirage-device >= "2.0.0"
  302. mirage-flow >= "3.0.0"
  303. mirage-flow-combinators
  304. mirage-flow-lwt
  305. mirage-flow-unix
  306. mirage-fs >= "4.0.0"
  307. mirage-fs-lwt
  308. mirage-kv >= "3.0.1"
  309. mirage-kv-lwt
  310. mirage-kv-unix
  311. mirage-net >= "4.0.0"
  312. mirage-net-lwt
  313. mirage-net-macosx
  314. mirage-net-solo5
  315. mirage-net-unikraft
  316. mirage-net-unix
  317. mirage-net-xen
  318. mirage-profile
  319. mirage-protocols >= "7.0.0"
  320. mirage-protocols-lwt
  321. mirage-qubes
  322. mirage-qubes-ipv4
  323. mirage-runtime
  324. mirage-sleep
  325. mirage-solo5
  326. mirage-stack = "3.0.0"
  327. mirage-stack-lwt
  328. mirage-time >= "3.0.0"
  329. mirage-time-lwt
  330. mirage-time-unix
  331. mirage-types-lwt
  332. mirage-unikraft
  333. mirage-unix
  334. mirage-vnetif
  335. mirage-xen
  336. monorobot
  337. moonpool-lwt >= "0.12"
  338. mosaic >= "0.2.0"
  339. mqtt
  340. mrmime >= "0.5.0"
  341. multipart-form-data
  342. multipart_form >= "0.2.0" & < "0.4.0"
  343. multipart_form-cohttp-lwt < "0.6.0"
  344. multipart_form-lwt
  345. naboris
  346. nbd >= "4.0.3"
  347. nbd-tool
  348. nbd-unix
  349. neo4j_bolt
  350. nottui-lwt
  351. notty-community
  352. nproc
  353. nsq
  354. obuilder
  355. obus >= "1.2.1"
  356. ocaml-ai-sdk
  357. ocluster
  358. ocluster-api
  359. ocluster-worker
  360. ocplib-resto
  361. ocsigenserver
  362. ocsipersist
  363. ocsipersist-dbm
  364. ocsipersist-lib
  365. ocsipersist-pgsql
  366. ocsipersist-sqlite
  367. oframl
  368. ohttp-cohttp-lwt
  369. ojs_base
  370. omigrate
  371. oneffs
  372. opam-check-npm-deps >= "4.1.0"
  373. opam-publish >= "3.0.0"
  374. opencage
  375. opentelemetry-client-cohttp-lwt
  376. opentelemetry-client-ocurl-lwt
  377. opentelemetry-cohttp-lwt >= "0.4"
  378. opentelemetry-lwt
  379. opium
  380. opium-graphql
  381. opium_kernel
  382. opomodoro
  383. order-i3-xfce
  384. ordma
  385. oskel >= "0.3.0"
  386. ounit-lwt < "2.2.0"
  387. ounit2-lwt
  388. owork
  389. ozulip
  390. paf
  391. paf-cohttp
  392. passage < "0.1.8"
  393. pcap-format < "0.5.2"
  394. petrol
  395. pgn_parser
  396. pgx_lwt
  397. pgx_lwt_mirage
  398. pgx_lwt_unix < "2.0"
  399. piaf < "0.2.0"
  400. picos >= "0.3.0" & < "0.5.0"
  401. picos_meta
  402. plebeia >= "2.0.0"
  403. plotkicadsch
  404. posix-getopt >= "4.0.2"
  405. ppx_defer >= "0.4.0"
  406. ppx_deriving_rpc
  407. ppx_rapper_lwt
  408. privatus-analytics-dream
  409. proc-smaps
  410. prof_spacetime
  411. prometheus < "2.0"
  412. prometheus-app
  413. prometheus-lwt
  414. promise_jsoo_lwt
  415. protocol-9p
  416. protocol-9p-unix
  417. proton
  418. pxshot
  419. qcow
  420. qcow-stream
  421. qcow-tool
  422. qcow-types
  423. qdrant < "0.2.0"
  424. qfs
  425. quests
  426. quickterface
  427. rawlink < "2.1"
  428. rawlink-lwt
  429. rdf_json_ld
  430. rdf_lwt
  431. redis-lwt
  432. reparse-lwt
  433. reparse-lwt-unix
  434. resource-pooling
  435. resp
  436. resp-mirage >= "0.10.0"
  437. resp-unix >= "0.10.0"
  438. resto
  439. resto-cohttp-client = "0.4"
  440. resto-cohttp-server = "0.4"
  441. resto-directory = "0.4"
  442. ringo-lwt
  443. river
  444. rock
  445. rpclib-js
  446. rpclib-lwt
  447. SZXX < "4.0.0"
  448. sanddb
  449. scgi
  450. sendmail-lwt
  451. sendmail-mirage
  452. serial
  453. server-reason-react
  454. session-cohttp-lwt
  455. session-cookie-lwt
  456. session-postgresql-lwt
  457. sessions
  458. shared-block-ring
  459. shared-memory-ring-lwt
  460. sherlodoc
  461. sihl < "0.2.0"
  462. slack
  463. slacko
  464. slipshow
  465. smtml >= "0.7.0"
  466. speed
  467. spin < "0.8.0"
  468. spoke
  469. statocaml
  470. stk
  471. stog
  472. swapfs
  473. syguslib-utils
  474. syndic >= "1.4" & < "1.6.0"
  475. tar-mirage
  476. tar-unix
  477. tcpip
  478. telegraml
  479. terminus
  480. testcontainers
  481. testo-lwt
  482. tidy_email
  483. tls >= "0.10.6" & < "0.16.0"
  484. tls-lwt
  485. tls-mirage
  486. tube
  487. tuntap
  488. twirp_cohttp_lwt_unix
  489. uring
  490. uspf
  491. uspf-lwt
  492. uspf-mirage
  493. utcp
  494. utop
  495. uwt
  496. vchan
  497. vchan-unix
  498. vchan-xen
  499. vercel
  500. vhd-format-lwt
  501. vmnet
  502. vue-jsoo < "0.3"
  503. wayland < "2.0"
  504. webauthn
  505. websocket-lwt-unix >= "2.18"
  506. xen-evtchn
  507. xen-evtchn-unix
  508. xen-gnt
  509. xen-gnt-unix
  510. xenstore
  511. xenstore-tool
  512. xenstore_transport
  513. xlsx2csv
  514. yocaml_git
  515. yocaml_unix < "2.0.0"
  516. zarr-lwt
  517. zmq-lwt >= "5.2.1"

Conflicts

None

Build status

Results of building lwt with each compiler on check.ci.ocaml.org, run of against opam-repository 78c202b. All results for this package.

Each result links to its build log. To keep crawlers from overloading the site, build logs require a GitHub sign-in (see ocurrent/opam-health-check). On your first log, GitHub asks you to “Authorize opam-health-check”, the OCurrent app that runs these checks; it sees only your public profile, not your repositories. The sign-in lasts 30 days.

Version OCaml 4.11 OCaml 4.14 OCaml 5.2 OCaml 5.4 OCaml 5.5
6.1.2 (this version) n/a good good good good
5.10.1 good good good good good
  • good Package successfully built
  • partial One of the dependencies failed to build
  • bad Package failed to build
  • n/a Package is not available in this environment
  • internal Internal failure