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.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

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 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.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"
  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-mirage
  143. git-paf
  144. git-unix >= "3.2.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
  196. irmin-git
  197. irmin-graphql
  198. irmin-http
  199. irmin-indexeddb
  200. irmin-layers
  201. irmin-mirage-git
  202. irmin-mirage-graphql
  203. irmin-pack
  204. irmin-server
  205. irmin-test
  206. irmin-unix
  207. irmin-watcher
  208. joolog
  209. jose < "0.9.0"
  210. js_of_ocaml-lwt
  211. jsoo_broadcastchannel
  212. jsoo_storage
  213. jupyter
  214. jupyter-kernel
  215. kafka < "0.5"
  216. kafka_lwt
  217. kappa-library
  218. ke >= "0.5"
  219. kinetic-client
  220. kubecaml
  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 < "2.0.0"
  230. letsencrypt-app
  231. letsencrypt-dns < "2.0.0"
  232. letters
  233. lichess_api
  234. links
  235. linol-lwt
  236. llama
  237. lru_cache
  238. lwt-canceler
  239. lwt-dllist
  240. lwt-exit
  241. lwt-parallel
  242. lwt-pipe
  243. lwt-pipeline
  244. lwt-watcher
  245. lwt_camlp4
  246. lwt_domain
  247. lwt_eio < "0.6"
  248. lwt_glib
  249. lwt_log
  250. lwt_ppx < "6.0.0~beta01"
  251. lwt_react
  252. lwt_retry
  253. lwt_ssl
  254. mariadb >= "1.2.0"
  255. markdown_monolith
  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-unix
  266. mimic
  267. mindstorm-lwt
  268. mirage < "4.0.0"
  269. mirage-block >= "2.0.1"
  270. mirage-block-ccm
  271. mirage-block-combinators
  272. mirage-block-lwt
  273. mirage-block-partition
  274. mirage-block-ramdisk
  275. mirage-block-solo5
  276. mirage-block-unikraft
  277. mirage-block-unix >= "2.14.2"
  278. mirage-block-xen
  279. mirage-channel >= "4.0.1"
  280. mirage-channel-lwt
  281. mirage-clock-lwt
  282. mirage-clock-unix < "4.2.0"
  283. mirage-console-lwt
  284. mirage-crypto-rng < "0.11.3"
  285. mirage-crypto-rng-lwt
  286. mirage-crypto-rng-mirage
  287. mirage-device >= "2.0.0"
  288. mirage-flow >= "3.0.0"
  289. mirage-flow-combinators
  290. mirage-flow-lwt
  291. mirage-flow-unix
  292. mirage-fs >= "4.0.0"
  293. mirage-fs-lwt
  294. mirage-kv >= "3.0.1"
  295. mirage-kv-lwt
  296. mirage-kv-unix
  297. mirage-net >= "4.0.0"
  298. mirage-net-lwt
  299. mirage-net-macosx
  300. mirage-net-solo5
  301. mirage-net-unikraft
  302. mirage-net-unix
  303. mirage-net-xen
  304. mirage-profile
  305. mirage-protocols >= "7.0.0"
  306. mirage-protocols-lwt
  307. mirage-qubes
  308. mirage-qubes-ipv4
  309. mirage-runtime
  310. mirage-sleep
  311. mirage-solo5
  312. mirage-stack = "3.0.0"
  313. mirage-stack-lwt
  314. mirage-time >= "3.0.0"
  315. mirage-time-lwt
  316. mirage-time-unix
  317. mirage-types-lwt
  318. mirage-unikraft
  319. mirage-unix
  320. mirage-vnetif
  321. mirage-xen
  322. monorobot
  323. moonpool-lwt
  324. mqtt
  325. mrmime >= "0.5.0"
  326. multipart-form-data
  327. multipart_form >= "0.2.0" & < "0.4.0"
  328. multipart_form-cohttp-lwt < "0.6.0"
  329. multipart_form-lwt
  330. mwt
  331. naboris
  332. nbd >= "4.0.3"
  333. nbd-tool
  334. nbd-unix
  335. neo4j_bolt
  336. nocrypto
  337. nottui-lwt
  338. notty-community
  339. nproc
  340. nsq
  341. obuilder
  342. obus >= "1.2.1"
  343. ocluster
  344. ocluster-api
  345. ocluster-worker
  346. ocplib-resto
  347. ocsigenserver
  348. ocsipersist
  349. ocsipersist-dbm
  350. ocsipersist-lib
  351. ocsipersist-pgsql
  352. ocsipersist-sqlite
  353. oframl
  354. ojs_base
  355. omigrate
  356. oneffs
  357. opam-check-npm-deps >= "4.1.0"
  358. opam-publish >= "3.0.0"
  359. opencage
  360. opentelemetry-client-cohttp-lwt
  361. opentelemetry-client-ocurl-lwt
  362. opentelemetry-cohttp-lwt >= "0.4"
  363. opentelemetry-lwt
  364. opium
  365. opium-graphql
  366. opium_kernel
  367. opomodoro
  368. order-i3-xfce
  369. ordma
  370. oskel >= "0.3.0"
  371. ounit-lwt < "2.2.0"
  372. ounit2-lwt
  373. owork
  374. ozulip
  375. paf
  376. paf-cohttp
  377. passage < "0.1.8"
  378. pcap-format < "0.5.2"
  379. petrol
  380. pgn_parser
  381. pgx_lwt
  382. pgx_lwt_mirage
  383. pgx_lwt_unix < "2.0"
  384. piaf < "0.2.0"
  385. picos >= "0.3.0" & < "0.5.0"
  386. picos_lwt
  387. picos_meta
  388. plebeia >= "2.0.0"
  389. plist-xml-lwt
  390. plotkicadsch
  391. posix-getopt >= "4.0.2"
  392. ppx_defer >= "0.4.0"
  393. ppx_deriving_rpc
  394. ppx_rapper_lwt
  395. proc-smaps
  396. prof_spacetime
  397. prometheus
  398. prometheus-app
  399. promise_jsoo_lwt
  400. protocol-9p
  401. protocol-9p-unix
  402. proton
  403. pxshot
  404. qcow
  405. qcow-stream
  406. qcow-tool
  407. qcow-types
  408. qdrant < "0.2.0"
  409. qfs
  410. quests
  411. quickterface
  412. rawlink < "2.1"
  413. rawlink-lwt
  414. rdf_json_ld
  415. rdf_lwt
  416. redis-lwt
  417. reparse-lwt
  418. reparse-lwt-unix
  419. resource-pooling
  420. resp
  421. resp-mirage >= "0.10.0"
  422. resp-unix >= "0.10.0"
  423. resto
  424. resto-cohttp-client >= "0.4"
  425. resto-cohttp-self-serving-client
  426. resto-cohttp-server >= "0.4" & < "0.6" | >= "0.9"
  427. resto-directory >= "0.4"
  428. ringo-lwt
  429. river
  430. rock
  431. rpclib-js
  432. rpclib-lwt
  433. SZXX < "4.0.0"
  434. sanddb
  435. scgi
  436. sendmail-lwt
  437. sendmail-mirage
  438. serial
  439. server-reason-react < "0.4.0"
  440. session-cohttp-lwt
  441. session-cookie-lwt
  442. session-postgresql-lwt
  443. sessions
  444. shared-block-ring
  445. shared-memory-ring-lwt
  446. sherlodoc
  447. sihl < "0.2.0"
  448. slack
  449. slacko
  450. slipshow
  451. smtml >= "0.7.0"
  452. speed
  453. spin < "0.8.0"
  454. spoke
  455. stk
  456. stog
  457. swapfs
  458. syguslib-utils
  459. syndic >= "1.4" & < "1.6.0"
  460. tar-mirage
  461. tar-unix
  462. tcpip
  463. telegraml
  464. terminus
  465. testcontainers
  466. testo-lwt
  467. tezt
  468. tidy_email
  469. timmy-lwt
  470. tls >= "0.10.6" & < "0.16.0"
  471. tls-lwt
  472. tls-mirage
  473. tube
  474. tuntap
  475. twirp_cohttp_lwt_unix
  476. uring
  477. uspf
  478. uspf-lwt
  479. uspf-mirage
  480. utcp
  481. utop
  482. uwt
  483. vchan
  484. vchan-unix
  485. vchan-xen
  486. vercel
  487. vhd-format-lwt
  488. vmnet
  489. vue-jsoo < "0.3"
  490. wayland < "2.0"
  491. webauthn
  492. xen-evtchn
  493. xen-evtchn-unix
  494. xen-gnt
  495. xen-gnt-unix
  496. xenstore
  497. xenstore-tool
  498. xenstore_transport
  499. xlsx2csv
  500. yocaml_git
  501. yocaml_unix < "2.0.0"
  502. zarr-lwt
  503. zmq-lwt >= "5.2.1"

Conflicts

None