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.6.1.tar.gz
md5=279024789a0ec84a9d97d98bad847f97
sha512=698875bd3bfcd5baa47eb48e412f442d289f9972421321541860ebe110b9af1949c3fbc253768495726ec547fe4ba25483cd97ff39bc668496fba95b2ed9edd8

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. ocaml >= "4.08" & < "5.1"
  3. dune-configurator
  4. dune >= "1.8.0"
  5. cppo build & >= "1.1.0"

Dev Dependencies (1)

  1. 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
  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 < "0.2.0"
  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 < "0.7.2"
  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. cohttp-curl-lwt
  61. cohttp-lwt < "6.0.0"
  62. cohttp-lwt-jsoo != "6.1.0" & < "6.2.1"
  63. cohttp-lwt-unix
  64. cohttp-mirage
  65. cohttp-server-lwt-unix
  66. comby
  67. comby-semantic
  68. conan-lwt
  69. conduit-lwt < "7.0.0"
  70. conduit-lwt-unix < "7.0.0"
  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 < "0.7.1"
  79. current-albatross-deployer
  80. current_docker < "0.7.1"
  81. current_examples < "0.7.1"
  82. current_git < "0.7.1"
  83. current_github < "0.7.1"
  84. current_gitlab < "0.7.1"
  85. current_ocluster < "0.4.0"
  86. current_rpc < "0.7.1"
  87. current_slack < "0.7.1"
  88. current_web < "0.7.1"
  89. dap
  90. data-encoding < "0.1.1"
  91. devkit >= "1.2" & < "1.20261006"
  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-mirage
  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. fxmacrodata
  144. gdbprofiler
  145. git
  146. git-cohttp
  147. git-cohttp-unix
  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. 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. hiredis >= "0.6"
  173. hl_yaml
  174. hockmd
  175. http-lwt-client
  176. http-mirage-client
  177. http-multipart-formdata >= "2.0.0" & < "3.0.0"
  178. httpaf-lwt-unix
  179. httpun-lwt
  180. httpun-mirage
  181. httpun-ws-lwt
  182. hvsock
  183. i3ipc
  184. influxdb-lwt
  185. inotify >= "2.4"
  186. inquire < "0.3.0"
  187. interface-prime-lwt
  188. ip2location
  189. ip2locationio
  190. ip2whois
  191. ipv6-multicast-lwt
  192. irc-client-lwt
  193. irc-client-lwt-ssl
  194. irc-client-tls
  195. irmin
  196. irmin-bench
  197. irmin-chunk
  198. irmin-cli
  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
  228. lambda_streams_lwt
  229. launchd
  230. ldp
  231. learn-ocaml
  232. learn-ocaml-client
  233. letsencrypt < "2.0.0"
  234. letsencrypt-app
  235. letsencrypt-dns < "2.0.0"
  236. letters
  237. lichess_api
  238. links
  239. linol-lwt
  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_domain
  251. lwt_eio < "0.4"
  252. lwt_glib
  253. lwt_log
  254. lwt_ppx < "5.8.0"
  255. lwt_react
  256. lwt_retry
  257. lwt_ssl
  258. mariadb >= "1.2.0"
  259. markdown_monolith
  260. markup = "0.7.6"
  261. markup-lwt
  262. mdx
  263. mechaml
  264. mehari-lwt-unix
  265. mehari-mirage
  266. memtrace-mirage
  267. metrics-influx
  268. metrics-lwt
  269. metrics-unix
  270. migra
  271. mimic
  272. mindstorm-lwt
  273. mirage < "4.0.0"
  274. mirage-block >= "2.0.1"
  275. mirage-block-ccm
  276. mirage-block-combinators
  277. mirage-block-lwt
  278. mirage-block-partition
  279. mirage-block-ramdisk
  280. mirage-block-solo5
  281. mirage-block-unikraft
  282. mirage-block-unix >= "2.14.2"
  283. mirage-block-xen
  284. mirage-channel >= "4.0.1"
  285. mirage-channel-lwt
  286. mirage-clock-lwt
  287. mirage-clock-unix < "4.2.0"
  288. mirage-console-lwt
  289. mirage-crypto-rng < "0.11.3"
  290. mirage-crypto-rng-lwt
  291. mirage-crypto-rng-mirage
  292. mirage-device >= "2.0.0"
  293. mirage-flow >= "3.0.0"
  294. mirage-flow-combinators
  295. mirage-flow-lwt
  296. mirage-flow-unix
  297. mirage-fs >= "4.0.0"
  298. mirage-fs-lwt
  299. mirage-kv >= "3.0.1"
  300. mirage-kv-lwt
  301. mirage-kv-unix < "3.0.1"
  302. mirage-net >= "4.0.0"
  303. mirage-net-lwt
  304. mirage-net-macosx
  305. mirage-net-solo5
  306. mirage-net-unikraft
  307. mirage-net-unix
  308. mirage-net-xen
  309. mirage-profile
  310. mirage-protocols >= "7.0.0"
  311. mirage-protocols-lwt
  312. mirage-runtime
  313. mirage-sleep
  314. mirage-solo5
  315. mirage-stack = "3.0.0"
  316. mirage-stack-lwt
  317. mirage-time >= "3.0.0"
  318. mirage-time-lwt
  319. mirage-time-unix
  320. mirage-types-lwt
  321. mirage-unikraft
  322. mirage-unix
  323. mirage-vnetif
  324. mirage-xen
  325. monorobot
  326. moonpool-lwt
  327. mrmime >= "0.5.0"
  328. multipart-form-data
  329. multipart_form >= "0.2.0" & < "0.4.0"
  330. multipart_form-cohttp-lwt < "0.6.0"
  331. multipart_form-lwt
  332. mwt
  333. naboris
  334. nbd >= "4.0.3"
  335. nbd-tool
  336. nbd-unix
  337. neo4j_bolt
  338. nocrypto
  339. nottui-lwt
  340. notty-community
  341. nproc
  342. nsq
  343. obuilder < "0.7.0"
  344. obus >= "1.2.1"
  345. ocluster < "0.4.0"
  346. ocluster-api
  347. ocluster-worker < "0.4.0"
  348. ocplib-resto
  349. ocsigen-start >= "4.1.0" & < "4.7.0"
  350. ocsigenserver < "7.0.0"
  351. ocsipersist < "3.1.2"
  352. ocsipersist-dbm < "3.1.2"
  353. ocsipersist-lib < "2.1.0"
  354. ocsipersist-pgsql < "3.1.2"
  355. ocsipersist-sqlite < "3.1.2"
  356. oframl
  357. ojs-base
  358. ojs_base
  359. omigrate
  360. oneffs
  361. opam-check-npm-deps >= "4.1.0"
  362. opam-compiler < "0.2.0"
  363. opam-publish >= "3.0.0"
  364. opencage
  365. opentelemetry-client-cohttp-lwt
  366. opentelemetry-cohttp-lwt >= "0.4"
  367. opentelemetry-lwt
  368. opium
  369. opium-graphql
  370. opium_kernel
  371. opomodoro
  372. order-i3-xfce
  373. ordma
  374. oskel >= "0.3.0"
  375. ounit-lwt < "2.2.0"
  376. ounit2-lwt
  377. owork
  378. ozulip
  379. paf
  380. paf-cohttp
  381. passage < "0.1.8"
  382. pcap-format < "0.5.2"
  383. petrol
  384. pgn_parser
  385. pgx_lwt
  386. pgx_lwt_mirage
  387. pgx_lwt_unix < "2.0"
  388. piaf < "0.2.0"
  389. plebeia >= "2.0.0"
  390. plist-xml-lwt
  391. plotkicadsch
  392. posix-getopt >= "4.0.2"
  393. ppx_defer >= "0.4.0"
  394. ppx_deriving_rpc
  395. ppx_rapper_lwt
  396. proc-smaps
  397. prof_spacetime
  398. prometheus < "2.0"
  399. prometheus-app
  400. prometheus-lwt
  401. promise_jsoo_lwt
  402. protocol-9p
  403. protocol-9p-unix
  404. proton
  405. pxshot
  406. qcow
  407. qcow-stream
  408. qcow-tool
  409. qcow-types
  410. qdrant < "0.2.0"
  411. qfs
  412. quests
  413. quickterface
  414. rawlink < "2.1"
  415. rawlink-lwt
  416. rdf_json_ld < "1.0.0"
  417. rdf_lwt < "1.0.0"
  418. redis-lwt
  419. reparse-lwt
  420. reparse-lwt-unix
  421. resource-pooling
  422. resp
  423. resp-mirage >= "0.10.0"
  424. resp-unix >= "0.10.0"
  425. resto
  426. resto-cohttp-client >= "0.4"
  427. resto-cohttp-self-serving-client
  428. resto-cohttp-server >= "0.4" & < "0.6" | >= "0.9"
  429. resto-directory >= "0.4"
  430. ringo-lwt
  431. river
  432. rock
  433. rpclib-js
  434. rpclib-lwt
  435. SZXX < "4.0.0"
  436. sanddb
  437. scgi
  438. sendmail-lwt
  439. sendmail-mirage
  440. serial
  441. server-reason-react < "0.4.0"
  442. session-cohttp-lwt
  443. session-cookie-lwt
  444. session-postgresql-lwt
  445. sessions
  446. shared-block-ring
  447. shared-memory-ring-lwt
  448. sihl < "0.2.0"
  449. slack
  450. slacko
  451. slipshow < "0.12.0"
  452. smtml >= "0.7.0"
  453. speed
  454. spin < "0.8.0"
  455. spoke
  456. stk
  457. stog < "1.0.0"
  458. syguslib-utils
  459. syndic >= "1.4" & < "1.6.0"
  460. tar-mirage
  461. tar-unix < "3.3.0"
  462. tcpip
  463. telegraml
  464. terminus
  465. testo-lwt
  466. tezt
  467. tidy_email
  468. timmy-lwt
  469. tls >= "0.10.6" & < "0.16.0"
  470. tls-lwt < "0.17.5"
  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 < "2.0.0"
  500. yocaml_unix < "2.0.0"
  501. zarr-lwt
  502. zmq-lwt

Conflicts

None