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

Conflicts

None