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.6.1.tar.gz
md5=279024789a0ec84a9d97d98bad847f97
sha512=698875bd3bfcd5baa47eb48e412f442d289f9972421321541860ebe110b9af1949c3fbc253768495726ec547fe4ba25483cd97ff39bc668496fba95b2ed9edd8

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: 29 Jun 2022

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

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