package lwt

The type of threads returning a result of type 'a.

return e is a thread whose return value is the value of the expression e.

fail e is a thread that fails with the exception e.

fail_with msg is a thread that fails with the exception Failure msg.

fail_invalid_arg msg is a thread that fails with the exception Invalid_argument msg.

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.

t >>= f is an alternative notation for bind t f.

f =<< t is t >>= f

map f m maps 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

return_unit = return ()

return_none = return None

return_some x = return (Some x)

return_nil = return []

return_true = return true

return_false = return false

return_ok x is equivalent to return (Ok x).

• since 2.6.0

return_error x is equivalent to return (Error x).

• since 2.6.0

Type of a key. Keys are used to store local values into threads.

new_key () creates a new key.

get key returns the value associated with key in the current thread.

with_value key value f executes f with value associated to key. key is restored to its previous value after f terminates.

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.

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.

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

choose l behaves as the first thread in l to terminate. If several threads are already terminated, one is chosen at random.

Note: choose leaves the local values of the current thread unchanged.

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.

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.

t <?> t' is the same as choose [t; t']

t <&> t' is the same as join [t; t']

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 behaves as follows:

• 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... *).

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.

See the manual for how to enable backtraces.

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 but it is not guaranteed that the thread will be woken up immediately.

Same as wakeup_exn but it is not guaranteed that the thread will be woken up immediately.

Returns the thread associated to a wakener.

Either a value of type 'a, either an exception.

This type is defined as ('a, exn) Result.result since 2.6.0.

value x creates a result containing the value x.

• deprecated

  Since 2.6.0. Use Result.Ok

error e creates a result containing the exception e.

• deprecated

  Since 2.6.0. Use Result.Error

Returns a thread from a result.

wakeup_result t r makes the sleeping thread t terminate with the result r.

Same as wakeup_result but it is not guaranteed that the thread will be woken up immediately.

State of a thread

state t returns the state of a thread

is_sleeping t returns true iff t is sleeping.

Canceled threads fails with this exception

task () is the same as wait () except that threads created with task can be canceled.

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.

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")

waiter will be woken up with Canceled.

pick l is the same as choose, except that it cancels all sleeping threads when one terminates.

Note: pick leaves the local values of the current thread unchanged.

npick l is the same as nchoose, except that it cancels all sleeping threads when one terminates.

Note: npick leaves the local values of the current thread unchanged.

protected thread creates a new cancelable thread which behave as thread except that cancelling it does not cancel thread.

no_cancel thread creates a thread which behave as thread except that it cannot be canceled.

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.

Infix operators. You should open only this module.