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

Sources

2.7.0.tar.gz
sha256=00419834e0c5601b3fee6ca9efb0e10ab797a9ff8f695bf2434d89395b7252ec
md5=cee770cf9edbda92578c873e7e4c6105

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: 06 Jan 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.


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

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