package lwt

All checked builds pass
  1. Overview
  2. Docs
Promises and event-driven I/O

Install 

dune-project
 Dependency

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

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

Conflicts

None

Build status

Results of building lwt with each compiler on check.ci.ocaml.org, run of against opam-repository 8a77e58. All results for this package.

Each result links to its build log. To keep crawlers from overloading the site, build logs require a GitHub sign-in (see ocurrent/opam-health-check). On your first log, GitHub asks you to “Authorize opam-health-check”, the OCurrent app that runs these checks; it sees only your public profile, not your repositories. The sign-in lasts 30 days.

Version OCaml 4.11 OCaml 4.14 OCaml 5.2 OCaml 5.4 OCaml 5.5
6.1.2 (this version) n/a good good good good
5.10.1 good good good good good
  • good Package successfully built
  • partial One of the dependencies failed to build
  • bad Package failed to build
  • n/a Package is not available in this environment
  • internal Internal failure