package lwt

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

Install

Dune Dependency

Authors

Maintainers

Sources

5.5.0.tar.gz
md5=94272fac89c5bf21a89c102b8a8f35a5
sha512=8951b94555e930634375816d71815b9d85daad6ffb7dab24864661504d11be26575ab0b237196c54693efa372a9b69cdc1d5068a20a250dc0bbb4a3c03c5fda1

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: 26 Nov 2021

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 (10)

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

Conflicts (1)

  1. ocaml-variants = "4.02.1+BER"
OCaml

Innovation. Community. Security.