package lwt

  1. Overview
  2. Docs
Monadic promises and concurrent I/O

Install

Dune Dependency

Authors

Maintainers

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