Page
Library
Module
Module type
Parameter
Class
Class type
Source
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.
libev-dev
or libev-devel
.opam install conf-libev lwt
We are currently working on improving the Lwt documentation (drastically; we are rewriting the manual). In the meantime:
doc/examples
.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.
Open an issue, visit Gitter chat, ask in #ocaml, on discuss.ocaml.org, or on Stack Overflow. Please do ask! Even apparently simple questions often end up educating other users, not to mention enlightening the maintainers!
Subscribe to the announcements issue to get news about Lwt releases. It is less noisy than watching the whole repository. Announcements are also made in /r/ocaml, on the OCaml mailing list, and on discuss.ocaml.org.
What counts as a contribution to Lwt? All kinds of things make the project better, and are very much appreciated:
Contributing to Lwt is not only for OCaml "experts!" If you are near the beginning of your OCaml journey, we'd love to give you a little help by recommending appropriate issues, or even just chatting about Lwt or OCaml. Newcomers make valuable contributions, that maintainers often learn from – not the least because newcomers bring a fresh, valuable perspective :) Don't be afraid to ask anything.
We hope you'll join us to work in a friendly community around Lwt :) On behalf of all users of, and contributors to, Lwt: Thank you! :tada:
There are several resources to help you get started:
CONTRIBUTING.md
contains optional tips for working on the code of Lwt, instructions on how to check the code out, and a high-level outline of the code base.Lwt is released under the LGPL, with an OpenSSL linking exception. See COPYING
.