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

Conflicts

None