Module Std.Monitor

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 monitor

val 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.

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 monitor

errors 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.