package lwt

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

Install

Dune Dependency

Authors

Maintainers

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

Conflicts

None

OCaml

Innovation. Community. Security.