Legend:
Library
Module
Module type
Parameter
Class
Class type
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 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 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.
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.
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 ->'at)->('a->'bt)->(exn ->'bt)->'bt
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 ().
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.
val nchoose_split : 'at list->('a list * 'at list)t
nchoose_split l does the same as 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: join 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).
if t has completed with a result, ignore_result t does nothing,
if t has completed with an exception, ignore_result t raises the exception,
if t has not completed, ignore_result t evaluates to () immediately, but if t completes later with an exception, it will be given to async_exception_hook.
Note that this means ignore_result t does not wait for t to complete. If you need to wait, use t >>= fun _ -> (* ...after t... *).
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).
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.
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 Canceled.
For example, in the following code:
let waiter, wakener = task () in
cancel (waiter >> printl "plop")
pause () is a sleeping thread which is wake up on the next call to wakeup_paused. A thread created with pause can be canceled.
val wakeup_paused : unit -> unit
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.
val paused_count : unit -> int
paused_count () returns the number of currently paused threads.
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 wakeup_paused when there is no scheduler