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
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
  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. 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 < "0.9.4"
  278. mirage-qubes-ipv4 < "0.9.4"
  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.2.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. xen-gnt-unix >= "4.0.2"
  443. xenctrl
  444. xenstore
  445. xenstore_transport
  446. xentropyd
  447. yurt != "0.3" & < "0.5"
  448. zbar
  449. 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"