package lwt

  1. Overview
  2. Docs
Promises and event-driven I/O

Install

Dune Dependency

Authors

Maintainers

Sources

5.2.0.tar.gz
sha256=97c12b3da3d0db019dbdb97950b72f6fd1226ded7519c36ebfe2787574a9b132
md5=d5783fcff4fbfa7f79c9303776e4d144

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: 09 Mar 2020

README

Lwt   

Lwt is a concurrent programming library for OCaml. 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 = Lwt_unix.((List.hd addresses).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,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.


Overview

Lwt compiles to native code on Linux, macOS, Windows, and other systems. It's also routinely compiled to JavaScript for the front end and Node, by js_of_ocaml and BuckleScript.

In Lwt,

  • The core library Lwt provides promises...

  • ...and a few pure-OCaml helpers, such as promise-friendly mutexes, condition variables, and mvars.

  • There is a big Unix binding, Lwt_unix that binds almost every Unix system call. A higher-level module Lwt_io provides nice I/O channels.

  • Lwt_process is for subprocess handling.

  • Lwt_preemptive spawns system threads.

  • The PPX syntax allows using all of the above without going crazy!

  • There are also some other helpers, such as Lwt_react for reactive programming. See the table of contents on the linked manual pages!


Installing

  1. Use your system package manager to install a development libev package. It is often called libev-dev or libev-devel.

  2. opam install conf-libev lwt


Documentation

We are currently working on improving the Lwt documentation (drastically; we are rewriting the manual). In the meantime:

  • The current manual can be found here.

  • Mirage has a nicely-written Lwt tutorial.

  • An example of a simple server written in Lwt.

  • Concurrent Programming with Lwt is a nice source of Lwt examples. They are translations of code from the excellent Real World OCaml, but are just as useful if you are not reading the book.

Note: much of the current manual 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 Discord chat, ask on discuss.ocaml.org, or on Stack Overflow.

Release announcements are made in /r/ocaml, and on discuss.ocaml.org. Watching the repo for "Releases only" is also an option.


Contributing

  • CONTRIBUTING.md contains tips for working on the code, such as how to check the code out, how review works, etc. There is also a high-level outline of the code base.

  • Ask us anything, whether it's about working on Lwt, or any question at all about it :)

  • The documentation always needs proofreading and fixes.

  • You are welcome to pick up any other issue, review a PR, add your opinion, etc.

  • Any feedback is welcome, including how to make contributing easier!


Libraries to use with Lwt

Dependencies (8)

  1. seq
  2. result
  3. ocplib-endian
  4. ocaml >= "4.02.0" & < "4.12"
  5. mmap >= "1.1.0"
  6. dune-configurator
  7. dune >= "1.7.0"
  8. cppo build & >= "1.1.0"

Dev Dependencies (2)

  1. ocamlfind dev & >= "1.7.3-1"
  2. bisect_ppx dev & >= "1.3.0"

  1. 0install >= "2.15.1"
  2. albatross
  3. alcotest-lwt
  4. alcotest-mirage
  5. ambient-context-lwt
  6. amqp-client >= "1.1.0"
  7. amqp-client-lwt
  8. angstrom-lwt-unix
  9. anthill
  10. anycache-lwt
  11. archi-lwt
  12. arp
  13. awa-mirage < "0.2.0"
  14. aws-lwt
  15. aws-s3-lwt
  16. awsm-lwt
  17. azure-cosmos-db
  18. balancer
  19. bastet_lwt
  20. bimage-lwt
  21. bistro
  22. brisk-reconciler
  23. brozip
  24. builder
  25. bun >= "0.3.3"
  26. cachet-lwt
  27. calculon
  28. caldav
  29. camltc
  30. canary
  31. capnp-rpc-lwt < "1.2.3"
  32. capnp-rpc-unix < "1.2.3"
  33. caqti-lwt < "2.0.1"
  34. carton-git < "0.7.2"
  35. carton-lwt < "1.0.0"
  36. catala-format >= "0.2.0"
  37. cf-lwt
  38. charrua-client
  39. charrua-unix
  40. cmdtui-lambda-term
  41. cohttp-lwt < "6.0.0~beta2"
  42. cohttp-lwt-jsoo != "6.1.0"
  43. cohttp-lwt-unix
  44. cohttp-mirage
  45. comby
  46. comby-semantic
  47. conan-lwt
  48. conduit-lwt < "7.0.0"
  49. conduit-lwt-unix < "7.0.0"
  50. cowabloga
  51. crunch
  52. cstruct-lwt
  53. csv-lwt
  54. ctypes >= "0.15.0" & < "0.21.1"
  55. ctypes-foreign >= "0.21.1"
  56. curl_lwt
  57. current < "0.7.1"
  58. current_docker < "0.7.1"
  59. current_examples < "0.7.1"
  60. current_git < "0.7.1"
  61. current_github < "0.7.1"
  62. current_gitlab < "0.7.1"
  63. current_ocluster < "0.2"
  64. current_slack < "0.7.1"
  65. current_web < "0.7.1"
  66. DkSDKFFIOCaml_Std
  67. dap
  68. data-encoding < "0.1.1"
  69. datakit-server
  70. devkit >= "1.2"
  71. distributed-lwt
  72. dkim-lwt-unix
  73. dkim-mirage
  74. dlm
  75. dns-certify
  76. dns-cli
  77. dns-client < "7.0.3"
  78. dns-client-lwt
  79. dns-client-mirage
  80. dns-forward
  81. dns-forward-lwt-unix
  82. dns-lwt
  83. dns-mirage
  84. dns-resolver
  85. dns-server
  86. dns-stub
  87. dnssd
  88. docker_hub
  89. dream
  90. dream-httpaf
  91. dream-pure
  92. dropbox
  93. dune >= "3.17.2"
  94. elasticsearch-cli
  95. emoji >= "2.0.0"
  96. ethernet
  97. ez_api
  98. ezcurl-lwt
  99. ezjs_min < "0.2"
  100. ezjsonm-lwt
  101. ezresto
  102. ezresto-directory >= "0.5"
  103. faraday-lwt
  104. faraday-lwt-unix
  105. fat-filesystem
  106. fiber-lwt
  107. fsevents-lwt
  108. fswatch_lwt
  109. fuseau-lwt
  110. gdbprofiler
  111. git
  112. git-paf
  113. git-unix >= "3.2.0" & < "3.15.0"
  114. github
  115. github-hooks
  116. github-unix >= "4.4.0"
  117. gitlab-unix
  118. gluten-lwt
  119. gluten-lwt-unix < "0.4.0"
  120. gluten-mirage < "0.4.0"
  121. graphql-lwt
  122. gremlin
  123. gufo
  124. h1
  125. h1-lwt-unix
  126. h2-lwt
  127. h2-lwt-unix < "0.10.0"
  128. h2-mirage
  129. happy-eyeballs-lwt
  130. happy-eyeballs-mirage
  131. hiredis >= "0.6"
  132. hl_yaml
  133. http-lwt-client
  134. http-multipart-formdata >= "2.0.0" & < "3.0.0"
  135. httpaf-lwt-unix
  136. httpun-lwt
  137. httpun-mirage
  138. httpun-ws-lwt
  139. hvsock
  140. i3ipc
  141. influxdb-lwt
  142. inotify >= "2.4"
  143. inquire < "0.3.0"
  144. interface-prime-lwt
  145. ip2location
  146. ip2locationio
  147. ip2whois
  148. ipv6-multicast-lwt
  149. irc-client-lwt
  150. irc-client-lwt-ssl
  151. irc-client-tls
  152. irmin < "2.7.1"
  153. irmin-indexeddb
  154. irmin-watcher
  155. joolog
  156. jose < "0.9.0"
  157. js_of_ocaml-lwt >= "3.5.0"
  158. jsoo_broadcastchannel
  159. jsoo_storage
  160. jupyter
  161. jupyter-kernel
  162. kafka < "0.5"
  163. kafka_lwt
  164. kappa-library
  165. ke >= "0.5"
  166. kinetic-client
  167. kubecaml
  168. lambda-runtime
  169. lambda-term
  170. lambda_streams_lwt
  171. launchd
  172. learn-ocaml
  173. learn-ocaml-client
  174. letsencrypt
  175. letsencrypt-app
  176. letsencrypt-dns
  177. letters
  178. links >= "0.9.1"
  179. linol-lwt
  180. lru_cache
  181. lwt-canceler
  182. lwt-dllist
  183. lwt-exit
  184. lwt-parallel
  185. lwt-pipe
  186. lwt-pipeline
  187. lwt-watcher
  188. lwt_camlp4
  189. lwt_domain < "0.3.0"
  190. lwt_eio < "0.4"
  191. lwt_glib
  192. lwt_log
  193. lwt_ppx < "5.8.0"
  194. lwt_react
  195. lwt_ssl
  196. mariadb >= "1.2.0"
  197. markup = "0.7.6"
  198. markup-lwt
  199. mdx
  200. mechaml
  201. metrics-influx
  202. metrics-lwt
  203. metrics-unix
  204. mindstorm-lwt
  205. mirage < "4.0.0"
  206. mirage-block >= "2.0.1"
  207. mirage-block-ccm
  208. mirage-block-combinators
  209. mirage-block-lwt
  210. mirage-block-ramdisk
  211. mirage-block-solo5
  212. mirage-block-unikraft
  213. mirage-block-xen
  214. mirage-channel >= "4.0.1"
  215. mirage-channel-lwt
  216. mirage-clock-lwt
  217. mirage-clock-unix < "4.2.0"
  218. mirage-console-lwt
  219. mirage-crypto-rng < "0.11.3"
  220. mirage-crypto-rng-lwt
  221. mirage-crypto-rng-mirage
  222. mirage-device >= "2.0.0"
  223. mirage-flow >= "3.0.0"
  224. mirage-flow-combinators
  225. mirage-flow-lwt
  226. mirage-flow-unix
  227. mirage-fs >= "4.0.0"
  228. mirage-fs-lwt
  229. mirage-kv >= "3.0.1"
  230. mirage-kv-lwt
  231. mirage-kv-unix < "3.0.0"
  232. mirage-net >= "4.0.0"
  233. mirage-net-lwt
  234. mirage-net-macosx
  235. mirage-net-solo5
  236. mirage-net-unikraft
  237. mirage-net-unix
  238. mirage-net-xen
  239. mirage-profile
  240. mirage-protocols >= "7.0.0"
  241. mirage-protocols-lwt
  242. mirage-runtime
  243. mirage-sleep
  244. mirage-solo5
  245. mirage-stack = "3.0.0"
  246. mirage-stack-lwt
  247. mirage-time >= "3.0.0"
  248. mirage-time-lwt
  249. mirage-time-unix
  250. mirage-types-lwt
  251. mirage-unikraft
  252. mirage-unix
  253. mirage-vnetif
  254. mirage-xen
  255. monorobot
  256. moonpool-lwt
  257. mrmime >= "0.5.0"
  258. multipart-form-data
  259. multipart_form >= "0.2.0" & < "0.4.0"
  260. multipart_form-lwt < "0.6.0"
  261. mwt
  262. naboris
  263. nbd >= "4.0.3"
  264. nbd-tool
  265. nbd-unix
  266. nocrypto
  267. nottui-lwt
  268. nproc
  269. nsq
  270. obuilder < "0.4"
  271. obus >= "1.2.1"
  272. ocluster < "0.2"
  273. ocluster-api < "0.2"
  274. ocplib-resto
  275. ocsigen-start >= "4.1.0" & < "4.7.0"
  276. ocsigenserver
  277. ocsipersist
  278. ocsipersist-dbm
  279. ocsipersist-lib
  280. ocsipersist-pgsql
  281. ocsipersist-sqlite
  282. opam-compiler < "0.2.0"
  283. opium < "0.19.0"
  284. opium_kernel
  285. opomodoro
  286. order-i3-xfce
  287. ordma
  288. osc-lwt
  289. oskel >= "0.3.0"
  290. ounit-lwt < "2.2.0"
  291. ounit2-lwt
  292. owork
  293. paf
  294. paf-cohttp
  295. passage
  296. pcap-format < "0.5.2"
  297. pgx_lwt
  298. pgx_lwt_mirage
  299. pgx_lwt_unix < "2.0"
  300. plist-xml-lwt
  301. plotkicadsch
  302. ppx_defer >= "0.4.0"
  303. ppx_deriving_rpc
  304. ppx_rapper_lwt
  305. prof_spacetime
  306. prometheus
  307. prometheus-app
  308. promise_jsoo_lwt
  309. protocol-9p
  310. protocol-9p-unix
  311. qcow < "0.12.1"
  312. qcow-tool
  313. qcow-types
  314. qfs >= "0.5"
  315. quests
  316. rawlink < "2.1"
  317. rawlink-lwt
  318. redis-lwt
  319. resource-pooling
  320. resp
  321. resp-mirage >= "0.10.0"
  322. resp-unix >= "0.10.0"
  323. resto
  324. resto-cohttp-client >= "0.4"
  325. resto-cohttp-self-serving-client
  326. resto-cohttp-server >= "0.4"
  327. resto-directory >= "0.4"
  328. riak
  329. ringo-lwt
  330. river
  331. rpclib-js
  332. rpclib-lwt
  333. SZXX < "2.0.0"
  334. sanddb
  335. scgi
  336. sendmail-lwt
  337. sendmail-mirage
  338. serial
  339. session-cohttp-lwt
  340. session-cookie-lwt
  341. session-postgresql-lwt
  342. sessions
  343. shared-block-ring
  344. shared-memory-ring-lwt
  345. slack
  346. slacko
  347. slipshow
  348. smtml
  349. speed
  350. spin < "0.6.0"
  351. stog < "0.19.0"
  352. syndic >= "1.4" & < "1.6.0"
  353. tar-unix < "3.3.0"
  354. tcpip
  355. telegraml
  356. tezos-lwt-result-stdlib < "12.3"
  357. tezos-p2p = "12.3"
  358. timmy-lwt
  359. tls >= "0.10.6" & < "0.16.0"
  360. tls-lwt < "0.17.5"
  361. tls-mirage
  362. tube
  363. tuntap
  364. twirp_cohttp_lwt_unix
  365. uring
  366. uspf
  367. uspf-lwt
  368. uspf-mirage
  369. utop
  370. uwt
  371. vchan
  372. vchan-unix
  373. vchan-xen
  374. vercel
  375. vhd-format-lwt
  376. vmnet
  377. vpnkit
  378. vue-jsoo < "0.3"
  379. webauthn
  380. xen-evtchn
  381. xen-evtchn-unix
  382. xen-gnt
  383. xen-gnt-unix
  384. xenstore
  385. xenstore_transport
  386. xlsx2csv
  387. zarr-lwt
  388. zmq-lwt

Conflicts (1)

  1. ocaml-variants = "4.02.1+BER"
OCaml

Innovation. Community. Security.