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