lwt
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:
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) ->
let%lwt () = write outgoing "GET / HTTP/1.1\r\n" in
let%lwt () = write outgoing "Connection: close\r\n\r\n" in
let%lwt response = read incoming in
Lwt.return (Some response)))
in
let timeout =
let%lwt () = 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 -o request example.ml
./request *)
In the program, functions such as Lwt_io.write create promises. Thelet%lwt ... 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
and BuckleScript.
In Lwt,
The core library
Lwtprovides promises......and a few pure-OCaml helpers, such as promise-friendly mutexes,
condition variables, and mvars.There is a big Unix binding,
Lwt_unixthat binds almost every Unix
system call. A higher-level moduleLwt_ioprovides nice I/O channels.Lwt_processis for subprocess handling.Lwt_preemptivespawns system threads.The PPX syntax allows using all of the above without going crazy!
There are also some other helpers, such as
Lwt_reactfor reactive
programming. See the table of contents on the linked manual pages!
Installing
Use your system package manager to install a development libev package.
It is often calledlibev-devorlibev-devel.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.mdcontains 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
dev & >= "1.7.3-1"
dev & >= "1.3.0"
>= "4.02.0" & < "4.12"
>= "1.1.0"
>= "1.7.0"
build & >= "1.1.0"
>= "2.15.1"
>= "0.9.0" & < "1.0.2" | >= "1.1.0"
>= "2.0.1"
< "1.8.6" | >= "1.8.8"
>= "2.3.1"
>= "2.2.1"
< "1.0.0"
< "0.2.0"
= "0.4.0"
>= "0.4.0"
>= "0.3.3"
= "0.9.5" | >= "0.9.7.0"
>= "0.9.0"
>= "0.11.0"
>= "1.3.0"
< "0.3"
>= "0.3" & != "0.10"
>= "1.1.1"
>= "0.2.2"
>= "2.0.0"
>= "0.15.0"
< "0.1.1"
>= "0.11.0"
>= "1.2"
< "0.2.0"
>= "0.19.1" & < "0.20.1"
>= "4.6.3"
>= "0.9.0"
< "1.0.0"
>= "0.4"
< "0.2"
>= "0.4.2" & < "0.5.0"
>= "0.5"
>= "0.6.0"
>= "0.12.0"
>= "0.72.0"
< "2.0.0"
>= "0.3"
!= "1.4.3" & != "1.7.2"
= "1.11.1" | >= "3.0.0"
< "0.2.0" | >= "0.4.0"
>= "4.4.0"
< "1.1.0"
>= "0.3.0"
!= "0.4"
< "0.3.1"
>= "2.0.0" & < "3.0.0"
>= "1.0.2"
>= "0.1.4"
>= "2.4"
< "0.3.0"
< "0.4.6"
>= "0.4.3" & < "0.4.6"
< "0.9.6" | = "0.9.10" | >= "0.11.0" & < "2.7.0"
< "2.7.0"
< "2.7.0"
< "2.7.0"
>= "2.3.0" & < "2.7.0"
>= "2.3.0" & < "2.7.0"
>= "2.3.0" & < "2.7.0"
>= "2.3.0" & < "2.7.0"
< "2.7.0"
>= "2.3.0"
>= "2.3.0" & < "2.7.0"
>= "2.3.0" & < "2.7.0"
< "2.7.0"
>= "2.3.0" & < "2.7.0"
>= "2.3.0" & < "2.7.0"
>= "0.3.0"
< "2.5"
>= "3.5.0"
>= "2.3.0"
>= "0.4"
>= "0.3" & < "0.5"
>= "0.5"
>= "3.2.0"
< "0.0.3" | >= "0.0.9"
< "0.6"
>= "1.13"
>= "0.13.0"
>= "0.13.0"
!= "0.9"
< "0.2.0"
< "1.0.0"
>= "1.0.1"
>= "1.1.0"
>= "1.0.1"
>= "1.0.1"
< "0.5.1"
= "0.7.6"
>= "0.4.1" & != "0.6.1" & < "0.8.0" | >= "0.10.0" & < "2.7.0"
< "1.0.0" | >= "2.0.0"
< "2.3.0" | = "2.8.2"
>= "0.2.0"
>= "0.4.0"
>= "4.0.0"
< "3.0.0"
>= "1.3.0" & < "3.0.0"
>= "3.0.0"
>= "0.2.0"
>= "2.2.1"
>= "5.0.0"
>= "0.7.0"
>= "0.8.8"
>= "2.0.0"
< "3.0.0"
>= "1.0.3" & < "1.2.0" | >= "2.0.0"
>= "1.3.0"
>= "3.0.0"
< "1.1.1" | >= "1.3.0"
>= "3.0.0"
!= "0.3.0"
>= "3.0.1"
>= "2.2.0"
>= "3.0.0"
>= "4.0.0" & < "8.0.0"
< "0.2" | >= "0.4"
>= "0.1.0"
>= "3.7.0"
>= "2.0.0" & < "4.0.0"
>= "2.0.0"
< "3.7.1"
>= "3.0.0"
>= "1.1.0"
>= "0.0.2"
>= "0.5.0"
>= "0.2.0"
>= "0.2.0" & < "0.4.0"
= "2.1.1" | >= "4.0.3"
>= "0.5.4"
>= "0.4.0"
< "0.4"
>= "1.2.1"
>= "4.00.1+mirage-unix" & < "4.00.1+open-types"
>= "2.10"
>= "2.0.0" & < "2.1.0"
< "0.6.0"
< "0.2.0"
>= "0.11.0" & != "0.16.0" & < "0.19.0"
>= "0.0.3"
>= "0.3.0"
< "2.2.0"
< "1.1.0"
>= "0.3.3" & < "0.5.0"
< "2.0"
>= "0.4.0"
>= "0.4.0"
>= "0.10.0"
>= "0.8.1"
< "0.3"
= "0.5" | >= "0.7"
>= "1.0"
>= "0.3.2"
>= "0.10.0"
>= "0.10.0"
>= "0.4"
>= "0.4"
>= "0.4"
>= "1.5.1" & < "7.1.0"
< "2.0.0"
>= "0.4.1"
< "2.3.0" | >= "3.0.0"
>= "1.2.0" & < "2.0.0"
< "0.3.0"
< "0.6.0"
< "0.2.1"
= "0.7.1" | >= "0.9.0"
>= "0.16.0" & < "0.19.0"
>= "1.4" & < "1.6.0"
>= "0.4.1"
>= "3.1.1" & < "3.4.1" | >= "4.1.0"
>= "8.0" & < "9.0"
>= "9.0" & < "11.0"
>= "11.0" & < "13.0"
< "9.3"
< "9.0"
= "0.10.1" | >= "0.10.6"
>= "4.3.0"
>= "1.0.0" & < "1.7.0" | >= "2.0.0"
>= "1.4.0"
>= "0.3.0"
>= "0.9.7" & < "2.0.0" | >= "2.0.3"
>= "0.7.0" & < "0.8.0"
>= "0.12.0"
< "0.12.0"
>= "1.3.2"
>= "0.2.0"
< "2.3"
< "0.9.14"
< "1.0.6" | >= "2.0.0"
>= "2.2.3"
< "0.9.29" | >= "0.9.32"
>= "1.3.0"
>= "1.0.0"
< "0.3"