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.9.0.tar.gz
md5=763b9201c891f8c20ee02dec0af23355
sha512=35574743df40170a8d1676254952c060090421a40d5f8ad37a6691f4f8bb0e28fca61f5efff1050edc4f8a3ffa2f06a1e23d0c084c89bfc105c1235e249bbc75

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. 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. cowabloga
  74. crunch
  75. cstruct-lwt
  76. csv-lwt
  77. ctypes >= "0.15.0" & < "0.21.1"
  78. ctypes-foreign >= "0.21.1"
  79. curl_lwt
  80. current
  81. current-albatross-deployer
  82. current_docker
  83. current_examples
  84. current_git
  85. current_github
  86. current_gitlab
  87. current_ocluster
  88. current_rpc
  89. current_slack
  90. current_web
  91. dap
  92. data-encoding < "0.1.1"
  93. devkit >= "1.2" & < "1.20261006"
  94. distributed-lwt
  95. dkim-bin < "0.8.0"
  96. dkim-lwt-unix
  97. dkim-mirage
  98. dlm
  99. dmarc
  100. dns-certify
  101. dns-cli
  102. dns-client < "7.0.3"
  103. dns-client-lwt
  104. dns-client-mirage
  105. dns-forward
  106. dns-forward-lwt-unix
  107. dns-lwt
  108. dns-mirage
  109. dns-resolver
  110. dns-server
  111. dns-stub
  112. dnsrobot
  113. dnssd
  114. docker_hub
  115. docteur >= "0.0.2"
  116. docteur-solo5
  117. docteur-unix >= "0.0.5"
  118. doi2bib
  119. dream
  120. dream-httpaf
  121. dream-mirage
  122. dream-pure
  123. dream-serve
  124. dropbox
  125. dune >= "3.17.2"
  126. dune-rpc-lwt
  127. earlybird
  128. elasticsearch-cli
  129. emoji = "2.0.0"
  130. equinoxe
  131. ethernet
  132. ez_api >= "1.2.0" & < "3.0.0"
  133. ezcurl-lwt
  134. ezjs_min < "0.2"
  135. ezjsonm-lwt
  136. ezresto
  137. ezresto-directory >= "0.5"
  138. faraday-lwt
  139. faraday-lwt-unix
  140. fat-filesystem
  141. fiber-lwt
  142. fsevents-lwt
  143. fswatch_lwt
  144. fuseau-lwt
  145. fxmacrodata
  146. gdbprofiler
  147. git
  148. git-cohttp
  149. git-cohttp-unix
  150. git-kv >= "0.2.0"
  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. ocaml-ai-sdk
  357. ocluster
  358. ocluster-api
  359. ocluster-worker
  360. ocplib-resto
  361. ocsigenserver
  362. ocsipersist
  363. ocsipersist-dbm
  364. ocsipersist-lib
  365. ocsipersist-pgsql
  366. ocsipersist-sqlite
  367. oframl
  368. ohttp-cohttp-lwt
  369. ojs_base
  370. omigrate
  371. oneffs
  372. opam-check-npm-deps >= "4.1.0"
  373. opam-publish >= "3.0.0"
  374. opencage
  375. opentelemetry-client-cohttp-lwt
  376. opentelemetry-client-ocurl-lwt
  377. opentelemetry-cohttp-lwt >= "0.4"
  378. opentelemetry-lwt
  379. opium
  380. opium-graphql
  381. opium_kernel
  382. opomodoro
  383. order-i3-xfce
  384. ordma
  385. oskel >= "0.3.0"
  386. ounit-lwt < "2.2.0"
  387. ounit2-lwt
  388. owork
  389. ozulip
  390. paf
  391. paf-cohttp
  392. passage < "0.1.8"
  393. pcap-format < "0.5.2"
  394. petrol
  395. pgn_parser
  396. pgx_lwt
  397. pgx_lwt_mirage
  398. pgx_lwt_unix < "2.0"
  399. piaf < "0.2.0"
  400. picos >= "0.3.0" & < "0.5.0"
  401. picos_lwt
  402. picos_meta
  403. plebeia >= "2.0.0"
  404. plist-xml-lwt
  405. plotkicadsch
  406. posix-getopt >= "4.0.2"
  407. ppx_defer >= "0.4.0"
  408. ppx_deriving_rpc
  409. ppx_rapper_lwt
  410. proc-smaps
  411. prof_spacetime
  412. prometheus < "2.0"
  413. prometheus-app
  414. prometheus-lwt
  415. promise_jsoo_lwt
  416. protocol-9p
  417. protocol-9p-unix
  418. proton
  419. pxshot
  420. qcow
  421. qcow-stream
  422. qcow-tool
  423. qcow-types
  424. qdrant < "0.2.0"
  425. qfs
  426. quests
  427. quickterface
  428. rawlink < "2.1"
  429. rawlink-lwt
  430. rdf_json_ld
  431. rdf_lwt
  432. redis-lwt
  433. reparse-lwt
  434. reparse-lwt-unix
  435. resource-pooling
  436. resp
  437. resp-mirage >= "0.10.0"
  438. resp-unix >= "0.10.0"
  439. resto
  440. resto-cohttp-client >= "0.4"
  441. resto-cohttp-self-serving-client
  442. resto-cohttp-server >= "0.4" & < "0.6" | >= "0.9"
  443. resto-directory >= "0.4"
  444. ringo-lwt
  445. river
  446. rock
  447. rpclib-js
  448. rpclib-lwt
  449. SZXX < "4.0.0"
  450. sanddb
  451. scgi
  452. sendmail-lwt
  453. sendmail-mirage
  454. serial
  455. server-reason-react < "0.4.0"
  456. session-cohttp-lwt
  457. session-cookie-lwt
  458. session-postgresql-lwt
  459. sessions
  460. shared-block-ring
  461. shared-memory-ring-lwt
  462. sherlodoc
  463. sihl < "0.2.0"
  464. slack
  465. slacko
  466. slipshow < "0.12.0"
  467. smtml >= "0.7.0"
  468. speed
  469. spin < "0.8.0"
  470. spoke
  471. statocaml
  472. stk
  473. stog
  474. swapfs
  475. syguslib-utils
  476. syndic >= "1.4" & < "1.6.0"
  477. tar-mirage
  478. tar-unix
  479. tcpip
  480. telegraml
  481. terminus
  482. testcontainers
  483. testo-lwt
  484. tezt
  485. tidy_email
  486. timmy-lwt
  487. tls >= "0.10.6" & < "0.16.0"
  488. tls-lwt
  489. tls-mirage
  490. tube
  491. tuntap
  492. twirp_cohttp_lwt_unix
  493. uring
  494. uspf
  495. uspf-lwt
  496. uspf-mirage
  497. utcp
  498. utop
  499. uwt
  500. vchan
  501. vchan-unix
  502. vchan-xen
  503. vercel
  504. vhd-format-lwt
  505. vmnet
  506. vue-jsoo < "0.3"
  507. wayland < "2.0"
  508. webauthn
  509. xen-evtchn
  510. xen-evtchn-unix
  511. xen-gnt
  512. xen-gnt-unix
  513. xenstore
  514. xenstore-tool
  515. xenstore_transport
  516. xlsx2csv
  517. yocaml_git
  518. yocaml_unix < "2.0.0"
  519. zarr-lwt
  520. zmq-lwt >= "5.2.1"

Conflicts

None