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.8.1.tar.gz
md5=d0f824f75ce5297975aec75366fed36c
sha512=c43fff2e9e808dc49ddf09caf7040e512ba36aebe2c600d524095ced11c196c3ac619953a11cb3e3a9f7c6c99e798d43bf179d5f790ab258fb9f746fae4c1125

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