package lwt

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

Install 

dune-project
 Dependency

github.com Readme MIT License Edit opam file Versions (34)

Authors

  1. J
    Jérôme Vouillon
  2. J
    Jérémie Dimino

Maintainers

  1. R
    Raphaël Proust <code@bnwr.net>
  2. Anton Bachin

Sources

6.1.2.tar.gz
md5=00bc7eb2772a28530f7365a7040f0c4f
sha512=a4737a2fc44aaeedca46ec6134c07013d5cf44039a988a6e79a40715a53e43601d4c91bbf11a8e89540528d912b8fa487e3068465c136c1156a872258eb3443b

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.

Added to opam-repository:

README

Lwt

version GitHub Actions status

Lwt is a concurrent programming library for OCaml. It provides a single data type: the promise, which is a value that will become resolved 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) ->
      write outgoing "GET / HTTP/1.1\r\n";%lwt
      write outgoing "Connection: close\r\n\r\n";%lwt
      let%lwt response = read incoming in
      Lwt.return (Some response)))
  in

  let timeout =
    Lwt_unix.sleep 5.;%lwt
    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 example.ml && ./a.out *)

If you are not using the lwt_ppx syntax extension, you can use the let* binding opoerators from the Lwt.Syntax module instead.

let () =
  let open Lwt.Syntax in
  let request =
    let* 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* () = write outgoing "GET / HTTP/1.1\r\n" in
      let* () = write outgoing "Connection: close\r\n\r\n" in
      let* response = read incoming in
      Lwt.return (Some response)))
  in

  let timeout =
    let* () = 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 example.ml && ./a.out *)

In the program above, functions such as Lwt_io.write create promises. The let%lwt ... in construct (provided by lwt_ppx) or the let* ... in construct (provided by Lwt.Syntax) are used to wait for a promise to resolve. The code after in is scheduled to run after the code inside the let...in has resolved.

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.

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

  1. ocplib-endian
  2. dune-configurator
  3. cppo build & >= "1.1"
  4. ocaml >= "4.14"
  5. dune >= "3.18"

