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

6.0.0-alpha00.tar.gz
md5=8a88c5d5fcb01d179bbb12e6b6888dca
sha512=bfecd3fa0a3461a3368bd7724e2fce7a751ba3899d590d5b08bc4257b058ca34ec25de1a3ead6585528afe77c6ca6db1c3e2d2421d6a773c845ef091472d2ed9

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

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

Conflicts

None