package async_kernel

create () returns a new monitor whose parent is the current monitor.

name t returns the name of the monitor, or a unique id if no name was supplied to create.

current () returns the current monitor.

detach t detaches t, removing its parent, so that errors raised to t are not passed to its former parent monitor. If those errors aren't handled in some other way (e.g. via get_next_error), then they will be ignored. One should usually use detach_and_iter_errors so that errors are not ignored.

If t is already detached, then detach does nothing. For example, it does not remove existing handlers added with detach_and_iter_errors.

detach_and_iter_errors t ~f detaches t and passes to f all subsequent errors that reach t, stopping iteration if f raises an exception. An exception raised by f is sent to the monitor in effect when detach_and_iter_errors was called.

detach_and_get_next_error t detaches t and returns a deferred that becomes determined with the next error that reaches t (possibly never).

detach_and_get_error_stream t detaches t and returns a stream of all subsequent errors that reach t.

Stream.iter (detach_and_get_error_stream t) ~f is equivalent to detach_and_iter_errors t ~f.

get_next_error t returns a deferred that becomes determined the next time t gets an error, if ever. Calling get_next_error t does not detach t, and if no other call has detached t, then errors will still bubble up the monitor tree. That includes the error returned by get_next_error, which will then be handled twice.

When extract_exn is set to false, exceptions returned by try_with are wrapped into this exception type which also provides backtrace information.

extract_exn exn extracts the exn from an error exn that comes from a monitor. If it is not supplied such an error exn, it returns the exn itself. It removes the backtrace from the error (see discussion in try_with).

has_seen_error t returns true iff the monitor has ever seen an error.

send_exn t exn ?backtrace sends the exception exn as an error to be handled by monitor t. If the backtrace is not specified, it defaults to `Get, which means that the backtrace will be collected automatically. Automatic backtrace collection only works if exn is the most recently raised exception.

try_with f runs f () in a monitor and returns the result as Ok x if f finishes normally, or returns Error e if there is an exception. It either runs f now, if run = `Now, or schedules a job to run f, if run = `Schedule. Once a result is returned, subsequent exceptions raised to the monitor are handled according to rest:

• `Log: Logged to a global error log (cannot raise).
• `Raise: Reraised to the monitor of try_with's caller.
• `Call f: Passed to f within the context of the monitor of try_with's caller.

The name argument is used to give a name to the monitor the computation will be running in. This name will appear when printing errors.

If extract_exn = true, then in an Error exn result, the exn will be the actual exception raised by the computation. If extract_exn = false, then the exn will include additional information, like the monitor and backtrace.

try_with_or_error is like try_with but returns 'a Or_error.t Deferred.t instead of ('a,exn) Result.t Deferred.t. More precisely:

try_with_or_error f ?extract_exn ~rest
= try_with f ?extract_exn ~run:`Now ~rest >>| Or_error.of_exn_result 

try_with_join_or_error f = try_with_or_error f >>| Or_error.join.

handle_errors ?name f handler runs f () inside a new monitor with the optionally supplied name, and calls handler error on every error raised to that monitor. Any error raised by handler goes to the monitor in effect when handle_errors was called.

Errors that are raised after f () becomes determined will still be sent to handler, i.e., the new monitor lives as long as jobs created by f live.

catch_stream ?name f runs f () inside a new monitor m and returns the stream of errors raised to m.

catch ?name f runs f () inside a new monitor m and returns the first error raised to m.

catch_error ?name f runs f () inside of a new monitor m and returns the first error raised to m.

protect f ~finally runs f () and then finally regardless of the success or failure of f. It re-raises any exception thrown by f or returns whatever f returned.

The name argument is used to give a name to the monitor the computation will be running in. This name will appear when printing the errors.

This is the initial monitor and is the root of the monitor tree. Unhandled exceptions are raised to this monitor.