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