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

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

Conflicts

None