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%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.
- The core library
- ...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_ioprovides nice I/O channels.
Lwt_processis for subprocess handling.
Lwt_preemptivespawns system threads.
- Use your system package manager to install a development libev package. It is often called
opam install conf-libev lwt
- Online manual.
- Concurrent Programming with Lwt is a nice source of Lwt examples. They are translations of code from Real World OCaml, but are just as useful if you are not reading the book.
- Mirage Lwt tutorial.
- Example server written with Lwt.
This is the system-independent, pure-OCaml core of Lwt. To link with it, use
(libraries lwt) in your
LwtAsynchronous programming with promises.
Lwt_resultExplicit error handling
Lwt_mutexCooperative locks for mutual exclusion
Lwt_poolExternal resource pools.
This is the system call and I/O library. Despite its name, it is implemented on both Unix-like systems and Windows, although not all functions are available on Windows. To link with this library, use
(libraries lwt.unix) in your
Lwt_unixCooperative system calls
Lwt_mainMain loop and event queue
Lwt_ioBuffered byte channels
Lwt_preemptiveThis module allows to mix preemptive threads with
Lwtcooperative threads. It maintains an extensible pool of preemptive threads to which you can detach computations.
Lwt_fmtFormat API for Lwt-powered IOs
Lwt_engineLwt unix main loop engine
Lwt_gcInteraction with the garbage collector