package lwt

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

Install 

dune-project
 Dependency

github.com Readme MIT License Edit opam file Versions (27)

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

version GitHub Actions status

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

Conflicts

None