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 wakeup or 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
fail instead of
raise. Also the
try ... with ...
construction will not catch Lwt errors. You must use catch
instead. You can also use wrap for functions that may raise
Lwt also provides the syntax extension [root:Pa_lwt] to make code using Lwt more readable.
The type of threads returning a result of type
bind t f is a thread which first waits for the thread
terminate and then, if the thread succeeds, behaves as the
application of function
f to the return value of
t. If the
bind t f also fails, with the same
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'.
bind is also often used just for synchronization
t' will not execute before
t is terminated.
The result of a thread can be bound several times.
Type of a key. Keys are used to store local values into threads.
get key returns the value associated with
key in the current
with_value key value f executes
value associated to
key is restored to its previous value after
wrap f calls
f and transforms the result into an Lwt thread.
f raises an exception, it is caught and converted to an Lwt
This is actually the same as:
try return (f ()) with exn -> fail exn
wrap1 f x applies
x and returns the result as a
thread. If the application of
x raise an exception it
is catched and a thread is returned.
For example, the following code is incorrect:
wrap1 f (Hashtbl.find table key)
and should be written as:
wrap (fun () -> f (Hashtbl.find table key))
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
fails with the same exception.
Note: nchoose leaves the local values of the current thread unchanged.
async f starts a thread without waiting for the result. If it
fails (now or later), the exception is given to
You should use this function if you want to start a thread that might fail and don't care what its return value is, nor when it terminates (for instance, because it is looping).
The type of thread wakeners.
wait () is a pair of a thread which sleeps forever (unless it
is resumed by one of the functions
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).
wakeup t e makes the sleeping thread
t terminate and return
the value of the expression
wakeup_exn t e makes the sleeping thread
t fail with the
Either a value of type
'a, either an exception.
Cancelable threads are the same as regular threads except that they can be canceled.
Canceled threads fails with this exception
wakeup_paused () wakes up all threads which suspended
themselves with 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 resumes and pauses again, it will not be woken up at this point.
paused_count () returns the number of currently paused
register_pause_notifier f register a function
f that will be
called each time pause is called. The parameter passed to
the new number of threads paused. It is usefull to be able to
call wakeup_paused when there is no scheduler