Package lwt

Contents

Introduction

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:

Copy
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.

Tour

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.

In Lwt,

Installing

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

Additional Docs

API: Library lwt

This is the system-independent, pure-OCaml core of Lwt. To link with it, use (libraries lwt) in your dune file.

API: Library lwt.unix

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 dune file.

  • Lwt_unix Cooperative system calls
  • Lwt_main Main loop and event queue
  • Lwt_io Buffered byte channels
  • Lwt_process Process management
  • Lwt_bytes Byte arrays
  • Lwt_preemptive This module allows to mix preemptive threads with Lwt cooperative threads. It maintains an extensible pool of preemptive threads to which you can detach computations.
  • Lwt_fmt Format API for Lwt-powered IOs
  • Lwt_throttle Rate limiters.
  • Lwt_timeout Cancelable timeouts.
  • Lwt_engine Lwt unix main loop engine
  • Lwt_gc Interaction with the garbage collector
  • Lwt_sys System informations.

Package info

authors
  • Jérémie Dimino
  • Jérôme Vouillon
changes-files
depends
homepage
issues
license
  • MIT
license-files
maintainers
  • Anton Bachin
  • Raphaël Proust
online-doc
readme-files
repo
  • git+https://github.com/ocsigen/lwt.git
version
  • 5.6.1