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

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