package lwt

  1. Overview
  2. Docs
Monadic promises and concurrent I/O

Install

Dune Dependency

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

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

2.7.1.tar.gz
sha256=43c0541c185f9db4ef7e44703bd75b832dc7a69ccc9905dd413d08563d44d639
md5=fb478fbdb6fda0d1fa64a8a2f9ac1bbb

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: 10 Apr 2017

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 = (List.hd addresses).Lwt_unix.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.


Installing

opam install lwt

Documentation

The manual can be found here. There are also some examples available in doc/examples.

Note: much of the manual still 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, email the maintainer, or ask in #ocaml. If you think enough people will be interested in the answer, it is also possible to ask on Stack Overflow.

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 the OCaml mailing list.


Contributing

Lwt is a very mature library, but there is considerable room for improvement. Contributions are welcome. To clone the source and install a development version,

opam source --dev-repo --pin lwt

This will also install the development dependency OASIS.

A list of project suggestions and a roadmap can be found on the wiki.


License

Lwt is released under the LGPL, with the OpenSSL linking exception. See COPYING.

Dependencies (8)

  1. ppx_tools build
  2. base-no-ppx
  3. cppo_ocamlbuild build
  4. cppo build & >= "1.1.0"
  5. result
  6. ocamlbuild build
  7. ocamlfind build & >= "1.5.0"
  8. ocaml >= "4.02.0" & < "4.06.0"

Dev Dependencies

None

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

Conflicts (5)

  1. ocamlbuild = "0.9.0"
  2. ppx_tools < "1.0.0"
  3. ssl < "0.5.0"
  4. react < "1.0.0"
  5. 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