module Monitor: Monitor
type
t
type'a
with_optional_monitor_name =?here:Core.Std.Source_code_position.t ->
?info:Core.Std.Info.t -> ?name:string -> 'a
val create : (unit -> t) with_optional_monitor_name
create ()
returns a new monitor whose parent is the current monitor.val name : t -> Core.Std.Info.t
name t
returns the name of the monitor, or a unique id if no name was supplied to
create
.val current : unit -> t
current ()
returns the current monitorval errors : t -> exn Tail.Stream.t
errors t
returns a stream of all subsequent errors that monitor t
sees.val error : t -> exn Deferred.t
error t
returns a deferred that becomes defined if the monitor ever sees an error.
Calling error t
does not count as "listening for errors", and if no one has called
errors t
to listen, then errors will still be raised up the monitor tree.val extract_exn : exn -> exn
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.val has_seen_error : t -> bool
has_seen_error t
returns true iff the monitor has ever seen an error.val send_exn : t -> ?backtrace:[ `Get | `This of string ] -> exn -> unit
send_exn t exn ?backtrace
sends the exception exn
as an error to be handled
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 ()
.val try_with : (?extract_exn:bool ->
?run:[ `Now | `Schedule ] ->
?rest:[ `Ignore | `Raise ] ->
(unit -> 'a Deferred.t) -> ('a, exn) Core.Std.Result.t Deferred.t)
with_optional_monitor_name
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 ignored 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.
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
.
val handle_errors : ((unit -> 'a Deferred.t) -> (exn -> unit) -> 'a Deferred.t)
with_optional_monitor_name
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.val catch_stream : ((unit -> unit) -> exn Tail.Stream.t) with_optional_monitor_name
catch_stream ?name f
runs f ()
inside a new monitor m
and returns the stream of
errors raised to m
.val catch : ((unit -> unit) -> exn Deferred.t) with_optional_monitor_name
catch ?name f
runs f ()
inside a new monitor m
and returns the first error
raised to m
.val protect : ((unit -> 'a Deferred.t) ->
finally:(unit -> unit Deferred.t) -> 'a Deferred.t)
with_optional_monitor_name
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.
val main : t
val kill : t -> unit
kill t
causes t
and all of t
's descendants to never start another job. The job
that calls kill
will complete, even if it is a descendant of t
.
kill
can break user expectations. For example, users expect in protect f ~finally
that finally
will eventually run. However, if the monitor in which finally
would
run is killed, then finally
will never run.
val is_alive : t -> bool
is_alive t
returns true
iff none of t
or its ancestors have been killed.module Exported_for_scheduler:sig
..end
val sexp_of_t : t -> Sexplib.Sexp.t
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 monitorerrors t
returns a stream of all subsequent errors that monitor t
sees.error t
returns a deferred that becomes defined if the monitor ever sees an error.
Calling error t
does not count as "listening for errors", and if no one has called
errors t
to listen, then errors will still be raised 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
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 ignored 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.
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
.
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.
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
.
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.
kill t
causes t
and all of t
's descendants to never start another job. The job
that calls kill
will complete, even if it is a descendant of t
.
kill
can break user expectations. For example, users expect in protect f ~finally
that finally
will eventually run. However, if the monitor in which finally
would
run is killed, then finally
will never run.
is_alive t
returns true
iff none of t
or its ancestors have been killed.