package lwt

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

Install 

dune-project
 Dependency

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

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

version GitHub Actions status

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.5"
  5. dune >= "2.7"

Dev Dependencies (2)

  1. odoc with-doc & >= "2.3.0"
  2. ocamlfind with-dev-setup & >= "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.8.1"
  18. awsm-lwt
  19. awso-lwt
  20. azure-cosmos-db < "0.4.0"
  21. azure-cosmos-db-lwt
  22. balancer
  23. bastet_lwt
  24. bimage-lwt
  25. bistro
  26. bizowie-api
  27. brisk-reconciler
  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 < "2.1"
  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
  49. charrua-unix
  50. chess_com_api
  51. ciao_lwt
  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
  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
  83. current_slack
  84. current_web
  85. dap
  86. data-encoding < "0.1.1"
  87. devkit >= "1.2"
  88. distributed-lwt
  89. dkim-bin < "0.8.0"
  90. dkim-lwt-unix
  91. dkim-mirage
  92. dlm
  93. dmarc
  94. dns-certify
  95. dns-cli
  96. dns-client < "7.0.3"
  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. dnsrobot
  107. dnssd
  108. docker_hub
  109. docteur >= "0.0.2"
  110. docteur-solo5
  111. docteur-unix >= "0.0.5"
  112. doi2bib
  113. dream
  114. dream-httpaf
  115. dream-pure
  116. dream-serve
  117. dropbox
  118. dune >= "3.17.2"
  119. dune-rpc-lwt
  120. earlybird
  121. elasticsearch-cli
  122. emoji = "2.0.0"
  123. equinoxe
  124. ethernet
  125. ez_api >= "1.2.0" & < "3.0.0"
  126. ezcurl-lwt
  127. ezjs_min < "0.2"
  128. ezjsonm-lwt
  129. ezresto
  130. ezresto-directory >= "0.5"
  131. faraday-lwt
  132. faraday-lwt-unix
  133. fat-filesystem
  134. fiber-lwt
  135. fsevents-lwt
  136. fswatch_lwt
  137. fuseau-lwt
  138. gdbprofiler
  139. git
  140. git-cohttp
  141. git-cohttp-unix
  142. git-kv >= "0.2.0"
  143. git-mirage
  144. git-paf
  145. git-unix >= "3.2.0"
  146. github
  147. github-hooks
  148. github-unix >= "4.4.0"
  149. gitlab-unix
  150. gitlab_pipeline_notifier
  151. gluten-lwt
  152. gluten-lwt-unix < "0.4.0"
  153. gluten-mirage < "0.4.0"
  154. graphql-lwt
  155. gremlin
  156. grpc-lwt
  157. guardian
  158. gufo
  159. h1
  160. h1-lwt-unix
  161. h2-lwt
  162. h2-lwt-unix < "0.10.0"
  163. h2-mirage
  164. happy-eyeballs-lwt
  165. happy-eyeballs-mirage
  166. hidapi-lwt
  167. hiredis >= "0.6"
  168. hl_yaml
  169. hockmd
  170. http-lwt-client
  171. http-mirage-client
  172. http-multipart-formdata >= "2.0.0" & < "3.0.0"
  173. httpaf-lwt-unix
  174. httpun-lwt
  175. httpun-mirage
  176. httpun-ws-lwt
  177. hvsock
  178. i3ipc
  179. influxdb-lwt
  180. inotify >= "2.4"
  181. inquire < "0.3.0"
  182. interface-prime-lwt
  183. ip2location
  184. ip2locationio
  185. ip2whois
  186. ipv6-multicast-lwt
  187. irc-client-lwt
  188. irc-client-lwt-ssl
  189. irc-client-tls
  190. irmin
  191. irmin-bench
  192. irmin-chunk
  193. irmin-cli
  194. irmin-client
  195. irmin-containers
  196. irmin-fs
  197. irmin-git
  198. irmin-graphql
  199. irmin-http
  200. irmin-indexeddb
  201. irmin-layers
  202. irmin-mirage-git
  203. irmin-mirage-graphql
  204. irmin-pack
  205. irmin-server
  206. irmin-test
  207. irmin-unix
  208. irmin-watcher
  209. joolog
  210. jose < "0.9.0"
  211. js_of_ocaml-lwt
  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. 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 < "2.0.0"
  231. letsencrypt-app
  232. letsencrypt-dns < "2.0.0"
  233. letters
  234. lichess_api
  235. links
  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 < "0.6"
  249. lwt_glib
  250. lwt_log
  251. lwt_ppx < "6.0.0~beta01"
  252. lwt_react
  253. lwt_retry
  254. lwt_ssl
  255. mariadb >= "1.2.0"
  256. markdown_monolith
  257. markup = "0.7.6"
  258. markup-lwt
  259. mdx
  260. mechaml
  261. mehari-lwt-unix
  262. mehari-mirage
  263. memtrace-mirage
  264. metrics-influx
  265. metrics-lwt
  266. metrics-unix
  267. mimic
  268. mindstorm-lwt
  269. mirage < "4.0.0"
  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-unikraft
  278. mirage-block-unix >= "2.14.2"
  279. mirage-block-xen
  280. mirage-channel >= "4.0.1"
  281. mirage-channel-lwt
  282. mirage-clock-lwt
  283. mirage-clock-unix < "4.2.0"
  284. mirage-console-lwt
  285. mirage-crypto-rng < "0.11.3"
  286. mirage-crypto-rng-lwt
  287. mirage-crypto-rng-mirage
  288. mirage-device >= "2.0.0"
  289. mirage-flow >= "3.0.0"
  290. mirage-flow-combinators
  291. mirage-flow-lwt
  292. mirage-flow-unix
  293. mirage-fs >= "4.0.0"
  294. mirage-fs-lwt
  295. mirage-kv >= "3.0.1"
  296. mirage-kv-lwt
  297. mirage-kv-unix
  298. mirage-net >= "4.0.0"
  299. mirage-net-lwt
  300. mirage-net-macosx
  301. mirage-net-solo5
  302. mirage-net-unikraft
  303. mirage-net-unix
  304. mirage-net-xen
  305. mirage-profile
  306. mirage-protocols >= "7.0.0"
  307. mirage-protocols-lwt
  308. mirage-qubes
  309. mirage-qubes-ipv4
  310. mirage-runtime
  311. mirage-sleep
  312. mirage-solo5
  313. mirage-stack = "3.0.0"
  314. mirage-stack-lwt
  315. mirage-time >= "3.0.0"
  316. mirage-time-lwt
  317. mirage-time-unix
  318. mirage-types-lwt
  319. mirage-unikraft
  320. mirage-unix
  321. mirage-vnetif
  322. mirage-xen
  323. monorobot
  324. moonpool-lwt
  325. mqtt
  326. mrmime >= "0.5.0"
  327. multipart-form-data
  328. multipart_form >= "0.2.0" & < "0.4.0"
  329. multipart_form-cohttp-lwt < "0.6.0"
  330. multipart_form-lwt
  331. mwt
  332. naboris
  333. nbd >= "4.0.3"
  334. nbd-tool
  335. nbd-unix
  336. neo4j_bolt
  337. nocrypto
  338. nottui-lwt
  339. notty-community
  340. nproc
  341. nsq
  342. obuilder
  343. obus >= "1.2.1"
  344. ocaml-ai-sdk
  345. ocluster
  346. ocluster-api
  347. ocluster-worker
  348. ocplib-resto
  349. ocsigenserver
  350. ocsipersist
  351. ocsipersist-dbm
  352. ocsipersist-lib
  353. ocsipersist-pgsql
  354. ocsipersist-sqlite
  355. oframl
  356. ojs_base
  357. omigrate
  358. oneffs
  359. opam-check-npm-deps >= "4.1.0"
  360. opam-publish >= "3.0.0"
  361. opencage
  362. opentelemetry-client-cohttp-lwt
  363. opentelemetry-client-ocurl-lwt
  364. opentelemetry-cohttp-lwt >= "0.4"
  365. opentelemetry-lwt
  366. opium
  367. opium-graphql
  368. opium_kernel
  369. opomodoro
  370. order-i3-xfce
  371. ordma
  372. oskel >= "0.3.0"
  373. ounit-lwt < "2.2.0"
  374. ounit2-lwt
  375. owork
  376. ozulip
  377. paf
  378. paf-cohttp
  379. passage < "0.1.8"
  380. pcap-format < "0.5.2"
  381. petrol
  382. pgn_parser
  383. pgx_lwt
  384. pgx_lwt_mirage
  385. pgx_lwt_unix < "2.0"
  386. piaf < "0.2.0"
  387. picos >= "0.3.0" & < "0.5.0"
  388. picos_lwt
  389. picos_meta
  390. plebeia >= "2.0.0"
  391. plist-xml-lwt
  392. plotkicadsch
  393. posix-getopt >= "4.0.2"
  394. ppx_defer >= "0.4.0"
  395. ppx_deriving_rpc
  396. ppx_rapper_lwt
  397. proc-smaps
  398. prof_spacetime
  399. prometheus
  400. prometheus-app
  401. promise_jsoo_lwt
  402. protocol-9p
  403. protocol-9p-unix
  404. proton
  405. pxshot
  406. qcow
  407. qcow-stream
  408. qcow-tool
  409. qcow-types
  410. qdrant < "0.2.0"
  411. qfs
  412. quests
  413. quickterface
  414. rawlink < "2.1"
  415. rawlink-lwt
  416. rdf_json_ld
  417. rdf_lwt
  418. redis-lwt
  419. reparse-lwt
  420. reparse-lwt-unix
  421. resource-pooling
  422. resp
  423. resp-mirage >= "0.10.0"
  424. resp-unix >= "0.10.0"
  425. resto
  426. resto-cohttp-client >= "0.4"
  427. resto-cohttp-self-serving-client
  428. resto-cohttp-server >= "0.4" & < "0.6" | >= "0.9"
  429. resto-directory >= "0.4"
  430. ringo-lwt
  431. river
  432. rock
  433. rpclib-js
  434. rpclib-lwt
  435. SZXX < "4.0.0"
  436. sanddb
  437. scgi
  438. sendmail-lwt
  439. sendmail-mirage
  440. serial
  441. server-reason-react < "0.4.0"
  442. session-cohttp-lwt
  443. session-cookie-lwt
  444. session-postgresql-lwt
  445. sessions
  446. shared-block-ring
  447. shared-memory-ring-lwt
  448. sherlodoc
  449. sihl < "0.2.0"
  450. slack
  451. slacko
  452. slipshow
  453. smtml >= "0.7.0"
  454. speed
  455. spin < "0.8.0"
  456. spoke
  457. statocaml
  458. stk
  459. stog
  460. swapfs
  461. syguslib-utils
  462. syndic >= "1.4" & < "1.6.0"
  463. tar-mirage
  464. tar-unix
  465. tcpip
  466. telegraml
  467. terminus
  468. testcontainers
  469. testo-lwt
  470. tezt
  471. tidy_email
  472. timmy-lwt
  473. tls >= "0.10.6" & < "0.16.0"
  474. tls-lwt
  475. tls-mirage
  476. tube
  477. tuntap
  478. twirp_cohttp_lwt_unix
  479. uring
  480. uspf
  481. uspf-lwt
  482. uspf-mirage
  483. utcp
  484. utop
  485. uwt
  486. vchan
  487. vchan-unix
  488. vchan-xen
  489. vercel
  490. vhd-format-lwt
  491. vmnet
  492. vue-jsoo < "0.3"
  493. wayland < "2.0"
  494. webauthn
  495. xen-evtchn
  496. xen-evtchn-unix
  497. xen-gnt
  498. xen-gnt-unix
  499. xenstore
  500. xenstore-tool
  501. xenstore_transport
  502. xlsx2csv
  503. yocaml_git
  504. yocaml_unix < "2.0.0"
  505. zarr-lwt
  506. zmq-lwt >= "5.2.1"

Conflicts

None