Repository files navigation

Lwt is a concurrent programming library for OCaml. It provides a single datatype: thepromise, which is a value that will become determined in the future.Creating a promise spawns a computation. When that computation is I/O, Lwt runsit in parallel with your OCaml code.

OCaml code, including creating and waiting on promises, is run in a singlethread by default, so you don't have to worry about locking or preemption. Youcan 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 failsif the request is not completed in five seconds:

openLwt.Syntaxlet()=let request=let* addresses=Lwt_unix.getaddrinfo"google.com""80"[]inlet google=Lwt_unix.((List.hd addresses).ai_addr)inLwt_io.(with_connection google (fun (incoming,outgoing) ->let*()= write outgoing"GET / HTTP/1.1\r\n"inlet*()= write outgoing"Connection: close\r\n\r\n"inlet* response= read incominginLwt.return (Some response)))inlet timeout=let*()=Lwt_unix.sleep5.inLwt.returnNoneinmatchLwt_main.run (Lwt.pick [request; timeout])with|Someresponse -> print_string response|None -> prerr_endline"Request timed out"; exit1(* ocamlfind opt -package lwt.unix -linkpkg example.ml && ./a.out*)

In the program, functions such asLwt_io.write create promises. Thelet* ... in construct is used to wait for a promise to become determined; thecode afterin is scheduled to run in a "callback."Lwt.pick races promisesagainst each other, and behaves as the first one to complete.Lwt_main.runforces the whole promise-computation network to be executed. All the visibleOCaml code is run in a single thread, but Lwt internally uses a combination ofworker threads and non-blocking file descriptors to resolve in parallel thepromises that do I/O.

Lwt compiles to native code on Linux, macOS, Windows, and other systems. It'salso routinely compiled to JavaScript for the front end and Node by js_of_ocaml.

In Lwt,

• Thecore libraryLwt provides promises...
• ...and a few pure-OCaml helpers, such as promise-friendlymutexes,condition variables, andmvars.
• There is a big Unix binding,Lwt_unix that binds almost every Unixsystem call. A higher-level moduleLwt_io provides nice I/O channels.
• Lwt_process is for subprocess handling.
• Lwt_preemptive spawns system threads.
• ThePPX syntax allows using all of the above without going crazy!
• There are also some other helpers, such asLwt_react for reactiveprogramming. See the table of contents on the linked manual pages!

1. Use your system package manager to install a development libev package.It is often calledlibev-dev orlibev-devel.
2. opam install conf-libev lwt

We are currently working on improving the Lwt documentation (drastically; we arerewriting the manual). In the meantime:

• The current manual can be foundhere.
• Mirage has a nicely-writtenLwt tutorial.
• An example of asimple 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 arejust 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 apromise, and has nothing to do with system or preemptive threads.

Open anissue, visitDiscord chat, ask ondiscuss.ocaml.org, or onStack Overflow.

Release announcements are made ondiscuss.ocaml.org. Watching therepo for "Releases only" is also an option.

• CONTRIBUTING.md contains tips for working on the code,such as how to check the code out, how review works, etc. There is also ahigh-level outline of the code base.
• Ask us anything, whether it's about working on Lwt, or anyquestion at all about it :)
• Thedocumentation always needs proofreading and fixes.
• You are welcome to pick up any otherissue, review a PR, addyour opinion, etc.
• Any feedback is welcome, including how to make contributing easier!

• alcotest —unit testing
• angstrom —parser combinators
• cohttp — HTTP client and server
• cstruct —interop with C-like structures
• ezjsonm —JSON parsing and output
• faraday —serialization combinators
• logs —logging
• lwt-parallel —distributed computing
• mwt — preemptive (system) thread pools
• opium —web framework
• lwt_domain — domain parallelism whenusing Lwt with OCaml 5