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

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

Conflicts

None