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

Conflicts

None