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"
  90. dkim-mirage
  91. dlm
  92. dns-certify
  93. dns-cli >= "4.6.3"
  94. dns-client < "7.0.0"
  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.0"
  116. dune-rpc-lwt >= "3.7.0" & != "3.10.0"
  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-mirage
  139. git-cohttp-unix
  140. git-mirage >= "3.0.0"
  141. git-paf
  142. git-unix >= "3.0.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 >= "2.3.0"
  194. irmin-git >= "2.3.0"
  195. irmin-graphql >= "2.3.0"
  196. irmin-http >= "2.3.0"
  197. irmin-indexeddb
  198. irmin-layers
  199. irmin-mem >= "2.3.0"
  200. irmin-mirage-git >= "2.3.0"
  201. irmin-mirage-graphql >= "2.3.0"
  202. irmin-pack
  203. irmin-server
  204. irmin-test >= "2.3.0"
  205. irmin-unix >= "2.3.0"
  206. irmin-watcher
  207. joolog
  208. jose < "0.9.0"
  209. js_of_ocaml-lwt >= "3.5.0"
  210. jsoo_broadcastchannel
  211. jsoo_storage
  212. jupyter
  213. jupyter-kernel
  214. kafka < "0.5"
  215. kafka_lwt
  216. kappa-library
  217. ke >= "0.5"
  218. kinetic-client
  219. kubecaml
  220. lablqml < "0.6"
  221. lambda-runtime
  222. lambda-term
  223. lambda_streams_lwt
  224. launchd
  225. ldp
  226. learn-ocaml
  227. learn-ocaml-client
  228. ledgerwallet >= "0.4.0"
  229. letsencrypt
  230. letsencrypt-app
  231. letsencrypt-dns
  232. letters
  233. links >= "0.9.1"
  234. linol-lwt
  235. llama
  236. lru_cache
  237. lwt-canceler
  238. lwt-dllist
  239. lwt-exit
  240. lwt-parallel
  241. lwt-pipe
  242. lwt-pipeline
  243. lwt-watcher
  244. lwt_camlp4
  245. lwt_domain
  246. lwt_eio
  247. lwt_glib
  248. lwt_log
  249. lwt_ppx
  250. lwt_react
  251. lwt_retry
  252. lwt_ssl
  253. mariadb >= "1.2.0"
  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-mirage
  264. metrics-unix
  265. mimic
  266. mindstorm-lwt
  267. mirage < "3.1.1"
  268. mirage-block >= "2.0.1"
  269. mirage-block-ccm
  270. mirage-block-combinators
  271. mirage-block-lwt
  272. mirage-block-partition
  273. mirage-block-ramdisk
  274. mirage-block-solo5
  275. mirage-block-unix < "2.8.3" | >= "2.13.0"
  276. mirage-block-xen
  277. mirage-bootvar-solo5
  278. mirage-bootvar-unix
  279. mirage-bootvar-xen >= "0.4.0"
  280. mirage-channel >= "4.0.1"
  281. mirage-channel-lwt
  282. mirage-clock-freestanding < "3.0.1"
  283. mirage-clock-lwt
  284. mirage-clock-unix >= "1.3.0" & < "3.0.1"
  285. mirage-console >= "3.0.2"
  286. mirage-console-lwt
  287. mirage-console-solo5
  288. mirage-console-unix
  289. mirage-console-xen >= "5.0.0"
  290. mirage-console-xen-backend
  291. mirage-crypto-entropy
  292. mirage-crypto-rng >= "0.8.0" & < "0.11.0"
  293. mirage-crypto-rng-lwt
  294. mirage-crypto-rng-mirage >= "0.8.8"
  295. mirage-device >= "2.0.0"
  296. mirage-entropy
  297. mirage-flow >= "2.0.1"
  298. mirage-flow-combinators
  299. mirage-flow-lwt < "1.3.0" | >= "1.5.0"
  300. mirage-flow-rawlink
  301. mirage-flow-unix >= "1.3.0"
  302. mirage-fs >= "3.0.1"
  303. mirage-fs-lwt
  304. mirage-fs-unix
  305. mirage-kv >= "3.0.1"
  306. mirage-kv-lwt
  307. mirage-kv-unix
  308. mirage-logs != "0.3.0" & < "3.0.0"
  309. mirage-nat < "3.0.0"
  310. mirage-net >= "3.0.1"
  311. mirage-net-fd
  312. mirage-net-lwt
  313. mirage-net-macosx
  314. mirage-net-solo5
  315. mirage-net-unix
  316. mirage-net-xen
  317. mirage-os-shim
  318. mirage-profile
  319. mirage-protocols >= "4.0.1" & < "8.0.0"
  320. mirage-protocols-lwt
  321. mirage-qubes
  322. mirage-qubes-ipv4
  323. mirage-random-stdlib >= "0.1.0"
  324. mirage-runtime >= "3.7.0"
  325. mirage-sleep
  326. mirage-solo5
  327. mirage-stack >= "2.0.1" & < "4.0.0"
  328. mirage-stack-lwt
  329. mirage-time >= "2.0.1"
  330. mirage-time-lwt
  331. mirage-time-unix
  332. mirage-types-lwt < "3.7.1"
  333. mirage-unix
  334. mirage-vnetif
  335. mirage-vnetif-stack
  336. mirage-xen
  337. monorobot
  338. moonpool-lwt
  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. mwt
  346. naboris
  347. nbd >= "4.0.3"
  348. nbd-tool
  349. nbd-unix
  350. netchannel
  351. nocrypto
  352. nottui-lwt
  353. nproc
  354. nsq
  355. obuilder
  356. obus >= "1.2.1"
  357. ocaml-variants >= "4.00.1+mirage-unix" & < "4.00.1+open-types"
  358. ocluster
  359. ocluster-api
  360. ocluster-worker
  361. ocplib-resto
  362. ocsigenserver
  363. ocsipersist
  364. ocsipersist-dbm
  365. ocsipersist-lib
  366. ocsipersist-pgsql
  367. ocsipersist-sqlite
  368. octez-distributed-lwt-internal
  369. octez-internal-libs
  370. octez-l2-libs
  371. octez-libs
  372. octez-proto-libs
  373. octez-protocol-compiler
  374. octez-proxy-server
  375. octez-rpc-process
  376. octez-shell-libs
  377. octez-smart-rollup-wasm-benchmark-lib
  378. odoc >= "2.0.0" & < "2.1.0"
  379. oframl
  380. ojs_base
  381. omigrate
  382. oneffs
  383. opentelemetry-client-cohttp-lwt
  384. opentelemetry-cohttp-lwt >= "0.4"
  385. opentelemetry-lwt
  386. opium
  387. opium-graphql
  388. opium_kernel
  389. opomodoro
  390. order-i3-xfce
  391. ordma
  392. oskel >= "0.3.0"
  393. ounit-lwt < "2.2.0"
  394. ounit2-lwt
  395. owork
  396. ozulip
  397. paf
  398. paf-cohttp
  399. passage
  400. pcap-format < "0.5.2"
  401. petrol
  402. pgx_lwt
  403. pgx_lwt_mirage
  404. pgx_lwt_unix < "2.0"
  405. piaf < "0.2.0"
  406. picos >= "0.3.0" & < "0.5.0"
  407. picos_lwt
  408. picos_meta
  409. plebeia >= "2.0.0"
  410. plist-xml-lwt
  411. plotkicadsch
  412. ppx_defer >= "0.4.0"
  413. ppx_deriving_rpc
  414. ppx_rapper_lwt
  415. proc-smaps
  416. prof_spacetime
  417. prometheus
  418. prometheus-app
  419. promise_jsoo_lwt
  420. protocol-9p
  421. protocol-9p-unix
  422. qcow
  423. qcow-tool
  424. qfs >= "0.5"
  425. quests
  426. rawlink < "2.1"
  427. rawlink-lwt
  428. rdf_json_ld
  429. rdf_lwt
  430. redis-lwt
  431. reparse-lwt
  432. reparse-lwt-unix
  433. resource-pooling
  434. resp
  435. resp-mirage >= "0.10.0"
  436. resp-unix >= "0.10.0"
  437. resto
  438. resto-cohttp-client >= "0.4"
  439. resto-cohttp-self-serving-client
  440. resto-cohttp-server >= "0.4" & < "0.6" | >= "0.9"
  441. resto-directory >= "0.4"
  442. riak
  443. ringo-lwt
  444. river
  445. rock
  446. rpc < "7.1.0"
  447. rpclib-js
  448. rpclib-lwt
  449. SZXX < "4.0.0"
  450. sanddb
  451. scgi
  452. sendmail-lwt
  453. sendmail-mirage
  454. serial
  455. server-reason-react
  456. session-cohttp-lwt
  457. session-cookie-lwt
  458. session-postgresql-lwt
  459. sessions
  460. shared-block-ring
  461. shared-memory-ring-lwt
  462. sherlodoc
  463. sihl < "0.2.0"
  464. slack
  465. slacko
  466. slipshow
  467. smtml >= "0.3.1"
  468. speed
  469. spin < "0.8.0"
  470. spoke
  471. stk
  472. stog
  473. swapfs
  474. syguslib-utils
  475. syndic >= "1.4" & < "1.6.0"
  476. tar-mirage
  477. tar-unix
  478. tcpip >= "4.1.0"
  479. telegraml
  480. terminus
  481. testo-lwt
  482. tezos-base >= "16.0"
  483. tezos-clic >= "16.0"
  484. tezos-crypto >= "16.0"
  485. tezos-crypto-dal
  486. tezos-error-monad >= "16.0"
  487. tezos-lwt-result-stdlib
  488. tezos-p2p = "12.3"
  489. tezos-protocol-environment
  490. tezos-proxy >= "17.3"
  491. tezos-stdlib
  492. tezos-stdlib-unix >= "16.0"
  493. tezos-test-helpers >= "12.3"
  494. tezos-wasmer
  495. tezos-webassembly-interpreter-extra
  496. tezt
  497. tidy_email
  498. timmy-lwt
  499. tls >= "0.10.6" & < "0.16.0"
  500. tls-lwt
  501. tls-mirage
  502. tube
  503. tuntap < "1.7.0" | >= "2.0.0"
  504. twirp_cohttp_lwt_unix
  505. u2f
  506. uring
  507. uspf
  508. uspf-lwt
  509. uspf-mirage
  510. utop
  511. uwt
  512. vchan
  513. vchan-unix
  514. vchan-xen
  515. vercel
  516. vhd-format-lwt
  517. vmnet
  518. vpnkit
  519. vue-jsoo < "0.3"
  520. wayland < "2.0"
  521. webauthn
  522. xen-evtchn >= "2.0.0"
  523. xen-evtchn-unix
  524. xen-gnt
  525. xen-gnt-unix >= "4.0.2"
  526. xenstore
  527. xenstore_transport
  528. xlsx2csv
  529. yocaml_git
  530. yocaml_unix < "2.0.0"
  531. zarr-lwt
  532. 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