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

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. c3
  31. cachet-lwt
  32. calculon
  33. caldav
  34. camltc
  35. canary
  36. capnp-rpc-lwt < "2.0"
  37. capnp-rpc-unix >= "0.9.0" & < "2.0"
  38. caqti-lwt >= "0.11.0"
  39. caqti-mirage
  40. carton < "1.0.0"
  41. carton-git
  42. carton-lwt
  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 >= "0.11.0"
  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 >= "1.1.1"
  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. datakit-client >= "0.11.0"
  87. datakit-github
  88. devkit >= "1.2"
  89. distributed-lwt
  90. dkim-bin >= "0.6.0"
  91. dkim-mirage
  92. dlm
  93. dns-certify
  94. dns-cli >= "4.6.3"
  95. dns-client < "7.0.0"
  96. dns-client-lwt
  97. dns-client-mirage
  98. dns-forward
  99. dns-forward-lwt-unix
  100. dns-lwt
  101. dns-mirage
  102. dns-resolver
  103. dns-server
  104. dns-stub
  105. dnssd
  106. docker_hub
  107. docteur >= "0.0.2"
  108. docteur-solo5
  109. docteur-unix >= "0.0.5"
  110. doi2bib
  111. dream
  112. dream-httpaf
  113. dream-pure
  114. dream-serve
  115. dropbox
  116. dune >= "3.17.0"
  117. dune-rpc-lwt >= "3.7.0" & != "3.10.0"
  118. dune_watch
  119. earlybird
  120. elasticsearch-cli >= "0.4"
  121. equinoxe
  122. ethernet
  123. ez_api >= "1.2.0"
  124. ezcurl-lwt
  125. ezjs_min < "0.2"
  126. ezjsonm-lwt
  127. ezresto
  128. ezresto-directory >= "0.5"
  129. faraday-lwt
  130. faraday-lwt-unix >= "0.6.0"
  131. fat-filesystem
  132. fiber-lwt
  133. flowtype >= "0.72.0"
  134. fsevents-lwt
  135. fswatch_lwt
  136. fuseau-lwt
  137. gamepad
  138. gdbprofiler >= "0.3"
  139. git
  140. git-cohttp
  141. git-cohttp-mirage
  142. git-cohttp-unix
  143. git-mirage >= "3.0.0"
  144. git-paf
  145. git-unix >= "3.0.0"
  146. github
  147. github-hooks >= "0.4.0"
  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 >= "1.0.2"
  178. i3ipc >= "0.1.4"
  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 >= "2.3.0"
  197. irmin-git >= "2.3.0"
  198. irmin-graphql >= "2.3.0"
  199. irmin-http >= "2.3.0"
  200. irmin-indexeddb
  201. irmin-layers
  202. irmin-mem >= "2.3.0"
  203. irmin-mirage-git >= "2.3.0"
  204. irmin-mirage-graphql >= "2.3.0"
  205. irmin-pack
  206. irmin-server
  207. irmin-test >= "2.3.0"
  208. irmin-unix >= "2.3.0"
  209. irmin-watcher >= "0.3.0"
  210. jerboa
  211. joolog
  212. jose < "0.9.0"
  213. js_of_ocaml-lwt >= "3.5.0"
  214. jsoo_broadcastchannel
  215. jsoo_storage
  216. jupyter >= "2.3.0"
  217. jupyter-kernel
  218. kafka < "0.5"
  219. kafka_lwt
  220. kappa-library
  221. ke >= "0.5"
  222. kinetic-client < "0.0.3" | >= "0.0.9"
  223. kubecaml
  224. lablqml < "0.6"
  225. lambda-runtime
  226. lambda-term >= "1.13"
  227. lambda_streams_lwt
  228. launchd
  229. ldp
  230. learn-ocaml
  231. learn-ocaml-client
  232. ledgerwallet >= "0.4.0"
  233. letsencrypt
  234. letsencrypt-app
  235. letsencrypt-dns
  236. letters
  237. links != "0.9"
  238. linol-lwt
  239. llama
  240. lru_cache
  241. lwt-canceler
  242. lwt-dllist
  243. lwt-exit
  244. lwt-parallel >= "1.0.0"
  245. lwt-pipe
  246. lwt-pipeline
  247. lwt-watcher
  248. lwt_camlp4
  249. lwt_domain
  250. lwt_eio
  251. lwt_glib
  252. lwt_log >= "1.1.0"
  253. lwt_ppx
  254. lwt_react
  255. lwt_retry
  256. lwt_ssl
  257. mariadb >= "1.2.0"
  258. markup = "0.7.6"
  259. markup-lwt
  260. mdx
  261. mechaml
  262. mehari-lwt-unix
  263. mehari-mirage
  264. memtrace-mirage
  265. metrics-influx
  266. metrics-lwt
  267. metrics-mirage
  268. metrics-unix
  269. mimic
  270. mindstorm-lwt
  271. mirage < "3.1.1"
  272. mirage-block >= "2.0.1"
  273. mirage-block-ccm
  274. mirage-block-combinators
  275. mirage-block-lwt
  276. mirage-block-partition
  277. mirage-block-ramdisk
  278. mirage-block-solo5
  279. mirage-block-unix = "2.8.2" | >= "2.13.0"
  280. mirage-block-xen
  281. mirage-bootvar-solo5
  282. mirage-bootvar-unix
  283. mirage-bootvar-xen >= "0.4.0"
  284. mirage-channel >= "4.0.1"
  285. mirage-channel-lwt
  286. mirage-clock-freestanding < "3.0.1"
  287. mirage-clock-lwt
  288. mirage-clock-unix >= "1.3.0" & < "3.0.1"
  289. mirage-console >= "3.0.2"
  290. mirage-console-lwt
  291. mirage-console-solo5
  292. mirage-console-unix >= "2.2.1"
  293. mirage-console-xen >= "5.0.0"
  294. mirage-console-xen-backend
  295. mirage-console-xen-cli
  296. mirage-crypto-entropy
  297. mirage-crypto-rng >= "0.8.0" & < "0.11.0"
  298. mirage-crypto-rng-lwt
  299. mirage-crypto-rng-mirage >= "0.8.8"
  300. mirage-device >= "2.0.0"
  301. mirage-entropy
  302. mirage-flow >= "2.0.1"
  303. mirage-flow-combinators
  304. mirage-flow-lwt < "1.3.0" | >= "1.5.0"
  305. mirage-flow-rawlink
  306. mirage-flow-unix >= "1.3.0"
  307. mirage-fs >= "3.0.1"
  308. mirage-fs-lwt
  309. mirage-fs-unix
  310. mirage-kv >= "3.0.1"
  311. mirage-kv-lwt
  312. mirage-kv-unix
  313. mirage-logs != "0.3.0"
  314. mirage-nat < "3.0.0"
  315. mirage-net >= "3.0.1"
  316. mirage-net-fd
  317. mirage-net-lwt
  318. mirage-net-macosx
  319. mirage-net-solo5
  320. mirage-net-unix
  321. mirage-net-xen
  322. mirage-os-shim
  323. mirage-profile
  324. mirage-protocols >= "4.0.1" & < "8.0.0"
  325. mirage-protocols-lwt
  326. mirage-qubes
  327. mirage-qubes-ipv4
  328. mirage-random-stdlib >= "0.1.0"
  329. mirage-runtime >= "3.7.0"
  330. mirage-sleep
  331. mirage-solo5
  332. mirage-stack >= "2.0.1" & < "4.0.0"
  333. mirage-stack-lwt
  334. mirage-time >= "2.0.1"
  335. mirage-time-lwt
  336. mirage-time-unix
  337. mirage-types-lwt < "3.7.1"
  338. mirage-unix
  339. mirage-vnetif
  340. mirage-vnetif-stack
  341. mirage-xen
  342. monorobot
  343. moonpool-lwt
  344. mqtt
  345. mrmime >= "0.5.0"
  346. multipart-form-data >= "0.2.0"
  347. multipart_form >= "0.2.0" & < "0.4.0"
  348. multipart_form-cohttp-lwt < "0.6.0"
  349. multipart_form-lwt
  350. mwt
  351. naboris
  352. nbd >= "4.0.3"
  353. nbd-tool
  354. nbd-unix
  355. netchannel
  356. nocrypto
  357. nottui-lwt
  358. nproc
  359. nsq >= "0.4.0"
  360. obuilder
  361. obus >= "1.2.1"
  362. ocaml-variants >= "4.00.1+mirage-unix" & < "4.00.1+open-types"
  363. ocluster
  364. ocluster-api
  365. ocluster-worker
  366. ocplib-resto
  367. ocsigenserver
  368. ocsipersist
  369. ocsipersist-dbm
  370. ocsipersist-lib
  371. ocsipersist-pgsql
  372. ocsipersist-sqlite
  373. octez-distributed-lwt-internal
  374. octez-internal-libs
  375. octez-l2-libs
  376. octez-libs
  377. octez-proto-libs
  378. octez-protocol-compiler
  379. octez-proxy-server
  380. octez-rpc-process
  381. octez-shell-libs
  382. octez-smart-rollup-wasm-benchmark-lib
  383. odoc >= "2.0.0" & < "2.1.0"
  384. oframl
  385. ojs_base
  386. omigrate
  387. oneffs
  388. opentelemetry-client-cohttp-lwt
  389. opentelemetry-cohttp-lwt >= "0.4"
  390. opentelemetry-lwt
  391. opium >= "0.17.0"
  392. opium-graphql
  393. opium_kernel
  394. opomodoro
  395. order-i3-xfce
  396. ordma >= "0.0.3"
  397. oskel >= "0.3.0"
  398. ounit-lwt < "2.2.0"
  399. ounit2-lwt
  400. owork
  401. ozulip
  402. paf
  403. paf-cohttp
  404. passage
  405. pcap-format < "0.5.0"
  406. petrol
  407. pgx_lwt
  408. pgx_lwt_mirage
  409. pgx_lwt_unix < "2.0"
  410. piaf < "0.2.0"
  411. picos >= "0.3.0" & < "0.5.0"
  412. picos_lwt
  413. picos_meta
  414. plebeia >= "2.0.0"
  415. plist-xml-lwt
  416. plotkicadsch >= "0.4.0"
  417. ppx_defer >= "0.4.0"
  418. ppx_deriving_rpc
  419. ppx_rapper_lwt
  420. ppx_sqlexpr
  421. proc-smaps
  422. prof_spacetime
  423. prometheus
  424. prometheus-app
  425. promise_jsoo_lwt
  426. protocol-9p
  427. protocol-9p-unix
  428. qcow
  429. qcow-tool
  430. qfs = "0.5" | >= "0.7"
  431. quests
  432. rawlink >= "1.0" & < "2.1"
  433. rawlink-lwt
  434. rdf_json_ld
  435. rdf_lwt
  436. redis-lwt
  437. reparse-lwt
  438. reparse-lwt-unix
  439. resource-pooling >= "0.3.2"
  440. resp
  441. resp-mirage >= "0.10.0"
  442. resp-unix >= "0.10.0"
  443. resto
  444. resto-cohttp-client >= "0.4"
  445. resto-cohttp-self-serving-client
  446. resto-cohttp-server >= "0.4" & < "0.6" | >= "0.9"
  447. resto-directory >= "0.4"
  448. riak
  449. ringo-lwt
  450. river
  451. rock
  452. rpc < "7.1.0"
  453. rpclib-js
  454. rpclib-lwt
  455. SZXX < "4.0.0"
  456. sanddb
  457. scgi
  458. sendmail-lwt
  459. sendmail-mirage
  460. serial
  461. server-reason-react
  462. session-cohttp-lwt
  463. session-cookie-lwt
  464. session-postgresql-lwt >= "0.4.1"
  465. sessions
  466. shared-block-ring
  467. shared-memory-ring-lwt
  468. sherlodoc
  469. sihl < "0.2.0"
  470. slack
  471. slacko
  472. slipshow
  473. smtml >= "0.3.1"
  474. speed
  475. spin < "0.8.0"
  476. spoke
  477. sqlexpr
  478. stk
  479. stog
  480. swapfs
  481. syguslib-utils
  482. syndic >= "1.4" & < "1.6.0"
  483. tar-mirage
  484. tar-unix
  485. tcpip < "3.4.1" | >= "4.1.0"
  486. teash
  487. telegraml
  488. terminus
  489. testo-lwt
  490. tezos-base >= "16.0"
  491. tezos-clic >= "16.0"
  492. tezos-crypto >= "16.0"
  493. tezos-crypto-dal
  494. tezos-error-monad >= "16.0"
  495. tezos-lwt-result-stdlib
  496. tezos-p2p = "12.3"
  497. tezos-protocol-environment
  498. tezos-proxy >= "17.3"
  499. tezos-stdlib
  500. tezos-stdlib-unix >= "16.0"
  501. tezos-test-helpers >= "12.3"
  502. tezos-wasmer
  503. tezos-webassembly-interpreter-extra
  504. tezt
  505. tidy_email
  506. timmy-lwt
  507. tls >= "0.10.6" & < "0.16.0"
  508. tls-lwt
  509. tls-mirage
  510. tube >= "4.3.0"
  511. tuntap < "1.7.0" | >= "2.0.0"
  512. twirp_cohttp_lwt_unix
  513. u2f
  514. uring
  515. uspf
  516. uspf-lwt
  517. uspf-mirage
  518. utop
  519. uwt >= "0.3.0"
  520. vchan
  521. vchan-unix
  522. vchan-xen
  523. vercel
  524. vhd-format-lwt >= "0.12.0"
  525. vmnet >= "1.3.2"
  526. vpnkit
  527. vue-jsoo < "0.3"
  528. wayland < "2.0"
  529. webauthn
  530. xen-evtchn >= "2.0.0"
  531. xen-evtchn-unix
  532. xen-gnt
  533. xen-gnt-unix >= "4.0.2"
  534. xenstore
  535. xenstore_transport >= "1.0.0"
  536. xlsx2csv
  537. yocaml_git
  538. yocaml_unix < "2.0.0"
  539. zarr-lwt
  540. 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