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.7.0.tar.gz
md5=737039d29d45b2d2b35db6931c8d75c6
sha512=42e629920783428673b99c9d7a639237c9e6b35079b5d907bc67e7ea506acf9edadc48cec580bdcfd2410ed9412bf5e6bcc8b09de2fa7d35ce1490973d05ddd1

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: 17 Aug 2023

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 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. ocaml >= "4.08"
  3. dune-configurator
  4. dune >= "1.8.0"
  5. cppo build & >= "1.1.0"

Dev Dependencies (1)

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