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

Conflicts

None