current () returns the current monitor
detach t detaches t so that errors raised to t are not passed to t's parent
monitor. If those errors aren't handled in some other way, then they will effectively
be ignored. One should usually use detach_and_iter_errors so that errors are not
ignored.
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.
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.
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. By default, the error will not contain a backtrace. However, the caller
can supply one using `This, or use `Get to request that send_exn obtain one
using Exn.backtrace ().
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 some error. It either runs f now, if
run = `Now, or schedules a job to run f, if run = `Schedule. Once a result is
returned, the rest of the errors raised by f are logged or re-raised, as per rest.
try_with never raises synchronously, and may only raise asynchronously with rest =
`Raise.
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.
try_with runs f () in a new monitor t that has no parent. This works because
try_with calls detach_and_get_error_stream t and explicitly handles all errors
sent to t. No errors would ever implicitly propagate to t's parent, although
try_with will explicitly send them to t's parent with rest = `Raise.
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. One typically wants
extract_exn = false due to the additional information. However, sometimes one wants
the concision of extract_exn = true.
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
= try_with f ?extract_exn ~run:`Now ~rest:`Log >>| Or_error.of_exn_result
~run:`Now is different from try_with's default, ~run:`Schedule. Based on
experience, we think ~run:`Now is a better behavior.
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.
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 it the initial monitor and is the root of the monitor tree. Unhandled exceptions are raised to this monitor.