Lwt is OCaml's concurrent programming library. 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 = (List.hd addresses).Lwt_unix.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 -package lwt.ppx -linkpkg -o request example.ml
./request *)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.
opam install lwt
The manual can be found here. There are also some examples available
in doc/examples.
Note: much of the manual still 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.
Open an issue, visit Gitter chat, email the maintainer, or ask in #ocaml. If you think enough people will be interested in the answer, it is also possible to ask on Stack Overflow.
Lwt is a very mature library, but there is considerable room for improvement. Contributions are welcome. To clone the source and install a development version,
opam source --dev-repo --pin lwt
This will also install the development dependency OASIS.
A list of project suggestions and a roadmap can be found on the wiki.
Lwt is released under the LGPL, with the OpenSSL linking exception. See
COPYING.