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.1.2.tar.gz
md5=00bc7eb2772a28530f7365a7040f0c4f
sha512=a4737a2fc44aaeedca46ec6134c07013d5cf44039a988a6e79a40715a53e43601d4c91bbf11a8e89540528d912b8fa487e3068465c136c1156a872258eb3443b

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 resolved 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:

let () =
  let request =
    let%lwt 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) ->
      write outgoing "GET / HTTP/1.1\r\n";%lwt
      write outgoing "Connection: close\r\n\r\n";%lwt
      let%lwt response = read incoming in
      Lwt.return (Some response)))
  in

  let timeout =
    Lwt_unix.sleep 5.;%lwt
    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,lwt_ppx -linkpkg example.ml && ./a.out *)

If you are not using the lwt_ppx syntax extension, you can use the let* binding opoerators from the Lwt.Syntax module instead.

let () =
  let open Lwt.Syntax in
  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,lwt_ppx -linkpkg example.ml && ./a.out *)

In the program above, functions such as Lwt_io.write create promises. The let%lwt ... in construct (provided by lwt_ppx) or the let* ... in construct (provided by Lwt.Syntax) are used to wait for a promise to resolve. The code after in is scheduled to run after the code inside the let...in has resolved.

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"
  4. ocaml >= "4.14"
  5. dune >= "3.18"

