Logo ProcessKit API Reference

ProcessGroup Type

A kill-on-dispose container for a process *tree*. Every process started into the group — and everything those processes spawn — is reaped when the group is disposed (deterministic under `use`) or, failing that, when the GC finalizes it. The OS primitive is chosen at creation and reported honestly by `Mechanism` — a Windows Job Object (`KILL_ON_JOB_CLOSE`), a Linux cgroup v2 (when resource limits are requested), or a POSIX process group (`killpg` teardown). All of that lives behind an `IContainmentBackend`; this type only orchestrates once-only teardown, the stdin/stream wiring, and the runner/disposable seams.

Instance members

Instance member Description

this.KillAll

Full Usage: this.KillAll

Returns: Result<unit, ProcessError>

Immediately hard-kill every process currently in the group (the honest name for the tree kill — no graceful signal). Idempotent; the group stays usable for further spawns. Returns `Result` for parity with the other tree-control verbs (a future backend can report an undrained tree); the current backends always succeed.

Returns: Result<unit, ProcessError>

this.Mechanism

Full Usage: this.Mechanism

Returns: Mechanism

The OS primitive containing this group on the current platform.

Returns: Mechanism

this.Members

Full Usage: this.Members

Returns: Result<IReadOnlyList<int>, ProcessError>

The pids of the processes currently in the group — a point-in-time snapshot. On Windows the whole Job tree, on cgroup v2 the whole cgroup, on the POSIX fallback the tracked group leaders.

Returns: Result<IReadOnlyList<int>, ProcessError>

this.Options

Full Usage: this.Options

Returns: ProcessGroupOptions

The options the group was created with (shutdown grace, resource limits).

Returns: ProcessGroupOptions

this.Resume

Full Usage: this.Resume

Returns: Result<unit, ProcessError>

Resume a tree suspended by `Suspend`.

Returns: Result<unit, ProcessError>

this.SampleStatsAsync

Full Usage: this.SampleStatsAsync

Parameters:
Returns: IAsyncEnumerable<ProcessGroupStats>

A periodic `ProcessGroupStats` series: the first sample immediately, then one per `interval`. **Pull-based** — it samples only as the enumeration is pulled and runs no background task, so it neither keeps the group alive nor leaks if abandoned. The series ends on the first snapshot the group fails to report (notably after it is torn down) or when the enumerator's token fires.

interval : TimeSpan
Returns: IAsyncEnumerable<ProcessGroupStats>

this.ShutdownAsync

Full Usage: this.ShutdownAsync

Returns: Task

`ShutdownAsync` using the group's configured `Options.ShutdownTimeout`.

Returns: Task

this.ShutdownAsync

Full Usage: this.ShutdownAsync

Parameters:
Returns: Task

Tear the group down gracefully, then release it. On Unix: SIGTERM, then SIGKILL if still alive after `gracePeriod`. On Windows: an atomic Job kill. Idempotent with `Dispose`.

gracePeriod : TimeSpan
Returns: Task

this.Signal

Full Usage: this.Signal

Parameters:
Returns: Result<unit, ProcessError>

Broadcast `signal` to every process in the group. A member that has already exited (or an already-empty group) is a best-effort success — that races the target's own exit, not a caller error. An invalid delivery — most notably `Signal.Other` with a signal number the platform rejects — is a genuine failure and returns `ProcessError.Io` with the errno detail; when the group has several members, the first genuine failure is reported but every member still receives the signal. On **Windows** `Signal.Kill` maps to the atomic Job terminate. `Signal.Int` and `Signal.Term` are delivered as a best-effort console **CTRL+BREAK**, but ONLY to children started with `Command.WindowsCtrlSignals()` (spawned in their own console process group): if the group has no such child, or the caller has no console to share with it, the call returns `ProcessError.Unsupported` rather than silently downgrading to a kill. Delivery is not guaranteed even on success — a console child may install its own handler. Every other Windows signal returns `ProcessError.Unsupported`.

signal : Signal
Returns: Result<unit, ProcessError>

this.StartAsync

Full Usage: this.StartAsync

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

Start `command` into this shared group and return a live `RunningProcess`. The **group** owns the child's lifetime: disposing the returned process detaches its I/O but does not kill it — reap the tree with `ShutdownAsync`/`Dispose`, or this one run with its `Kill`. `cancellationToken` is checked once, before the spawn (an already-cancelled token reports `ProcessError.Cancelled` and starts nothing); once the child is running the token is not tracked — this live handle is caller-driven, so kill or reap it yourself. (The capture/completion verbs on a `ProcessGroup` do watch the token — and the command's `CancelOn` — for the whole run.)

command : Command
?cancellationToken : CancellationToken
Returns: Task<Result<RunningProcess, ProcessError>>

this.Stats

Full Usage: this.Stats

Returns: Result<ProcessGroupStats, ProcessError>

A snapshot of the group's resource usage. On Windows this reads the Job Object's accounting (CPU + peak committed memory + active count); on cgroup v2 the cgroup accounting; on the POSIX fallback only the live group count (CPU/memory are `None`). Errors once the group is released.

Returns: Result<ProcessGroupStats, ProcessError>

this.Suspend

Full Usage: this.Suspend

Returns: Result<unit, ProcessError>

Suspend (freeze) every process in the group. POSIX: `SIGSTOP` (level-triggered, idempotent). Cgroup v2: `cgroup.freeze`. Windows: suspend every thread of every member — best-effort, and suspend counts stack, so N `Suspend`s need N `Resume`s.

Returns: Result<unit, ProcessError>

Static members

Static member Description

ProcessGroup.Create(options)

Full Usage: ProcessGroup.Create(options)

Parameters:
Returns: Result<ProcessGroup, ProcessError>

Create a new kill-on-dispose group with `options` (graceful-shutdown window and whole-tree resource limits). When `options.Limits` is set, the group needs a limit-capable mechanism — a Windows Job Object or a Linux cgroup v2 at the real cgroup root; otherwise creation fails fast with `ProcessError.ResourceLimit` rather than leaving the tree unbounded. Without limits the group uses the platform's default mechanism (Job Object / POSIX process group). On the Linux cgroup v2 mechanism, a spawned child is migrated into the cgroup right after it starts, and the limits then apply to it and every descendant it forks *afterwards*. A grandchild forked in the brief spawn→migrate window is created in the parent cgroup and stays there — still reaped by kill-on-drop teardown, but outside the resource limits. If the child cannot be migrated at all (e.g. the cgroup was torn down underneath the spawn), it is killed and reaped and the spawn fails with `ProcessError.ResourceLimit` — never left running unconstrained.

options : ProcessGroupOptions
Returns: Result<ProcessGroup, ProcessError>

ProcessGroup.Create()

Full Usage: ProcessGroup.Create()

Returns: Result<ProcessGroup, ProcessError>

Create a new, empty kill-on-dispose group on the current platform (no resource limits).

Returns: Result<ProcessGroup, ProcessError>

Type something to start searching.