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 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
normal exception.
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 'a
.
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.
Type of a key. Keys are used to store local values into threads.
with_value key value f
executes f
with value
associated to
key
. key
is restored to its previous value after f
terminates.
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:
try
return (f ())
with exn ->
fail exn
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 wrap instead of 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.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 l
fails, nchoose
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
async_exception_hook.
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).
ignore_result t
is like Pervasives.ignore t
except that:
t
already failed, it raises the exception now,t
is sleeping and fails later, the exception will be
given to async_exception_hook.Function called when a asynchronous exception is thrown.
The default behavior is to print an error message with a backtrace if available and to exit the program.
The behavior is undefined if this function raise an exception.
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).
wakeup t e
makes the sleeping thread t
terminate and return
the value of the expression e
.
wakeup_exn t e
makes the sleeping thread t
fail with the
exception e
.
Same as wakeup_exn but it is not guaranteed that the thread will be woken up immediately.
Either a value of type 'a
, either an exception.
Same as wakeup_result but it is not guaranteed that the thread will be woken up immediately.
Cancelable threads are the same as regular threads except that they can be canceled.
Canceled threads fails with this exception
on_cancel t f
executes f
when t
is canceled. f
will be
executed before all other threads waiting on t
.
If f
raises an exception it is given to
async_exception_hook.
add_task_r seq
creates a sleeping thread, adds its wakener to
the right of seq
and returns its waiter. When the thread is
canceled, it is removed from seq
.
add_task_l seq
creates a sleeping thread, adds its wakener to
the left of seq
and returns its waiter. When the thread is
canceled, it is removed from seq
.
pause ()
is a sleeping thread which is wake up on the next
call to wakeup_paused. A thread created with pause
can be
canceled.
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
threads.
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 wakeup_paused when there is no scheduler
on_success t f
executes f
when t
terminates without
failing. If f
raises an exception it is given to
async_exception_hook.
on_failure t f
executes f
when t
terminates and fails. If
f
raises an exception it is given to
async_exception_hook.
on_termination t f
executes f
when t
terminates. If f
raises an exception it is given to async_exception_hook.
on_any t f g
executes f
or g
when t
terminates. If f
or g
raises an exception it is given to
async_exception_hook.