Logo ProcessKit API Reference

SupervisionSession Type

A live handle to a running supervision, returned by `Supervisor.StartAsync`. Unlike `RunAsync` — which only reports its `SupervisionOutcome` at the very end — a session lets a caller watch supervision *while it runs* (`Status`), ask it to stop *gracefully* (`StopAsync`), and await its eventual outcome (`Completion`). This is the primitive for building daemons / process managers on top of the runner layer without pulling in `Microsoft.Extensions.Hosting`. Thread-safe: `Status` is read under the same lock the supervision loop uses to publish each state change, so a concurrent read never races an update nor throws; `StopAsync` is idempotent and race-safe against the loop (and against a repeat call). Sealed with an internal constructor — build one via `Supervisor.StartAsync`.

Instance members

Instance member Description

this.Completion

Full Usage: this.Completion

Returns: Task<Result<SupervisionOutcome, ProcessError>>

The task that resolves to the final `SupervisionOutcome` (or a terminal `ProcessError`) when supervision ends — exactly what `Supervisor.RunAsync` returns. `await` it to block until supervision concludes on its own, via `StopAsync`, or via the `StartAsync` token's cancellation.

Returns: Task<Result<SupervisionOutcome, ProcessError>>

this.DroppedEventCount

Full Usage: this.DroppedEventCount

Returns: int64

How many events this session has dropped so far because the event stream's consumer fell behind its bounded capacity (or never read it) — the lifetime total behind the in-band `SupervisionEventKind.EventsDropped` markers, and the supervision analogue of `RunningProcess.DroppedStreamLineCount`. Always `0` when no stream was enabled, and while a consumer keeps up. Safe to read at any time, including after supervision has ended.

Returns: int64

this.EventsAsync

Full Usage: this.EventsAsync

Returns: IAsyncEnumerable<SupervisionEvent>

This session's typed lifecycle-event stream — incarnation starts and outcomes, launch-failure classes, scheduled restarts, storm pauses, health-check verdicts, give-up decisions, and the terminal reason — as an `IAsyncEnumerable` you drain while supervision runs (concurrently with `Completion`/`StopAsync`; the stream ends when supervision does). Requires the stream to have been enabled on the builder (`Supervisor.Events`), which is what gives the session somewhere to retain events from its very first incarnation — before any consumer could have asked for them. Without it this throws `InvalidOperationException`, rather than handing back a stream that would silently be missing the beginning of supervision. **One consumer.** Reading the buffer is destructive, so a second consumer would steal events from the first: call this once and share the enumeration, or a repeat call throws `InvalidOperationException`. Purely additive to the `OnRestart`/`OnStormPause` callbacks and the `Status` snapshot — enabling it changes no supervision decision, timing, or outcome. **Bounded, with an explicit gap marker.** The buffer holds at most the configured capacity of unread events. A consumer that keeps up loses nothing; one that falls behind (or never reads) makes the supervisor drop the OLDEST unread events to make room for newer ones — supervision is never slowed down or blocked by its observer. Each such gap is reported: the next event the consumer sees is a `SupervisionEventKind.EventsDropped` carrying exactly how many were lost, immediately before the oldest event that survived, and `DroppedEventCount` keeps the lifetime total.

Returns: IAsyncEnumerable<SupervisionEvent>

this.Status

Full Usage: this.Status

Returns: SupervisionStatus

A consistent live snapshot of this session's state (activity, restart count, storm-pause flag, and the current live incarnation's pid/start time). Cheap and lock-guarded — safe to poll from any thread, e.g. a health check, without racing the supervision loop.

Returns: SupervisionStatus

this.StopAsync

Full Usage: this.StopAsync

Returns: Task<Result<SupervisionOutcome, ProcessError>>

`StopAsync` using the default 2-second grace window (matching `RunningProcess.StopAsync`).

Returns: Task<Result<SupervisionOutcome, ProcessError>>

this.StopAsync

Full Usage: this.StopAsync

Parameters:
Returns: Task<Result<SupervisionOutcome, ProcessError>>

Request a graceful stop with `gracePeriod`: stop a live-handle incarnation through its own graceful path (`RunningProcess.StopAsync`, honouring the grace window), or immediately cancel a capture-only incarnation (which has no process handle to stop gracefully), and end the supervision loop with `StopReason.Stopped`. A stopped capture-only run whose exit status is unavailable reports `Outcome.Unobserved` in its final result. Interrupts an in-flight backoff / storm pause so a stop taken between incarnations also ends promptly, and never launches a further incarnation. A stop that lands before *any* incarnation has produced a result has no result to report and no child of its own to stop, so supervision ends with `RunAsync`'s `Error` rather than starting one more child just to manufacture a `SupervisionOutcome`: the last failure that kept the child from starting (while backing off after runs that only ever failed to start), or `Error(ProcessError.Cancelled)` when the stop landed before the very first incarnation, so there is no failure to report either. That second shape is the one case where a `ProcessError.Cancelled` does not come from a cancelled `CancellationToken` (see `ProcessError.Cancelled`). Idempotent and race-safe against the loop and repeat calls. Returns the session's `Completion`, so a caller can `await` the final outcome directly. A negative `gracePeriod` is rejected with `ArgumentOutOfRangeException`; `TimeSpan.Zero` escalates the child kill immediately.

gracePeriod : TimeSpan
Returns: Task<Result<SupervisionOutcome, ProcessError>>

Type something to start searching.