package lwt

  1. Overview
  2. Docs
Promises and event-driven I/O

Install 

dune-project
 Dependency

github.com Readme MIT License Edit opam file Versions (30)

Authors

  1. J
    Jérôme Vouillon
  2. J
    Jérémie Dimino

Maintainers

  1. R
    Raphaël Proust <code@bnwr.net>
  2. Anton Bachin

Sources

5.9.1.tar.gz
md5=18742da8b8fe3618e3fa700b7a884fe7
sha512=1c51fdb4d0856c89e2df08a1c0095ef28ebd0f613b07b03d0f66501ca5486515562071291e6d0932e57587ed0c9362c8b92c5c9eddb4d2bb2f5e129986b484a7

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.

Published: 15 Mar 2025

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 determined 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:

open Lwt.Syntax

let () =
  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 -linkpkg example.ml && ./a.out *)

In the program, functions such as Lwt_io.write create promises. The let* ... in construct is used to wait for a promise to become determined; the code after in is scheduled to run in a "callback." 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.0"
  4. ocaml >= "4.08"
  5. dune >= "2.7"

Dev Dependencies (2)

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

Conflicts

None