package lwt

  1. Overview
  2. Docs
Promises, concurrency, and parallelized I/O

Install

Dune Dependency

github.com Readme Changelog LGPL with OpenSSL linking exception License Edit opam file Versions (46)

Authors

  1. J
    Jérôme Vouillon
  2. J
    Jérémie Dimino

Maintainers

  1. Anton Bachin
  2. M
    Mauricio Fernandez <mfp@acm.org>
  3. S
    Simon Cruanes <simon.cruanes.2007@m4x.org>

Sources

4.1.0.tar.gz
sha256=974e941f0e9c63200935ebd5e6bd4be5acde3ad1fd067fb7ebe54db952001056
md5=e919bee206f18b3d49250ecf9584fde7

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: 28 Jun 2018

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 -package 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 Gitter chat, ask in #ocaml, on discuss.ocaml.org, or on Stack Overflow. Please do ask! Even apparently simple questions often end up educating other users, not to mention enlightening the maintainers!

Subscribe to the announcements issue to get news about Lwt releases. It is less noisy than watching the whole repository. Announcements are also made in /r/ocaml, and on discuss.ocaml.org.


Contributing

  • We maintain easy starter issues. These are thoroughly explained and hyperlinked. We hope that this makes working on Lwt accessible even to relative OCaml beginners :)

  • 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.

  • The overall development plan can be found in the roadmap.

  • Ask us anything, whether it's about working on Lwt, or any question at all about it :)

  • The documentation always needs proofreading and fixes.

  • Despite a lot of progress, Lwt still needs more tests.

  • 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. result
  2. ocamlfind build & >= "1.7.3-1"
  3. jbuilder >= "1.0+beta14"
  4. cppo build & >= "1.1.0"
  5. ocaml >= "4.02.0" & < "4.08.0"

Dev Dependencies

None

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

Conflicts (1)

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

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct