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

Conflicts

None