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 (23)

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.0.tar.gz
md5=763b9201c891f8c20ee02dec0af23355
sha512=35574743df40170a8d1676254952c060090421a40d5f8ad37a6691f4f8bb0e28fca61f5efff1050edc4f8a3ffa2f06a1e23d0c084c89bfc105c1235e249bbc75

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 Nov 2024

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