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