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.
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
val fail : exn -> 'a t
fail e is a thread that fails with the exception e.
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
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.
t >>= f is an alternative notation for bind t f.
f =<< t is t >>= f
map f m map the result of a thread. This is the same as bind
m (fun x -> return (f x))
m >|= f is map f m
f =|< m is map f m
Thread storage ¶
type 'a key
Type of a key. Keys are used to store local values into
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
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
Exceptions handling ¶
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
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 ().
finalize f g returns the same result as f () whether it
fails or not. In both cases, g () is executed after f.
Multi-threads composition ¶
choose l behaves as the first thread in l to terminate. If
several threads are already terminated, one is choosen at
Note: Lwt.choose leaves the local values of the current thread
nchoose l returns the value of all that have succcessfully
terminated. If all threads are sleeping, it waits for at least
one to terminates. If one the threads of l fails, nchoose
fails with the same exception.
Note: Lwt.nchoose leaves the local values of the current thread
nchoose_split l does the same as Lwt.nchoose but also retrurns
the list of threads that have not yet terminated.
join l waits for all threads in l to terminate. If one of
the threads fails, then join l will fails with the same
exception as the first one to terminate.
Note: Lwt.join leaves the local values of the current thread
t <?> t' is the same as choose [t; t']
t <&> t' is the same as join [t; t']
val ignore_result : 'a t -> unit
ignore_result t start the thread t and ignores its result
value if the thread terminates sucessfully. However, if the
thread t fails, the exception is raised instead of being
You should use this function if you want to start a thread and
don't care what its return value is, nor when it terminates (for
instance, because it is looping). Note that if the thread t
yields and later fails, the exception will not be raised at this
point in the program.
Sleeping and resuming ¶
type 'a u
The type of thread wakeners.
wait () is a pair of a thread which sleeps forever (unless it
is resumed by one of the functions wakeup, wakeup_exn below)
and the corresponding wakener. This thread does not block the
execution of the remainder of the program (except of course, if
another thread tries to wait for its termination).
val wakeup : 'a u -> 'a -> unit
wakeup t e makes the sleeping thread t terminate and return
the value of the expression e.
val wakeup_exn : 'a u -> exn -> unit
wakeup_exn t e makes the sleeping thread t fail with the
val wakeup_later : 'a u -> 'a -> unit
Same as Lwt.wakeup but it is not guaranteed that the thread will
be wakeup immediately.
val wakeup_later_exn : 'a u -> exn -> unit
Same as Lwt.wakeup_exn but it is not guaranteed that the thread
will be wakeup immediately.
Returns the thread associated to a wakener.
Threads state ¶
type 'a state = | Return of 'a(* The thread which has successfully terminated *) | Fail of exn(* The thread raised an exception *) | Sleep(* The thread is sleeping *)
State of a thread
state t returns the state of a thread
Cancelable threads ¶
Cancelable threads are the same as regular threads except that they can be canceled.
Canceled threads fails with this exception
task () is the same as wait () except that threads created
with task can be canceled.
val on_cancel : 'a t -> (unit -> unit) -> unit
on_cancel t f executes f when t is canceled. This is the
same as catching Canceled.
val cancel : 'a t -> unit
cancel t cancels the threads t. This means that the deepest
sleeping thread created with task and connected to t is
woken up with the exception Lwt.Canceled.
For example, in the following code:
let waiter, wakener = task () in cancel (waiter >> printl "plop")
waiter will be woken up with Lwt.Canceled.
pick l is the same as Lwt.choose, except that it cancels all
sleeping threads when one terminates.
Note: Lwt.pick leaves the local values of the current thread
npick l is the same as Lwt.nchoose, except that it cancels all
sleeping threads when one terminates.
Note: Lwt.npick leaves the local values of the current thread
protected thread creates a new cancelable thread which behave
as thread except that cancelling it does not cancel
val pause : unit -> unit t
pause () is a sleeping thread which is wake up on the next
call to Lwt.wakeup_paused. A thread created with pause can be
val wakeup_paused : unit -> unit
wakeup_paused () wakes up all threads which suspended
themselves with Lwt.pause.
This function is called by the scheduler, before entering the
main loop. You usually do not have to call it directly, except
if you are writing a custom scheduler.
Note that if a paused thread resume and pause again, it will not
be wakeup at this point.
val paused_count : unit -> int
paused_count () returns the number of thread currently
val register_pause_notifier : (int -> unit) -> unit
register_pause_notifier f register a function f that will be
called each time pause is called. The parameter passed to f is
the new number of threads paused. It is usefull to be able to
call Lwt.wakeup_paused when there is no scheduler
val on_success : 'a t -> ('a -> unit) -> unit
on_success t f executes f when t terminates without
failing. This is the same as:
ignore_result (bind t (fun x -> f x; return ()))
but a bit more efficient.
val on_failure : 'a t -> (exn -> unit) -> unit
on_failure t f executes f when t terminates and
fails. This is the same as:
ignore_result (catch t (fun e -> f e; return ()))
but a bit more efficient.