package lwt

  1. Overview
  2. Docs
Promises, concurrency, and parallelized I/O

Install

Dune Dependency

Authors

Maintainers

Sources

4.0.1.tar.gz
sha256=97ff4892eea38b2cc3cb9bc764afa31948d7c345a2caf6c60848d5ce60b2de25
md5=d2d1dacf089d7948fd95d9665259a9b6

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: 14 Apr 2018

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 = 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 -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.


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 Gitter chat, ask in #ocaml, on discuss.ocaml.org, or on Stack Overflow. Please do ask! Even apparently simple questions often end up educating other users, not to mention enlightening the maintainers!

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, on the OCaml mailing list, and on discuss.ocaml.org.


Contributing

  • We maintain easy starter issues. These are thoroughly explained and hyperlinked. We hope that this makes working on Lwt accessible even to relative OCaml beginners :)

  • 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.

  • The overall development plan can be found in the roadmap.

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

  • The documentation always needs proofreading and fixes.

  • Despite a lot of progress, Lwt still needs more tests.

  • 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!


License

Lwt is released under the LGPL, with an OpenSSL linking exception. See COPYING.


Related Libraries

  • alcotest A lightweight framework for unit testing

  • angstrom A library for building parsers with a focus on efficiency, concurrency, and reusability

  • cohttp A lightweight library for writing HTTP clients and servers

  • cstruct A library and syntax extension for interop with C-like structures

  • ezjsonm A library for easy interop with JSON

  • faraday A library for fast and memory-efficient serialization

  • logs A logging library with reporting decoupled from logging

  • lwt-parallel A library for distributed computing

  • opium A web toolkit that uses Sinatra-inspired middleware

Dependencies (5)

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

Conflicts (1)

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

Innovation. Community. Security.