package lwt

  1. Overview
  2. Docs
Promises and event-driven I/O

Install

Dune Dependency

Authors

Maintainers

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.