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 < "0.6"
  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-client-ocurl-lwt
  361. opentelemetry-cohttp-lwt >= "0.4"
  362. opentelemetry-lwt
  363. opium
  364. opium-graphql
  365. opium_kernel
  366. opomodoro
  367. order-i3-xfce
  368. ordma
  369. oskel >= "0.3.0"
  370. ounit-lwt < "2.2.0"
  371. ounit2-lwt
  372. owork
  373. ozulip
  374. paf
  375. paf-cohttp
  376. passage < "0.1.8"
  377. pcap-format < "0.5.2"
  378. petrol
  379. pgn_parser
  380. pgx_lwt
  381. pgx_lwt_mirage
  382. pgx_lwt_unix < "2.0"
  383. piaf < "0.2.0"
  384. picos >= "0.3.0" & < "0.5.0"
  385. picos_lwt
  386. picos_meta
  387. plebeia >= "2.0.0"
  388. plist-xml-lwt
  389. plotkicadsch
  390. posix-getopt >= "4.0.2"
  391. ppx_defer >= "0.4.0"
  392. ppx_deriving_rpc
  393. ppx_rapper_lwt
  394. proc-smaps
  395. prof_spacetime
  396. prometheus
  397. prometheus-app
  398. promise_jsoo_lwt
  399. protocol-9p
  400. protocol-9p-unix
  401. proton
  402. pxshot
  403. qcow
  404. qcow-stream
  405. qcow-tool
  406. qcow-types
  407. qdrant < "0.2.0"
  408. qfs >= "0.5"
  409. quests
  410. quickterface
  411. rawlink < "2.1"
  412. rawlink-lwt
  413. rdf_json_ld
  414. rdf_lwt
  415. redis-lwt
  416. reparse-lwt
  417. reparse-lwt-unix
  418. resource-pooling
  419. resp
  420. resp-mirage >= "0.10.0"
  421. resp-unix >= "0.10.0"
  422. resto
  423. resto-cohttp-client >= "0.4"
  424. resto-cohttp-self-serving-client
  425. resto-cohttp-server >= "0.4" & < "0.6" | >= "0.9"
  426. resto-directory >= "0.4"
  427. riak
  428. ringo-lwt
  429. river
  430. rock
  431. rpclib-js
  432. rpclib-lwt
  433. SZXX < "4.0.0"
  434. sanddb
  435. scgi
  436. sendmail-lwt
  437. sendmail-mirage
  438. serial
  439. server-reason-react < "0.4.0"
  440. session-cohttp-lwt
  441. session-cookie-lwt
  442. session-postgresql-lwt
  443. sessions
  444. shared-block-ring
  445. shared-memory-ring-lwt
  446. sherlodoc
  447. sihl < "0.2.0"
  448. slack
  449. slacko
  450. slipshow
  451. smtml >= "0.7.0"
  452. speed
  453. spin < "0.8.0"
  454. spoke
  455. statocaml
  456. stk
  457. stog
  458. swapfs
  459. syguslib-utils
  460. syndic >= "1.4" & < "1.6.0"
  461. tar-mirage
  462. tar-unix
  463. tcpip
  464. telegraml
  465. terminus
  466. testcontainers
  467. testo-lwt
  468. tezt
  469. tidy_email
  470. timmy-lwt
  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