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. ocaml-ai-sdk
  343. ocluster
  344. ocluster-api
  345. ocluster-worker
  346. ocplib-resto
  347. ocsigenserver
  348. ocsipersist
  349. ocsipersist-dbm
  350. ocsipersist-lib
  351. ocsipersist-pgsql
  352. ocsipersist-sqlite
  353. oframl
  354. ojs_base
  355. omigrate
  356. oneffs
  357. opam-check-npm-deps >= "4.1.0"
  358. opam-publish >= "3.0.0"
  359. opencage
  360. opentelemetry-client-cohttp-lwt
  361. opentelemetry-client-ocurl-lwt
  362. opentelemetry-cohttp-lwt >= "0.4"
  363. opentelemetry-lwt
  364. opium
  365. opium-graphql
  366. opium_kernel
  367. opomodoro
  368. order-i3-xfce
  369. ordma
  370. oskel >= "0.3.0"
  371. ounit-lwt < "2.2.0"
  372. ounit2-lwt
  373. owork
  374. ozulip
  375. paf
  376. paf-cohttp
  377. passage < "0.1.8"
  378. pcap-format < "0.5.2"
  379. petrol
  380. pgn_parser
  381. pgx_lwt
  382. pgx_lwt_mirage
  383. pgx_lwt_unix < "2.0"
  384. piaf < "0.2.0"
  385. picos >= "0.3.0" & < "0.5.0"
  386. picos_lwt
  387. picos_meta
  388. plebeia >= "2.0.0"
  389. plist-xml-lwt
  390. plotkicadsch
  391. posix-getopt >= "4.0.2"
  392. ppx_defer >= "0.4.0"
  393. ppx_deriving_rpc
  394. ppx_rapper_lwt
  395. proc-smaps
  396. prof_spacetime
  397. prometheus
  398. prometheus-app
  399. promise_jsoo_lwt
  400. protocol-9p
  401. protocol-9p-unix
  402. proton
  403. pxshot
  404. qcow
  405. qcow-stream
  406. qcow-tool
  407. qcow-types
  408. qdrant < "0.2.0"
  409. qfs >= "0.5"
  410. quests
  411. quickterface
  412. rawlink < "2.1"
  413. rawlink-lwt
  414. rdf_json_ld
  415. rdf_lwt
  416. redis-lwt
  417. reparse-lwt
  418. reparse-lwt-unix
  419. resource-pooling
  420. resp
  421. resp-mirage >= "0.10.0"
  422. resp-unix >= "0.10.0"
  423. resto
  424. resto-cohttp-client >= "0.4"
  425. resto-cohttp-self-serving-client
  426. resto-cohttp-server >= "0.4" & < "0.6" | >= "0.9"
  427. resto-directory >= "0.4"
  428. riak
  429. ringo-lwt
  430. river
  431. rock
  432. rpclib-js
  433. rpclib-lwt
  434. SZXX < "4.0.0"
  435. sanddb
  436. scgi
  437. sendmail-lwt
  438. sendmail-mirage
  439. serial
  440. server-reason-react < "0.4.0"
  441. session-cohttp-lwt
  442. session-cookie-lwt
  443. session-postgresql-lwt
  444. sessions
  445. shared-block-ring
  446. shared-memory-ring-lwt
  447. sherlodoc
  448. sihl < "0.2.0"
  449. slack
  450. slacko
  451. slipshow
  452. smtml >= "0.7.0"
  453. speed
  454. spin < "0.8.0"
  455. spoke
  456. statocaml
  457. stk
  458. stog
  459. swapfs
  460. syguslib-utils
  461. syndic >= "1.4" & < "1.6.0"
  462. tar-mirage
  463. tar-unix
  464. tcpip
  465. telegraml
  466. terminus
  467. testcontainers
  468. testo-lwt
  469. tezt
  470. tidy_email
  471. timmy-lwt
  472. tls >= "0.10.6" & < "0.16.0"
  473. tls-lwt
  474. tls-mirage
  475. tube
  476. tuntap
  477. twirp_cohttp_lwt_unix
  478. uring
  479. uspf
  480. uspf-lwt
  481. uspf-mirage
  482. utcp
  483. utop
  484. uwt
  485. vchan
  486. vchan-unix
  487. vchan-xen
  488. vercel
  489. vhd-format-lwt
  490. vmnet
  491. vue-jsoo < "0.3"
  492. wayland < "2.0"
  493. webauthn
  494. xen-evtchn
  495. xen-evtchn-unix
  496. xen-gnt
  497. xen-gnt-unix
  498. xenstore
  499. xenstore-tool
  500. xenstore_transport
  501. xlsx2csv
  502. yocaml_git
  503. yocaml_unix < "2.0.0"
  504. zarr-lwt
  505. zmq-lwt >= "5.2.1"

Conflicts

None