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
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
  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. hvsock < "1.0.2"
  141. i3ipc
  142. imaplet-lwt
  143. influxdb-lwt
  144. inotify >= "2.4"
  145. inquire < "0.3.0"
  146. iocaml
  147. iocaml-kernel >= "0.4.3"
  148. iocamljs-kernel
  149. ip2location
  150. ip2locationio
  151. ipv6-multicast < "0.9"
  152. irc-client-lwt
  153. irc-client-lwt-ssl
  154. irc-client-tls
  155. irmin < "0.9.6" | = "0.9.10" | >= "0.11.0" & < "2.7.0"
  156. irmin-bench < "2.7.0"
  157. irmin-chunk < "2.7.0"
  158. irmin-containers < "2.7.0"
  159. irmin-fs >= "2.3.0" & < "2.7.0"
  160. irmin-git >= "2.3.0" & < "2.7.0"
  161. irmin-graphql >= "2.3.0" & < "2.7.0"
  162. irmin-http >= "2.3.0" & < "2.7.0"
  163. irmin-indexeddb
  164. irmin-layers < "2.7.0"
  165. irmin-mem >= "2.3.0"
  166. irmin-mirage-git >= "2.3.0" & < "2.7.0"
  167. irmin-mirage-graphql >= "2.3.0" & < "2.7.0"
  168. irmin-pack < "2.7.0"
  169. irmin-test >= "2.3.0" & < "2.7.0"
  170. irmin-unix >= "2.3.0" & < "2.7.0"
  171. irmin-watcher
  172. jitsu
  173. joolog
  174. jose < "0.9.0"
  175. js_of_ocaml < "3.0"
  176. js_of_ocaml-lwt
  177. jsoo_broadcastchannel
  178. jsoo_router
  179. jsoo_storage
  180. jupyter < "1.0.2"
  181. jupyter-archimedes < "2.3.2"
  182. jupyter-kernel
  183. KaSim >= "4.0.0"
  184. kafka >= "0.3" & < "0.5"
  185. kafka_lwt
  186. ke >= "0.5"
  187. ketrew >= "3.0.0"
  188. kinetic-client < "0.0.9"
  189. lablqml < "0.6"
  190. lambda-runtime
  191. lambda-term < "1.13"
  192. launchd
  193. letsencrypt
  194. letsencrypt-app
  195. letsencrypt-dns
  196. libres3
  197. links < "0.7.3"
  198. lru_cache < "v0.16.0"
  199. lwt-binio
  200. lwt-dllist
  201. lwt-exit
  202. lwt-parallel
  203. lwt-pipe
  204. lwt-pipeline
  205. lwt-watcher
  206. lwt-zmq
  207. lwt_camlp4
  208. lwt_eio < "0.4"
  209. lwt_glib < "1.0.1"
  210. lwt_log < "1.1.0"
  211. lwt_named_threads
  212. lwt_ppx
  213. lwt_ppx_let
  214. lwt_react < "1.0.1"
  215. lwt_ssl < "1.0.1"
  216. macaque_lwt
  217. maki
  218. mariadb < "0.5.1"
  219. markup = "0.7.6"
  220. markup-lwt
  221. mbr-format < "1.0.0"
  222. mdx
  223. mechaml
  224. metrics-influx
  225. metrics-lwt
  226. metrics-mirage
  227. metrics-unix
  228. mindstorm-lwt
  229. mirage < "0.9.1" | >= "0.10.0" & < "2.7.0"
  230. mirage-block < "1.0.0"
  231. mirage-block-ccm
  232. mirage-block-lwt
  233. mirage-block-ramdisk
  234. mirage-block-solo5
  235. mirage-block-unix < "2.8.3"
  236. mirage-block-xen
  237. mirage-bootvar-solo5 >= "0.2.0"
  238. mirage-bootvar-unix
  239. mirage-bootvar-xen >= "0.4.0"
  240. mirage-channel-lwt
  241. mirage-clock-freestanding < "3.0.0"
  242. mirage-clock-lwt
  243. mirage-clock-unix >= "1.2.0" & < "3.0.0"
  244. mirage-console >= "2.1.1" & < "2.2.0"
  245. mirage-console-lwt
  246. mirage-console-solo5 >= "0.2.0"
  247. mirage-console-unix >= "2.2.0" & < "3.0.0"
  248. mirage-console-xen >= "5.0.0"
  249. mirage-console-xen-backend < "3.0.1"
  250. mirage-console-xen-cli
  251. mirage-dns < "3.0.0"
  252. mirage-entropy < "0.5.0"
  253. mirage-entropy-unix
  254. mirage-entropy-xen != "0.2.0"
  255. mirage-flow >= "1.0.3" & < "1.2.0"
  256. mirage-flow-lwt
  257. mirage-flow-rawlink
  258. mirage-flow-unix < "2.0.0"
  259. mirage-fs-lwt
  260. mirage-fs-unix != "1.2.1"
  261. mirage-http
  262. mirage-http-unix
  263. mirage-http-xen
  264. mirage-kv-lwt
  265. mirage-kv-unix < "3.0.0"
  266. mirage-logs
  267. mirage-nat < "3.0.0"
  268. mirage-net-fd
  269. mirage-net-lwt
  270. mirage-net-macosx
  271. mirage-net-solo5
  272. mirage-net-unix
  273. mirage-net-xen
  274. mirage-os-shim >= "3.0.0"
  275. mirage-profile
  276. mirage-protocols-lwt
  277. mirage-qubes
  278. mirage-qubes-ipv4
  279. mirage-random-stdlib >= "0.1.0"
  280. mirage-solo5
  281. mirage-stack-lwt
  282. mirage-time-lwt
  283. mirage-time-unix < "2.0.0"
  284. mirage-types-lwt < "3.7.1"
  285. mirage-unix
  286. mirage-vnetif
  287. mirage-vnetif-stack
  288. mirage-www >= "1.1.0"
  289. mirage-xen
  290. mirror
  291. moonpool-lwt
  292. mpris = "0.1.1"
  293. mqtt = "0.0.2"
  294. mrmime >= "0.5.0"
  295. multipart-form-data
  296. multipart_form >= "0.2.0" & < "0.4.0"
  297. multipart_form-lwt < "0.6.0"
  298. mwt
  299. named-pipe
  300. nanomsg
  301. nbd >= "2.1.1"
  302. nbd-tool
  303. nbd-unix
  304. netchannel
  305. nocrypto >= "0.5.4"
  306. noise
  307. nottui-lwt
  308. nproc
  309. nsq < "0.2.4"
  310. obrowser
  311. obuilder < "0.4"
  312. obus < "1.2.0"
  313. ocaml-variants >= "4.00.1+mirage-unix" & < "4.00.1+open-types"
  314. ocluster < "0.2"
  315. ocluster-api < "0.2"
  316. ocplib-concur
  317. ocplib-resto
  318. ocsigen-start = "1.1.0" | >= "4.1.0" & < "4.7.0"
  319. ocsigen-toolkit = "1.1.0"
  320. ocsigenserver >= "2.5" & < "2.9"
  321. odoc >= "2.0.0" & < "2.1.0"
  322. ojquery
  323. ojs-base < "0.6.0"
  324. opam-compiler < "0.2.0"
  325. opam-publish = "0.3.5"
  326. opam-sync-github-prs
  327. openflow < "0.2.0"
  328. opium >= "0.11.0" & < "0.19.0"
  329. opium_kernel
  330. order-i3-xfce
  331. ordma
  332. osc-lwt
  333. oskel >= "0.3.0"
  334. ounit-lwt < "2.2.0"
  335. ounit2-lwt
  336. ox < "1.1.0"
  337. paf
  338. paf-cohttp
  339. pcap-format >= "0.3.3" & < "0.5.0"
  340. pgx_lwt
  341. pgx_lwt_mirage
  342. pgx_lwt_unix < "2.0"
  343. plotkicadsch < "0.2.0" | >= "0.4.0"
  344. ppx_defer >= "0.4.0"
  345. ppx_json_types
  346. ppx_netblob
  347. ppx_rapper_lwt
  348. ppx_sqlexpr
  349. prof_spacetime
  350. prometheus
  351. prometheus-app
  352. promise_jsoo_lwt
  353. protocol-9p < "0.10.0"
  354. pvem_lwt_unix >= "0.0.2"
  355. qcow < "0.11.0"
  356. qcow-format
  357. qcow-tool
  358. qfs >= "0.5" & < "0.7"
  359. quests
  360. rashell
  361. rawlink < "2.1"
  362. rawlink-lwt
  363. receive-mail
  364. redis-lwt
  365. resource-pooling
  366. resp >= "0.10.0"
  367. resp-mirage >= "0.10.0"
  368. resp-unix >= "0.10.0"
  369. resto
  370. riak
  371. ringo-lwt
  372. river
  373. rpc >= "1.5.1" & < "7.1.0"
  374. rpclib-js
  375. sanddb >= "0.3.0"
  376. scgi
  377. sendmail-lwt
  378. session-cohttp-lwt
  379. session-cookie-lwt
  380. session-postgresql-lwt < "0.4.1"
  381. sessions
  382. shared-block-ring
  383. shared-memory-ring < "2.0.0"
  384. shared-memory-ring-lwt
  385. skkserv-lite
  386. slacko < "0.14.1"
  387. sociaml-facebook-api
  388. sociaml-oauth-client
  389. sociaml-tumblr-api
  390. socket-daemon
  391. spin < "0.6.0"
  392. spotify-cli
  393. spotify-web-api < "0.2.1"
  394. sqlexpr
  395. statsd-client
  396. stog >= "0.16.0" & < "0.19.0"
  397. syndic >= "1.4" & < "1.6.0"
  398. tar-format >= "0.4.1"
  399. tar-mirage < "2.2.0"
  400. tar-unix
  401. tcpip >= "2.5.0" & < "3.3.0"
  402. telegraml
  403. testrunner
  404. tezos-p2p >= "11.0" & < "13.0"
  405. tezos-stdlib < "9.0"
  406. tftp
  407. themoviedb
  408. tls >= "0.10.1" & < "0.11.0"
  409. transmission-rpc
  410. tube
  411. tuntap >= "1.0.0" & < "2.0.0"
  412. typerex-lldb
  413. u2f
  414. usb
  415. usbmux
  416. uspf
  417. uspf-lwt
  418. utop >= "1.4.0"
  419. utp
  420. uwt >= "0.0.2"
  421. vchan >= "0.9.6" & < "2.0.0" | >= "2.0.3"
  422. vchan-unix
  423. vchan-xen
  424. vercel
  425. vhd-format >= "0.6.0" & < "0.9.1"
  426. vhd-format-lwt < "0.12.0"
  427. vhd-tool
  428. vmnet
  429. vpnkit >= "0.1.1"
  430. vue-jsoo < "0.3"
  431. webauthn
  432. websocket < "2.3"
  433. websocket-lwt = "2.11"
  434. xapi-idl
  435. xe
  436. xe-unikernel-upload
  437. xen-api-client
  438. xen-block-driver
  439. xen-evtchn
  440. xen-evtchn-unix
  441. xen-gnt
  442. xenctrl
  443. xenstore
  444. xenstore_transport
  445. xentropyd
  446. yurt != "0.3" & < "0.5"
  447. zbar
  448. 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"