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

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.1.tar.gz
md5=18742da8b8fe3618e3fa700b7a884fe7
sha512=1c51fdb4d0856c89e2df08a1c0095ef28ebd0f613b07b03d0f66501ca5486515562071291e6d0932e57587ed0c9362c8b92c5c9eddb4d2bb2f5e129986b484a7

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.

Added to opam-repository:

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

Conflicts

None