package lwt

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

Install

Dune Dependency

Authors

Maintainers

Sources

4.5.0.tar.gz
sha256=e07d845cd8b105802d975e9d09deee09dcfadbb66d2455d81f09608e42786186
md5=1b2fa7df39a70be1925acdabb8b3f8aa

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 Dec 2019

README

Lwt   

Lwt is OCaml's concurrent programming library. 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:

let () =
  let request =
    let%lwt 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%lwt () = write outgoing "GET / HTTP/1.1\r\n" in
      let%lwt () = write outgoing "Connection: close\r\n\r\n" in
      let%lwt response = read incoming in
      Lwt.return (Some response)))
  in

  let timeout =
    let%lwt () = 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,lwt_ppx -linkpkg -o request example.ml
   ./request *)

In the program, functions such as Lwt_io.write create promises. The let%lwt ... 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 and BuckleScript.

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

  1. seq
  2. result
  3. ocplib-endian
  4. ocaml >= "4.02.0" & < "4.12"
  5. mmap >= "1.1.0"
  6. dune-configurator
  7. dune >= "1.7.0"
  8. cppo build & >= "1.1.0"

Dev Dependencies (2)

  1. ocamlfind dev & >= "1.7.3-1"
  2. bisect_ppx dev & >= "1.3.0"

  1. 0install >= "2.14"
  2. albatross
  3. alcotest-lwt
  4. alcotest-mirage
  5. ambient-context-lwt
  6. amqp-client >= "0.9.0" & < "1.0.2" | >= "1.1.0"
  7. amqp-client-lwt >= "2.0.1"
  8. angstrom-lwt-unix
  9. anthill
  10. anycache-lwt
  11. arakoon < "1.8.6" | >= "1.8.8"
  12. archi-lwt
  13. arp >= "2.3.1"
  14. arp-mirage
  15. awa-lwt
  16. awa-mirage < "0.2.0"
  17. aws-lwt
  18. aws-s3-lwt
  19. awsm-lwt
  20. azure-cosmos-db
  21. baardskeerder
  22. balancer
  23. bap < "1.0.0"
  24. bap-server != "0.2.0"
  25. bimage-lwt
  26. biocaml = "0.4.0"
  27. bistro >= "0.4.0"
  28. brozip
  29. builder
  30. bun >= "0.3.3"
  31. c3
  32. calculon
  33. caldav
  34. camltc = "0.9.5" | >= "0.9.7.0"
  35. canary
  36. capnp-rpc-lwt < "1.2.3"
  37. capnp-rpc-unix >= "0.9.0" & < "1.2.3"
  38. caqti-lwt >= "0.11.0" & < "2.0.1"
  39. carton-git < "0.7.2"
  40. carton-lwt
  41. cf-lwt
  42. channel
  43. charrua-client >= "1.3.0"
  44. charrua-client-lwt
  45. charrua-client-mirage
  46. charrua-core < "0.3"
  47. charrua-unix >= "0.3" & != "0.10"
  48. cmdtui-lambda-term
  49. coclobas
  50. cohttp-lwt < "6.0.0~alpha2"
  51. cohttp-lwt-jsoo
  52. cohttp-lwt-unix >= "1.1.1"
  53. cohttp-lwt-unix-nossl
  54. cohttp-lwt-unix-ssl
  55. cohttp-mirage
  56. comby
  57. comby-semantic
  58. conan-lwt
  59. conduit-lwt < "7.0.0"
  60. conduit-lwt-unix < "7.0.0"
  61. core-lwt >= "0.3.0"
  62. cowabloga >= "0.2.2"
  63. crunch >= "2.0.0"
  64. cstruct-lwt
  65. csv-lwt
  66. csvprovider
  67. ctypes >= "0.15.0" & < "0.21.1"
  68. ctypes-foreign >= "0.21.1"
  69. current < "0.6.4"
  70. current_docker < "0.6.4"
  71. current_examples < "0.6.4"
  72. current_git < "0.6.4"
  73. current_github < "0.6.4"
  74. current_gitlab < "0.6.4"
  75. current_ocluster < "0.2"
  76. current_slack < "0.6.4"
  77. current_web < "0.6.4"
  78. DkSDKFFIOCaml_Std
  79. dap
  80. data-encoding < "0.1.1"
  81. datakit
  82. datakit-bridge-github
  83. datakit-bridge-local-git
  84. datakit-ci
  85. datakit-client >= "0.11.0"
  86. datakit-github
  87. datakit-server
  88. devkit >= "0.6"
  89. dht < "0.2.0"
  90. distributed-lwt
  91. dkim-mirage
  92. dlm
  93. dns >= "0.19.1" & < "0.20.1"
  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 >= "0.9.0"
  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. dream
  109. dream-httpaf
  110. dream-pure
  111. dropbox
  112. dune_watch
  113. earlybird < "1.0.0"
  114. elasticsearch-cli >= "0.4"
  115. eris-lwt
  116. ethernet
  117. ez_api
  118. ezcurl-lwt
  119. ezirmin
  120. ezjsonm >= "0.4.2" & < "0.5.0"
  121. ezjsonm-lwt
  122. ezresto
  123. ezresto-directory
  124. faraday-lwt
  125. faraday-lwt-unix >= "0.6.0"
  126. fat-filesystem >= "0.12.0"
  127. fiber-lwt
  128. flowtype >= "0.72.0"
  129. frenetic < "2.0.0"
  130. fswatch_lwt
  131. fuseau-lwt
  132. gamepad
  133. gdb
  134. gdbprofiler >= "0.3"
  135. git != "1.4.3" & != "1.7.2"
  136. git-paf
  137. git-unix = "1.11.1" | >= "3.0.0" & < "3.10.0"
  138. github
  139. github-hooks < "0.2.0" | >= "0.4.0"
  140. github-unix >= "4.4.0"
  141. gitlab-unix
  142. gluten-lwt < "0.4.0"
  143. gluten-lwt-unix < "0.4.0"
  144. gluten-mirage < "0.4.0"
  145. graphql-lwt
  146. gremlin
  147. gufo
  148. h1
  149. h1-lwt-unix
  150. h2-lwt < "0.10.0"
  151. h2-lwt-unix < "0.10.0"
  152. h2-mirage
  153. happy-eyeballs-lwt
  154. happy-eyeballs-mirage
  155. hardcaml < "1.1.0"
  156. hardcaml-examples >= "0.3.0"
  157. hardcaml-framework
  158. hiredis
  159. hl_yaml
  160. horned_worm < "0.3.1"
  161. http-lwt-client
  162. http-multipart-formdata >= "2.0.0" & < "3.0.0"
  163. http2https
  164. httpaf-lwt-unix
  165. httpun-lwt
  166. httpun-mirage
  167. httpun-ws-lwt
  168. hvsock >= "1.0.2"
  169. i3ipc >= "0.1.4"
  170. imaplet-lwt
  171. influxdb-lwt
  172. inotify >= "2.4"
  173. inquire < "0.3.0"
  174. interface-prime-lwt
  175. iocaml < "0.4.6"
  176. iocaml-kernel >= "0.4.3" & < "0.4.6"
  177. iocamljs-kernel
  178. ip2location
  179. ip2locationio
  180. ip2whois
  181. ipv6-multicast-lwt
  182. irc-client-lwt
  183. irc-client-lwt-ssl
  184. irc-client-tls
  185. irmin < "0.9.6" | = "0.9.10" | >= "0.11.0" & < "2.7.0"
  186. irmin-bench < "2.7.0"
  187. irmin-chunk < "2.7.0"
  188. irmin-containers < "2.7.0"
  189. irmin-fs >= "2.3.0" & < "2.7.0"
  190. irmin-git >= "2.3.0" & < "2.7.0"
  191. irmin-graphql >= "2.3.0" & < "2.7.0"
  192. irmin-http >= "2.3.0" & < "2.7.0"
  193. irmin-indexeddb
  194. irmin-layers < "2.7.0"
  195. irmin-mem >= "2.3.0"
  196. irmin-mirage-git >= "2.3.0" & < "2.7.0"
  197. irmin-mirage-graphql >= "2.3.0" & < "2.7.0"
  198. irmin-pack < "2.7.0"
  199. irmin-test >= "2.3.0" & < "2.7.0"
  200. irmin-unix >= "2.3.0" & < "2.7.0"
  201. irmin-watcher >= "0.3.0"
  202. jerboa
  203. jitsu
  204. joolog
  205. jose < "0.9.0"
  206. js_of_ocaml < "2.5"
  207. js_of_ocaml-lwt >= "3.2.0"
  208. jsoo_broadcastchannel
  209. jsoo_router
  210. jsoo_storage
  211. jupyter >= "2.3.0"
  212. jupyter-kernel >= "0.4"
  213. kafka >= "0.3" & < "0.5"
  214. kafka_lwt
  215. kappa-library
  216. ke >= "0.5"
  217. ketrew >= "3.2.0"
  218. kinetic-client < "0.0.3" | >= "0.0.9"
  219. kubecaml
  220. lablqml < "0.6"
  221. lambda-runtime
  222. lambda-term >= "1.13"
  223. launchd
  224. learn-ocaml >= "0.13.0"
  225. learn-ocaml-client >= "0.13.0"
  226. letsencrypt
  227. letsencrypt-app
  228. letsencrypt-dns
  229. libres3
  230. links < "0.9.5"
  231. lru_cache < "v0.16.0"
  232. lwt-binio
  233. lwt-canceler
  234. lwt-dllist
  235. lwt-exit
  236. lwt-parallel >= "1.0.0"
  237. lwt-pipe
  238. lwt-pipeline
  239. lwt-watcher
  240. lwt-zmq < "1.0.0" | >= "2.0.1"
  241. lwt_camlp4
  242. lwt_domain < "0.3.0"
  243. lwt_eio < "0.4"
  244. lwt_glib >= "1.0.1"
  245. lwt_log >= "1.1.0"
  246. lwt_named_threads
  247. lwt_ppx
  248. lwt_ppx_let
  249. lwt_react >= "1.0.1"
  250. lwt_ssl >= "1.0.1"
  251. mariadb < "0.5.1"
  252. markup = "0.7.6"
  253. markup-lwt
  254. mdx
  255. mechaml
  256. metrics-influx
  257. metrics-lwt
  258. metrics-mirage
  259. metrics-unix
  260. mindstorm-lwt
  261. mirage >= "0.4.1" & != "0.6.1" & < "0.8.0" | >= "0.10.0" & < "2.7.0"
  262. mirage-block < "1.0.0" | >= "2.0.0"
  263. mirage-block-ccm
  264. mirage-block-combinators
  265. mirage-block-lwt
  266. mirage-block-ramdisk
  267. mirage-block-solo5
  268. mirage-block-unix < "2.3.0" | = "2.8.2"
  269. mirage-block-xen
  270. mirage-bootvar-solo5 >= "0.2.0"
  271. mirage-bootvar-unix
  272. mirage-bootvar-xen >= "0.4.0"
  273. mirage-channel >= "4.0.0"
  274. mirage-channel-lwt
  275. mirage-clock-freestanding < "3.0.0"
  276. mirage-clock-lwt
  277. mirage-clock-unix >= "1.2.0" & < "3.0.0"
  278. mirage-console >= "2.1.1" & < "2.2.0" | >= "3.0.0"
  279. mirage-console-lwt
  280. mirage-console-solo5 >= "0.2.0"
  281. mirage-console-unix >= "2.2.1"
  282. mirage-console-xen >= "5.0.0"
  283. mirage-console-xen-backend
  284. mirage-console-xen-cli
  285. mirage-crypto-entropy
  286. mirage-crypto-rng >= "0.7.0" & < "0.11.0"
  287. mirage-crypto-rng-lwt
  288. mirage-crypto-rng-mirage >= "0.8.8"
  289. mirage-device >= "2.0.0"
  290. mirage-dns < "3.0.0"
  291. mirage-entropy
  292. mirage-flow >= "1.0.3" & < "1.2.0" | >= "2.0.0"
  293. mirage-flow-combinators
  294. mirage-flow-lwt
  295. mirage-flow-rawlink
  296. mirage-flow-unix
  297. mirage-fs >= "3.0.0"
  298. mirage-fs-lwt
  299. mirage-fs-unix < "1.1.1" | >= "1.3.0"
  300. mirage-http
  301. mirage-http-unix
  302. mirage-http-xen
  303. mirage-kv >= "3.0.0"
  304. mirage-kv-lwt
  305. mirage-kv-unix < "3.0.0"
  306. mirage-logs
  307. mirage-nat < "3.0.0"
  308. mirage-net >= "3.0.1"
  309. mirage-net-fd
  310. mirage-net-lwt
  311. mirage-net-macosx
  312. mirage-net-solo5
  313. mirage-net-unix >= "2.2.0"
  314. mirage-net-xen
  315. mirage-os-shim >= "3.0.0"
  316. mirage-profile
  317. mirage-protocols >= "4.0.0" & < "8.0.0"
  318. mirage-protocols-lwt
  319. mirage-qubes < "0.2" | >= "0.4" & < "0.9.4"
  320. mirage-qubes-ipv4 < "0.9.4"
  321. mirage-random-stdlib >= "0.1.0"
  322. mirage-runtime >= "3.7.0"
  323. mirage-solo5
  324. mirage-stack >= "2.0.0" & < "4.0.0"
  325. mirage-stack-lwt
  326. mirage-time >= "2.0.0"
  327. mirage-time-lwt
  328. mirage-time-unix
  329. mirage-types-lwt < "3.7.1"
  330. mirage-unix >= "3.0.0"
  331. mirage-vnetif
  332. mirage-vnetif-stack
  333. mirage-www >= "1.1.0"
  334. mirage-xen
  335. mirror
  336. moonpool-lwt
  337. mqtt = "0.0.2"
  338. mrmime >= "0.5.0"
  339. multipart-form-data >= "0.2.0"
  340. multipart_form >= "0.2.0" & < "0.4.0"
  341. multipart_form-lwt < "0.6.0"
  342. mwt
  343. naboris < "0.1.1"
  344. named-pipe >= "0.3"
  345. nanomsg
  346. nbd = "2.1.1" | >= "3.0.0"
  347. nbd-tool
  348. nbd-unix
  349. netchannel
  350. nocrypto >= "0.5.4"
  351. noise
  352. nottui-lwt
  353. nproc
  354. nsq >= "0.4.0"
  355. obrowser
  356. obuilder < "0.4"
  357. obus >= "1.1.8"
  358. ocaml-variants >= "4.00.1+mirage-unix" & < "4.00.1+open-types"
  359. ocluster < "0.2"
  360. ocluster-api < "0.2"
  361. ocplib-concur
  362. ocplib-resto
  363. ocsigen-start >= "4.1.0" & < "4.7.0"
  364. ocsigenserver >= "2.10"
  365. ocsipersist
  366. ocsipersist-dbm
  367. ocsipersist-lib
  368. ocsipersist-pgsql
  369. ocsipersist-sqlite
  370. odoc >= "2.0.0" & < "2.1.0"
  371. ojquery
  372. ojs-base < "0.6.0"
  373. opam-compiler < "0.2.0"
  374. opam-publish = "0.3.5"
  375. opam-sync-github-prs
  376. openflow < "0.2.0"
  377. opium >= "0.11.0" & != "0.16.0" & < "0.19.0"
  378. opium_kernel
  379. opomodoro
  380. order-i3-xfce
  381. ordma >= "0.0.3"
  382. osc-lwt
  383. oskel >= "0.3.0"
  384. ounit-lwt < "2.2.0"
  385. ounit2-lwt
  386. owork
  387. ox < "1.1.0"
  388. paf
  389. paf-cohttp
  390. passage
  391. pcap-format >= "0.3.3" & < "0.5.0"
  392. pgx_lwt
  393. pgx_lwt_mirage
  394. pgx_lwt_unix < "2.0"
  395. plotkicadsch >= "0.4.0"
  396. ppx_defer >= "0.4.0"
  397. ppx_deriving_rpc
  398. ppx_json_types
  399. ppx_netblob
  400. ppx_rapper_lwt
  401. ppx_sqlexpr
  402. prof_spacetime
  403. prometheus
  404. prometheus-app
  405. promise_jsoo_lwt
  406. protocol-9p >= "0.10.0"
  407. protocol-9p-unix
  408. qcow >= "0.8.1"
  409. qcow-format < "0.3"
  410. qcow-tool
  411. qfs = "0.5" | >= "0.7"
  412. quests
  413. rawlink >= "1.0" & < "2.1"
  414. rawlink-lwt
  415. redis-lwt
  416. resource-pooling >= "0.3.2"
  417. resp
  418. resp-mirage >= "0.10.0"
  419. resp-unix >= "0.10.0"
  420. resto
  421. resto-cohttp-client
  422. resto-cohttp-self-serving-client
  423. resto-cohttp-server
  424. resto-directory
  425. riak
  426. ringo-lwt
  427. river
  428. rpc >= "1.5.1" & < "7.1.0"
  429. rpclib-js
  430. rpclib-lwt
  431. sanddb
  432. scgi
  433. sendmail-lwt
  434. serial
  435. session-cohttp-lwt
  436. session-cookie-lwt
  437. session-postgresql-lwt >= "0.4.1"
  438. sessions
  439. shared-block-ring < "2.3.0" | >= "3.0.0"
  440. shared-memory-ring >= "1.2.0" & < "2.0.0"
  441. shared-memory-ring-lwt
  442. slacko
  443. slipshow
  444. socket-daemon < "0.3.0"
  445. speed
  446. spin < "0.6.0"
  447. spotify-web-api < "0.2.1"
  448. sqlexpr = "0.7.1" | >= "0.9.0"
  449. statsd-client
  450. stog >= "0.16.0" & < "0.19.0"
  451. syndic >= "1.4" & < "1.6.0"
  452. tar-format >= "0.4.1"
  453. tar-mirage < "2.2.0"
  454. tar-unix < "3.0.0"
  455. tcpip >= "3.1.1"
  456. teash
  457. telegraml
  458. tezos-p2p >= "11.0" & < "13.0"
  459. tezos-stdlib < "9.3"
  460. tezos-stdlib-unix < "9.0"
  461. tftp
  462. themoviedb
  463. tls >= "0.10.1" & < "0.16.0"
  464. tls-lwt < "0.17.4"
  465. tls-mirage
  466. tlstunnel >= "0.2.0"
  467. transmission-rpc
  468. tube >= "4.3.0"
  469. tuntap >= "1.0.0" & < "2.0.0"
  470. twirp_cohttp_lwt_unix
  471. typerex-lldb
  472. u2f
  473. uspf
  474. uspf-lwt
  475. utop >= "1.4.0"
  476. uwt >= "0.3.0"
  477. vchan >= "0.9.7" & < "2.0.0" | >= "2.0.3"
  478. vchan-unix
  479. vchan-xen
  480. vercel
  481. vhd-format >= "0.7.0" & < "0.8.0"
  482. vhd-format-lwt >= "0.12.0"
  483. vhd-tool < "0.12.0"
  484. vmnet >= "1.3.2"
  485. vpnkit >= "0.2.0"
  486. vue-jsoo < "0.3"
  487. webauthn
  488. websocket < "2.3"
  489. xe-unikernel-upload
  490. xen-api-client < "0.9.14"
  491. xen-block-driver
  492. xen-evtchn != "1.0.6"
  493. xen-evtchn-unix
  494. xen-gnt >= "2.2.3"
  495. xen-gnt-unix >= "4.0.2"
  496. xenctrl < "0.9.29" | >= "0.9.32"
  497. xenstore >= "1.3.0"
  498. xenstore_transport >= "1.0.0"
  499. xentropyd
  500. yurt < "0.3"
  501. zarr-lwt
  502. zbar
  503. zmq-lwt

Conflicts (1)

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

Innovation. Community. Security.