Dev Dependencies (2)

  1. odoc with-doc & >= "2.3"
  2. ocamlfind dev & >= "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. faraday-lwt
  135. faraday-lwt-unix
  136. fat-filesystem
  137. fiber-lwt
  138. fsevents-lwt
  139. fswatch_lwt
  140. gdbprofiler
  141. git
  142. git-cohttp
  143. git-cohttp-unix
  144. git-kv >= "0.2.0"
  145. git-mirage
  146. git-paf
  147. git-unix >= "3.2.0"
  148. github
  149. github-hooks
  150. github-unix >= "4.4.0"
  151. gitlab-unix
  152. gitlab_pipeline_notifier
  153. gluten-lwt
  154. gluten-lwt-unix < "0.4.0"
  155. gluten-mirage < "0.4.0"
  156. granary
  157. granary_repl
  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 >= "3.3.3"
  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. llama
  241. lru_cache
  242. lwt-canceler
  243. lwt-dllist
  244. lwt-exit
  245. lwt-parallel
  246. lwt-pipe
  247. lwt-pipeline
  248. lwt-watcher
  249. lwt_camlp4
  250. lwt_direct >= "6.0.0"
  251. lwt_domain != "0.2.0"
  252. lwt_eio >= "0.6"
  253. lwt_ppx >= "6.0.0"
  254. lwt_react
  255. lwt_retry
  256. lwt_ssl
  257. mariadb >= "1.2.0"
  258. markdown_monolith
  259. markup = "0.7.6"
  260. markup-lwt
  261. mdx
  262. mechaml
  263. mehari-lwt-unix
  264. mehari-mirage
  265. memtrace-mirage
  266. metrics-influx
  267. metrics-lwt
  268. metrics-unix
  269. migra
  270. mimic
  271. mindstorm-lwt
  272. mirage < "4.0.0"
  273. mirage-block >= "2.0.1"
  274. mirage-block-ccm
  275. mirage-block-combinators
  276. mirage-block-lwt
  277. mirage-block-partition
  278. mirage-block-ramdisk
  279. mirage-block-solo5
  280. mirage-block-unikraft
  281. mirage-block-unix >= "2.14.2"
  282. mirage-block-xen
  283. mirage-channel >= "4.0.1"
  284. mirage-channel-lwt
  285. mirage-clock-lwt
  286. mirage-clock-unix < "4.2.0"
  287. mirage-console-lwt
  288. mirage-crypto-rng < "0.11.3"
  289. mirage-crypto-rng-lwt
  290. mirage-crypto-rng-mirage
  291. mirage-device >= "2.0.0"
  292. mirage-flow >= "3.0.0"
  293. mirage-flow-combinators
  294. mirage-flow-lwt
  295. mirage-flow-unix
  296. mirage-fs >= "4.0.0"
  297. mirage-fs-lwt
  298. mirage-kv >= "3.0.1"
  299. mirage-kv-lwt
  300. mirage-kv-unix
  301. mirage-net >= "4.0.0"
  302. mirage-net-lwt
  303. mirage-net-macosx
  304. mirage-net-solo5
  305. mirage-net-unikraft
  306. mirage-net-unix
  307. mirage-net-xen
  308. mirage-profile
  309. mirage-protocols >= "7.0.0"
  310. mirage-protocols-lwt
  311. mirage-qubes
  312. mirage-qubes-ipv4
  313. mirage-runtime
  314. mirage-sleep
  315. mirage-solo5
  316. mirage-stack = "3.0.0"
  317. mirage-stack-lwt
  318. mirage-time >= "3.0.0"
  319. mirage-time-lwt
  320. mirage-time-unix
  321. mirage-types-lwt
  322. mirage-unikraft
  323. mirage-unix
  324. mirage-vnetif
  325. mirage-xen
  326. monorobot
  327. mqtt
  328. mrmime >= "0.5.0"
  329. multipart-form-data
  330. multipart_form >= "0.2.0" & < "0.4.0"
  331. multipart_form-cohttp-lwt < "0.6.0"
  332. multipart_form-lwt
  333. naboris
  334. nbd >= "4.0.3"
  335. nbd-tool
  336. nbd-unix
  337. neo4j_bolt
  338. nottui-lwt
  339. notty-community
  340. nproc
  341. nsq
  342. obuilder
  343. obus >= "1.2.1"
  344. ocaml-ai-sdk
  345. ocluster
  346. ocluster-api
  347. ocluster-worker
  348. ocplib-resto
  349. ocsigenserver
  350. ocsipersist
  351. ocsipersist-dbm
  352. ocsipersist-lib
  353. ocsipersist-pgsql
  354. ocsipersist-sqlite
  355. oframl
  356. ojs_base
  357. omigrate
  358. oneffs
  359. opam-check-npm-deps >= "4.1.0"
  360. opam-publish >= "3.0.0"
  361. opencage
  362. opentelemetry-client-cohttp-lwt
  363. opentelemetry-client-ocurl-lwt
  364. opentelemetry-cohttp-lwt >= "0.4"
  365. opentelemetry-lwt
  366. opium
  367. opium-graphql
  368. opium_kernel
  369. opomodoro
  370. order-i3-xfce
  371. ordma
  372. oskel >= "0.3.0"
  373. ounit-lwt < "2.2.0"
  374. ounit2-lwt
  375. owork
  376. ozulip
  377. paf
  378. paf-cohttp
  379. passage < "0.1.8"
  380. pcap-format < "0.5.2"
  381. petrol
  382. pgn_parser
  383. pgx_lwt
  384. pgx_lwt_mirage
  385. pgx_lwt_unix < "2.0"
  386. piaf < "0.2.0"
  387. picos >= "0.3.0" & < "0.5.0"
  388. picos_meta
  389. plebeia >= "2.0.0"
  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. prometheus-lwt
  400. promise_jsoo_lwt
  401. protocol-9p
  402. protocol-9p-unix
  403. proton
  404. pxshot
  405. qcow
  406. qcow-stream
  407. qcow-tool
  408. qcow-types
  409. qdrant < "0.2.0"
  410. qfs
  411. quests
  412. quickterface
  413. rawlink < "2.1"
  414. rawlink-lwt
  415. rdf_json_ld
  416. rdf_lwt
  417. redis-lwt
  418. reparse-lwt
  419. reparse-lwt-unix
  420. resource-pooling
  421. resp
  422. resp-mirage >= "0.10.0"
  423. resp-unix >= "0.10.0"
  424. resto
  425. resto-cohttp-client = "0.4"
  426. resto-cohttp-server = "0.4"
  427. resto-directory = "0.4"
  428. ringo-lwt
  429. river
  430. rock
  431. rpclib-js
  432. rpclib-lwt
  433. SZXX < "4.0.0"
  434. sanddb
  435. scgi
  436. sendmail-lwt
  437. sendmail-mirage
  438. serial
  439. server-reason-react
  440. session-cohttp-lwt
  441. session-cookie-lwt
  442. session-postgresql-lwt
  443. sessions
  444. shared-block-ring
  445. shared-memory-ring-lwt
  446. sherlodoc
  447. sihl < "0.2.0"
  448. slack
  449. slacko
  450. slipshow
  451. smtml >= "0.7.0"
  452. speed
  453. spin < "0.8.0"
  454. spoke
  455. statocaml
  456. stk
  457. stog
  458. swapfs
  459. syguslib-utils
  460. syndic >= "1.4" & < "1.6.0"
  461. tar-mirage
  462. tar-unix
  463. tcpip
  464. telegraml
  465. terminus
  466. testcontainers
  467. testo-lwt
  468. tidy_email
  469. tls >= "0.10.6" & < "0.16.0"
  470. tls-lwt
  471. tls-mirage
  472. tube
  473. tuntap
  474. twirp_cohttp_lwt_unix
  475. uring
  476. uspf
  477. uspf-lwt
  478. uspf-mirage
  479. utcp
  480. utop
  481. uwt
  482. vchan
  483. vchan-unix
  484. vchan-xen
  485. vercel
  486. vhd-format-lwt
  487. vmnet
  488. vue-jsoo < "0.3"
  489. wayland < "2.0"
  490. webauthn
  491. xen-evtchn
  492. xen-evtchn-unix
  493. xen-gnt
  494. xen-gnt-unix
  495. xenstore
  496. xenstore-tool
  497. xenstore_transport
  498. xlsx2csv
  499. yocaml_git
  500. yocaml_unix < "2.0.0"
  501. zarr-lwt
  502. zmq-lwt >= "5.2.1"

Conflicts

None