Dev Dependencies (2)

  1. odoc with-doc & >= "2.3"
  2. ocamlfind dev & >= "1.7.3-1"

  1. 0install >= "2.15.1"
  2. aches-lwt
  3. activitypub
  4. albatross
  5. alcotest-lwt
  6. alcotest-mirage
  7. ambient-context-lwt
  8. amqp-client >= "1.1.0"
  9. amqp-client-lwt
  10. angstrom-lwt-unix >= "0.11.0"
  11. anthill
  12. anycache-lwt
  13. archi-lwt
  14. arp
  15. awa-mirage
  16. aws-lwt
  17. aws-s3-lwt >= "4.8.1"
  18. awskit-lwt
  19. awskit-lwt-unix
  20. awskit-s3-lwt
  21. awskit-s3-lwt-unix
  22. awsm-lwt
  23. awso-lwt
  24. azure-cosmos-db < "0.4.0"
  25. azure-cosmos-db-lwt
  26. balancer
  27. bastet_lwt
  28. bimage-lwt
  29. bistro
  30. bitflyer
  31. bizowie-api
  32. brisk-reconciler
  33. builder
  34. builder-web
  35. bun >= "0.3.3"
  36. cachet-lwt
  37. calculon
  38. caldav
  39. camltc
  40. canary
  41. capnp-rpc-lwt < "2.0"
  42. capnp-rpc-unix < "2.1"
  43. caqti-lwt
  44. caqti-mirage
  45. carton < "1.0.0"
  46. carton-git
  47. carton-lwt
  48. catala-format >= "0.2.0"
  49. cf-lwt
  50. chamelon
  51. chamelon-unix
  52. chamo
  53. charrua-client
  54. charrua-unix
  55. chess_com_api
  56. ciao_lwt
  57. clz
  58. cmdtui-lambda-term
  59. coap
  60. coap-server-lwt
  61. cohttp-curl-lwt
  62. cohttp-lwt
  63. cohttp-lwt-jsoo
  64. cohttp-lwt-unix
  65. cohttp-mirage
  66. cohttp-server-lwt-unix
  67. comby
  68. comby-semantic
  69. conan-lwt
  70. conduit-lwt
  71. conduit-lwt-unix
  72. cowabloga
  73. crunch
  74. cstruct-lwt
  75. csv-lwt
  76. ctypes >= "0.15.0" & < "0.21.1"
  77. ctypes-foreign >= "0.21.1"
  78. curl_lwt
  79. current
  80. current-albatross-deployer
  81. current_docker
  82. current_examples
  83. current_git
  84. current_github
  85. current_gitlab
  86. current_ocluster
  87. current_rpc
  88. current_slack
  89. current_web
  90. dap
  91. data-encoding < "0.1.1"
  92. devkit >= "1.2"
  93. distributed-lwt
  94. dkim-bin < "0.8.0"
  95. dkim-lwt-unix
  96. dkim-mirage
  97. dlm
  98. dmarc
  99. dns-certify
  100. dns-cli
  101. dns-client < "7.0.3"
  102. dns-client-lwt
  103. dns-client-mirage
  104. dns-forward
  105. dns-forward-lwt-unix
  106. dns-lwt
  107. dns-mirage
  108. dns-resolver
  109. dns-server
  110. dns-stub
  111. dnsrobot
  112. dnssd
  113. docker_hub
  114. docteur >= "0.0.2"
  115. docteur-solo5
  116. docteur-unix >= "0.0.5"
  117. doi2bib
  118. dream
  119. dream-httpaf
  120. dream-pure
  121. dream-serve < "1.0.1"
  122. dropbox
  123. dune >= "3.17.2"
  124. dune-rpc-lwt
  125. earlybird
  126. elasticsearch-cli
  127. emoji = "2.0.0"
  128. equinoxe
  129. ethernet
  130. ez_api >= "1.2.0" & < "3.0.0"
  131. ezcurl-lwt
  132. ezjs_min < "0.2"
  133. ezjsonm-lwt
  134. ezresto
  135. faraday-lwt
  136. faraday-lwt-unix
  137. fat-filesystem
  138. fiber-lwt
  139. fsevents-lwt
  140. fswatch_lwt
  141. fxmacrodata
  142. gdbprofiler
  143. git
  144. git-cohttp
  145. git-cohttp-unix
  146. git-kv >= "0.2.0"
  147. git-mirage
  148. git-paf
  149. git-unix >= "3.2.0"
  150. github
  151. github-hooks
  152. github-unix >= "4.4.0"
  153. gitlab-unix
  154. gitlab_pipeline_notifier
  155. gluten-lwt
  156. gluten-lwt-unix < "0.4.0"
  157. gluten-mirage < "0.4.0"
  158. gmocoin
  159. granary
  160. granary_repl
  161. graphql-lwt
  162. gremlin
  163. grpc-lwt
  164. guardian
  165. gufo
  166. h1
  167. h1-lwt-unix
  168. h2-lwt
  169. h2-lwt-unix < "0.10.0"
  170. h2-mirage
  171. happy-eyeballs-lwt
  172. happy-eyeballs-mirage
  173. hidapi-lwt
  174. hiredis >= "0.6"
  175. hl_yaml
  176. hockmd
  177. http-lwt-client
  178. http-mirage-client
  179. http-multipart-formdata >= "2.0.0" & < "3.0.0"
  180. httpaf-lwt-unix
  181. httpun-lwt
  182. httpun-mirage
  183. httpun-ws-lwt
  184. hvsock
  185. i3ipc
  186. influxdb-lwt
  187. inotify >= "2.4"
  188. inquire < "0.3.0"
  189. interface-prime-lwt
  190. ip2location
  191. ip2locationio
  192. ip2whois
  193. ipv6-multicast-lwt
  194. irc-client-lwt
  195. irc-client-lwt-ssl
  196. irc-client-tls
  197. irmin
  198. irmin-bench
  199. irmin-chunk
  200. irmin-cli
  201. irmin-client
  202. irmin-containers
  203. irmin-fs
  204. irmin-git
  205. irmin-graphql
  206. irmin-http
  207. irmin-indexeddb
  208. irmin-layers
  209. irmin-mirage-git
  210. irmin-mirage-graphql
  211. irmin-pack
  212. irmin-server
  213. irmin-test
  214. irmin-unix
  215. irmin-watcher
  216. joolog
  217. jose < "0.9.0"
  218. js_of_ocaml-lwt
  219. jsoo_broadcastchannel
  220. jsoo_storage
  221. jupyter
  222. jupyter-kernel
  223. kafka < "0.5"
  224. kafka_lwt
  225. kappa-library
  226. ke >= "0.5"
  227. kinetic-client
  228. kubecaml
  229. lambda-runtime
  230. lambda-term >= "3.3.3"
  231. lambda_streams_lwt
  232. launchd
  233. ldp
  234. learn-ocaml
  235. learn-ocaml-client
  236. ledgerwallet >= "0.4.0"
  237. letsencrypt < "2.0.0"
  238. letsencrypt-app
  239. letsencrypt-dns < "2.0.0"
  240. letters
  241. lichess_api
  242. links
  243. llama
  244. lru_cache
  245. lwt-canceler
  246. lwt-dllist
  247. lwt-exit
  248. lwt-parallel
  249. lwt-pipe
  250. lwt-pipeline
  251. lwt-watcher
  252. lwt_camlp4
  253. lwt_direct >= "6.0.0"
  254. lwt_domain != "0.2.0"
  255. lwt_eio >= "0.6"
  256. lwt_ppx >= "6.0.0"
  257. lwt_react
  258. lwt_retry
  259. lwt_ssl
  260. mariadb >= "1.2.0"
  261. markdown_monolith
  262. markup = "0.7.6"
  263. markup-lwt
  264. mdx
  265. mechaml
  266. mehari-lwt-unix
  267. mehari-mirage
  268. memtrace-mirage
  269. metrics-influx
  270. metrics-lwt
  271. metrics-unix
  272. migra
  273. mimic
  274. mindstorm-lwt
  275. mirage < "4.0.0"
  276. mirage-block >= "2.0.1"
  277. mirage-block-ccm
  278. mirage-block-combinators
  279. mirage-block-lwt
  280. mirage-block-partition
  281. mirage-block-ramdisk
  282. mirage-block-solo5
  283. mirage-block-unikraft
  284. mirage-block-unix >= "2.14.2"
  285. mirage-block-xen
  286. mirage-channel >= "4.0.1"
  287. mirage-channel-lwt
  288. mirage-clock-lwt
  289. mirage-clock-unix < "4.2.0"
  290. mirage-console-lwt
  291. mirage-crypto-rng < "0.11.3"
  292. mirage-crypto-rng-lwt
  293. mirage-crypto-rng-mirage
  294. mirage-device >= "2.0.0"
  295. mirage-flow >= "3.0.0"
  296. mirage-flow-combinators
  297. mirage-flow-lwt
  298. mirage-flow-unix
  299. mirage-fs >= "4.0.0"
  300. mirage-fs-lwt
  301. mirage-kv >= "3.0.1"
  302. mirage-kv-lwt
  303. mirage-kv-unix
  304. mirage-net >= "4.0.0"
  305. mirage-net-lwt
  306. mirage-net-macosx
  307. mirage-net-solo5
  308. mirage-net-unikraft
  309. mirage-net-unix
  310. mirage-net-xen
  311. mirage-profile
  312. mirage-protocols >= "7.0.0"
  313. mirage-protocols-lwt
  314. mirage-qubes
  315. mirage-qubes-ipv4
  316. mirage-runtime
  317. mirage-sleep
  318. mirage-solo5
  319. mirage-stack = "3.0.0"
  320. mirage-stack-lwt
  321. mirage-time >= "3.0.0"
  322. mirage-time-lwt
  323. mirage-time-unix
  324. mirage-types-lwt
  325. mirage-unikraft
  326. mirage-unix
  327. mirage-vnetif
  328. mirage-xen
  329. monorobot
  330. mqtt
  331. mrmime >= "0.5.0"
  332. multipart-form-data
  333. multipart_form >= "0.2.0" & < "0.4.0"
  334. multipart_form-cohttp-lwt < "0.6.0"
  335. multipart_form-lwt
  336. naboris
  337. nbd >= "4.0.3"
  338. nbd-tool
  339. nbd-unix
  340. neo4j_bolt
  341. nottui-lwt
  342. notty-community
  343. nproc
  344. nsq
  345. obuilder
  346. obus >= "1.2.1"
  347. ocaml-ai-sdk
  348. ocluster
  349. ocluster-api
  350. ocluster-worker
  351. ocplib-resto
  352. ocsigenserver
  353. ocsipersist
  354. ocsipersist-dbm
  355. ocsipersist-lib
  356. ocsipersist-pgsql
  357. ocsipersist-sqlite
  358. oframl
  359. ojs_base
  360. omigrate
  361. oneffs
  362. opam-check-npm-deps >= "4.1.0"
  363. opam-publish >= "3.0.0"
  364. opencage
  365. opentelemetry-client-cohttp-lwt
  366. opentelemetry-client-ocurl-lwt
  367. opentelemetry-cohttp-lwt >= "0.4"
  368. opentelemetry-lwt
  369. opium
  370. opium-graphql
  371. opium_kernel
  372. opomodoro
  373. order-i3-xfce
  374. ordma
  375. oskel >= "0.3.0"
  376. ounit-lwt < "2.2.0"
  377. ounit2-lwt
  378. owork
  379. ozulip
  380. paf
  381. paf-cohttp
  382. passage < "0.1.8"
  383. pcap-format < "0.5.2"
  384. petrol
  385. pgn_parser
  386. pgx_lwt
  387. pgx_lwt_mirage
  388. pgx_lwt_unix < "2.0"
  389. piaf < "0.2.0"
  390. picos >= "0.3.0" & < "0.5.0"
  391. picos_meta
  392. plebeia >= "2.0.0"
  393. plotkicadsch
  394. posix-getopt >= "4.0.2"
  395. ppx_defer >= "0.4.0"
  396. ppx_deriving_rpc
  397. ppx_rapper_lwt
  398. proc-smaps
  399. prof_spacetime
  400. prometheus < "2.0"
  401. prometheus-app
  402. prometheus-lwt
  403. promise_jsoo_lwt
  404. protocol-9p
  405. protocol-9p-unix
  406. proton
  407. pxshot
  408. qcow
  409. qcow-stream
  410. qcow-tool
  411. qcow-types
  412. qdrant < "0.2.0"
  413. qfs
  414. quests
  415. quickterface
  416. rawlink < "2.1"
  417. rawlink-lwt
  418. rdf_json_ld
  419. rdf_lwt
  420. redis-lwt
  421. reparse-lwt
  422. reparse-lwt-unix
  423. resource-pooling
  424. resp
  425. resp-mirage >= "0.10.0"
  426. resp-unix >= "0.10.0"
  427. resto
  428. resto-cohttp-client = "0.4"
  429. resto-cohttp-server = "0.4"
  430. resto-directory = "0.4"
  431. ringo-lwt
  432. river
  433. rock
  434. rpclib-js
  435. rpclib-lwt
  436. SZXX < "4.0.0"
  437. sanddb
  438. scgi
  439. sendmail-lwt
  440. sendmail-mirage
  441. serial
  442. server-reason-react
  443. session-cohttp-lwt
  444. session-cookie-lwt
  445. session-postgresql-lwt
  446. sessions
  447. shared-block-ring
  448. shared-memory-ring-lwt
  449. sherlodoc
  450. sihl < "0.2.0"
  451. slack
  452. slacko
  453. slipshow
  454. smtml >= "0.7.0"
  455. speed
  456. spin < "0.8.0"
  457. spoke
  458. statocaml
  459. stk
  460. stog
  461. swapfs
  462. syguslib-utils
  463. syndic >= "1.4" & < "1.6.0"
  464. tar-mirage
  465. tar-unix
  466. tcpip
  467. telegraml
  468. terminus
  469. testcontainers
  470. testo-lwt
  471. tidy_email
  472. tls >= "0.10.6" & < "0.16.0"
  473. tls-lwt
  474. tls-mirage
  475. tube
  476. tuntap
  477. twirp_cohttp_lwt_unix
  478. uring
  479. uspf
  480. uspf-lwt
  481. uspf-mirage
  482. utcp
  483. utop
  484. uwt
  485. vchan
  486. vchan-unix
  487. vchan-xen
  488. vercel
  489. vhd-format-lwt
  490. vmnet
  491. vue-jsoo < "0.3"
  492. wayland < "2.0"
  493. webauthn
  494. xen-evtchn
  495. xen-evtchn-unix
  496. xen-gnt
  497. xen-gnt-unix
  498. xenstore
  499. xenstore-tool
  500. xenstore_transport
  501. xlsx2csv
  502. yocaml_git
  503. yocaml_unix < "2.0.0"
  504. zarr-lwt
  505. zmq-lwt >= "5.2.1"

Conflicts

None