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

3.0.0.tar.gz
sha256=fc1654bb06fdd48180f093f6e05e7264936626a11fef23cc8cf2ca4b5e3d7d44
md5=6c45ce0035f627d0de0d3d185f2a1a7f

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: 19 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.08.0"

Dev Dependencies

None

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

Conflicts (3)

  1. ocamlbuild = "0.9.0"
  2. ppx_tools < "1.0.0"
  3. 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