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

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.8.1.tar.gz
md5=d0f824f75ce5297975aec75366fed36c
sha512=c43fff2e9e808dc49ddf09caf7040e512ba36aebe2c600d524095ced11c196c3ac619953a11cb3e3a9f7c6c99e798d43bf179d5f790ab258fb9f746fae4c1125

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

Conflicts

None