package lwt

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

Install

Dune Dependency

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

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

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

Conflicts

None

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct