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

Conflicts

None