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 awlays explicit (with Lwt.​wakeup or wekup_exn). When a thread is running, it executes as much as possible, and then returns (a value or an eror) 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.

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

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 map 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

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. The previous value associated to key is restored after f terminates.

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