Module Async.Trace

Tracing asynchronous function activity.

Domain identifiers

type domain_id = {
  1. main : Stdlib.Domain.id;
    (*

    Identifier of the domain that calls Affect.Fun.Async.main

    *)
  2. index : int;
    (*

    Scheduler specific domain index. 0 must be the domain associated with main.

    *)
}

The type for affect domain identifiers.

val out_of_scheduler_domain_id : unit -> domain_id

out_of_scheduler_domain_id () is an identifier for when you don't have one.

val pp_domain_id : Stdlib.Format.formatter -> domain_id -> unit

pp_domain_id formats domain ids.

Traces

type payload =
  1. | Action_block of Call.id * Action.Private.Action.Meta.t
    (*

    Reported on a blocking Affect.Action.invoke.

    *)
  2. | Async_fun_call of {
    1. parent : Call.id;
    2. id : Call.id;
    }
    (*

    Reported on Affect.Fun.Async.call.

    *)
  3. | Async_fun_continue of Call.id
    (*

    Reported when a function continues its execution after it was called, yielded or blocked.

    *)
  4. | Async_fun_yield of Call.id
    (*

    Reported on Affect.Fun.Async.yield.

    *)
  5. | Async_fun_return of Call.id
    (*

    Reported when an asynchronous function returns.

    *)
  6. | Async_fun_trace of Call.id * string
    (*

    User defined trace, see Affect.Fun.Async.trace.

    *)
  7. | Domain_start
    (*

    Reported when domain starts its local scheduler.

    *)
  8. | Domain_sleep
    (*

    Reported when a domain starts sleeping.

    *)
  9. | Domain_unblocker of {
    1. block : bool;
    }
    (*

    Reported when a domain executes an unblocker.

    *)
  10. | Domain_resume
    (*

    Reported when a domain returns from sleep or the unblocker

    *)
  11. | Domain_panic of string
    (*

    Reported when a domain has an internal scheduler error.

    *)
  12. | Domain_stop
    (*

    Reported when a domain stops its local scheduler.

    *)

The type for trace payloads.

type t = domain_id * payload

The type for traces.

val is_domain : t -> bool

is_domain t is true iff the trace t only pertains to the life cycle of domains.

val is_fun : t -> bool

is_fun t is not (is_domain t) and true iff the trace t only pertains to asynchronous function activity or actions.

val is_user : t -> bool

is_user t is true iff t is Async_fun_trace.

Reporters

type reporter = t -> unit

The type for reporters.

val default_reporter : reporter

default_reporter is the default reporter (Stdlib.ignore).

val format_reporter : (unit -> Stdlib.Format.formatter) -> reporter

format_reporter ppf is a reporter using a synchronization safe formater ppf (see Format.get_std_formatter) and pp to report.

val stderr_reporter : reporter

stderr_reporter is format_reporter (Format.get_err_formatter).

Current

val reporter : unit -> reporter

reporter is the current reporter.

val set_reporter : reporter -> unit

set_reporter reporter sets the current reporter to reporter

val exchange_reporter : reporter -> reporter

exchange_reporter r sets the current reporter r and returns the previous reporter.

val with_reporter : reporter -> (unit -> 'a) -> 'a

with_reporter r f executes f () with current reporter r and restores the previous reporter after f returns or raises.

Filtering

val keep : (t -> bool) -> reporter -> reporter

keep sat reporter reports with reporter but only those sat satisfying trace are given to it.

val only_fun : reporter -> reporter

only_fun reporter is keep is_fun reporter.

val only_user : reporter -> reporter

only_user reporter is keep is_user reporter.

Delayed

module Delayed : sig ... end

Delayed reporters.

Reporting

val report : t -> unit

report t reports trace t on the current reporter.

Formatting

val pp_fun_trace : Stdlib.Format.formatter -> (domain_id * Call.id) -> unit

pp_call formats domain id and call identifier pairs.

val pp : Stdlib.Format.formatter -> t -> unit

pp formats a trace.