Module Lwt

module Lwt : sig..end

Module Lwt: cooperative light-weight threads.

This module defines cooperative light-weight threads with their primitives. A light-weight thread represent a computation that may be not terminated, for example because it is waiting for some event to happen.

Lwt threads are cooperative in the sense that switching to another thread is always explicit (with Lwt.​wakeup or Lwt.​wakeup_exn). When a thread is running, it executes as much as possible, and then returns (a value or an error) or sleeps.

Note that inside a Lwt thread, exceptions must be raised with Lwt.​fail instead of raise. Also the try ... with ... construction will not catch Lwt errors. You must use Lwt.​catch instead. You can also use Lwt.​wrap for functions that may raise normal exception.

Lwt also provides the syntax extension Pa_lwt to make code using Lwt more readable.

Definitions and basics

type +'a t

The type of threads returning a result of type 'a.

val return : 'a -> 'a t

return e is a thread whose return value is the value of the expression e.

val fail : exn -> 'a t

fail e is a thread that fails with the exception e.

val fail_with : string -> 'a t

fail_with msg is a thread that fails with the exception Failure msg.

val fail_invalid_arg : string -> 'a t

fail_invalid_arg msg is a thread that fails with the exception Invalid_argument msg.

val bind : 'a t -> ('a -> 'b t) -> 'b t

bind t f is a thread which first waits for the thread t to terminate and then, if the thread succeeds, behaves as the application of function f to the return value of t. If the thread t fails, bind t f also fails, with the same exception.

The expression bind t (fun x -> t') can intuitively be read as let x = t in t', and if you use the lwt.syntax syntax extension, you can write a bind operation like that: lwt x = t in t'.

Note that bind is also often used just for synchronization purpose: t' will not execute before t is terminated.

The result of a thread can be bound several times.

Note that bind will not propagate backtraces correctly. See the manual for how to enable backtraces.

val (>>=) : 'a t -> ('a -> 'b t) -> 'b t

t >>= f is an alternative notation for bind t f.

val (=<<) : ('a -> 'b t) -> 'a t -> 'b t

f =<< t is t >>= f

val map : ('a -> 'b) -> 'a t -> 'b t

map f m maps the result of a thread. This is the same as bind m (fun x -> return (f x))

val (>|=) : 'a t -> ('a -> 'b) -> 'b t

m >|= f is map f m

val (=|<) : ('a -> 'b) -> 'a t -> 'b t

f =|< m is map f m

Pre-allocated threads

val return_unit : unit t

return_unit = return ()

val return_none : 'a option t

return_none = return None

val return_some : 'a -> 'a option t

return_some x = return (Some x)

val return_nil : 'a list t

return_nil = return []

val return_true : bool t

return_true = return true

val return_false : bool t

return_false = return false

val return_ok : 'a -> ('a, 'b) Result.result t

return_ok x is equivalent to return (Ok x). Since 2.6.0

val return_error : 'e -> ('a, 'e) Result.result t

return_error x is equivalent to return (Error x). Since 2.6.0

Thread storage

type 'a key

Type of a key. Keys are used to store local values into threads.

val new_key : unit -> 'a key

new_key () creates a new key.

val get : 'a key -> 'a option

get key returns the value associated with key in the current thread.

val with_value : 'a key -> 'a option -> (unit -> 'b) -> 'b

with_value key value f executes f with value associated to key. key is restored to its previous value after f terminates.

This function should not be applied within threads created with Lwt_preemptive.​detach.

Exceptions handling

val catch : (unit -> 'a t) -> (exn -> 'a t) -> 'a t

catch t f is a thread that behaves as the thread t () if this thread succeeds. If the thread t () fails with some exception, catch t f behaves as the application of f to this exception.

val try_bind : 
  (unit -> 'a t) ->
  ('a -> 'b t) -> (exn -> 'b t) -> 'b t

try_bind t f g behaves as bind (t ()) f if t does not fail. Otherwise, it behaves as the application of g to the exception associated to t ().

val finalize : (unit -> 'a t) -> (unit -> unit t) -> 'a t

finalize f g runs f (), and then g (), whether f () fails or completes normally. Lwt.finalize returns the result of f (), unless g () fails, in which case it returns the exception raised by g ().

val wrap : (unit -> 'a) -> 'a t

wrap f calls f and transforms the result into an Lwt thread. If f raises an exception, it is caught and converted to an Lwt exception.

This is actually the same as:

          return (f ())
        with exn ->
          fail exn
val wrap1 : ('a -> 'b) -> 'a -> 'b t

wrap1 f x applies f on x and returns the result as a thread. If the application of f to x raise an exception it is catched and a thread is returned.

Note that you must use Lwt.​wrap instead of Lwt.​wrap1 if the evaluation of x may raise an exception.

For example, the following code is incorrect:

wrap1 f (Hashtbl.find table key)

and should be written as:

wrap (fun () -> f (Hashtbl.