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 (31)

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

5.9.0.tar.gz
md5=763b9201c891f8c20ee02dec0af23355
sha512=35574743df40170a8d1676254952c060090421a40d5f8ad37a6691f4f8bb0e28fca61f5efff1050edc4f8a3ffa2f06a1e23d0c084c89bfc105c1235e249bbc75

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.

Published: 15 Nov 2024

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 determined 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:

open Lwt.Syntax

let () =
  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 -linkpkg example.ml && ./a.out *)

In the program, functions such as Lwt_io.write create promises. The let* ... in construct is used to wait for a promise to become determined; the code after in is scheduled to run in a "callback." 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.0"
  4. ocaml >= "4.08" & < "5.5"
  5. dune >= "2.7"

Dev Dependencies (2)

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

Conflicts

None