ProcessKit API Reference
PipelineSession Type
A live streaming session over a whole pipeline — the multi-stage analogue of `RunningProcess`, returned by `Pipeline.StartAsync`. It gives a pipeline the streaming layer a single command has long had: stream the **final** stage's stdout line by line as it arrives (`StdoutLinesAsync` / `StdoutJsonLinesAsync` / `OutputEventsAsync`), wait on a readiness line (`WaitForLineAsync`), wait for the whole chain to finish with the SAME pipefail classification the buffering verbs use (`FinishAsync`), or stop / reap the entire chain (`StopAsync` / `Kill` / dispose). Disposing it reaps every stage's tree (kill-on-drop), just like disposing a `RunningProcess`. **Single consumption** (the `RunningProcess` rule, [[K-031]]): the final stage's stdout is pumped exactly once, so `StdoutLinesAsync` and `OutputEventsAsync` are mutually exclusive — a second, different consumer throws `"already consumed by another verb"`. `FinishAsync` rejoins the SAME stdout-streaming session `StdoutLinesAsync` started (so it is the natural "wait for the rest" after streaming lines); after `OutputEventsAsync`, use `StopAsync` (or dispose) to reap. These hold because the session delegates every streaming/consuming verb to one underlying `RunningProcess`. **Whole-chain semantics.** The stream is the final stage's stdout, but `FinishAsync`/`StopAsync` reap and classify the ENTIRE chain: the returned `Finished.Outcome` is the pipefail representative (the rightmost checked stage that did not exit with an accepted code, or a `TimedOut`/`Cancelled` for the whole chain); when no checked stage failed, it is the final stage's real outcome, including an accepted unchecked non-zero exit. `Finished.Stderr` is that representative stage's stderr — identical to what `Pipeline.RunAsync` would report. Stopping or disposing tears down EVERY stage (including a partially started chain), never just the last. A genuine read failure in an upstream inter-stage relay is returned by `FinishAsync` as `ProcessError.Io`, even if the downstream stage observed the resulting EOF and exited successfully; a downstream broken pipe remains routine. That relay failure also tears the whole chain down the moment it is seen — it never waits out a still-running upstream stage that has simply stopped writing — so the streamed final-stage output ends wherever that kill lands.
Instance members
| Instance member |
Description
|
|
Wait for the WHOLE chain to finish, then return how it concluded (the pipefail representative's `Outcome`) plus that stage's stderr and a truncation signal combining the final stdout stream with that representative stderr — with the same classification `Pipeline.RunAsync` applies: an `OutputTooLarge` on any stage's fail-loud stream, or a stage-0 stdin-source failure on an otherwise-successful run, surfaces as `Error`, and a whole-chain cancellation is `Cancelled`. A genuine upstream relay read fault also surfaces as `ProcessError.Io` — and, having torn the chain down when it happened, returns promptly rather than waiting out a silent upstream stage; a downstream broken pipe is routine early-consumer teardown. A non-zero pipefail exit is *data* in `Finished.Outcome`, not an `Error`. Reaps the whole tree. Pairs with `StdoutLinesAsync` (it rejoins that stdout-streaming session); called with no prior streaming it drains and discards the final stdout as it arrives — retaining nothing — then reports the outcome, after which `StdoutLinesAsync`/`StdoutJsonLinesAsync`/`WaitForLineAsync` are refused as already-consumed rather than answered with an empty stream (see `RunningProcess.FinishAsync`).
|
Full Usage:
this.Kill
|
Signal the whole chain to die without waiting (fire-and-forget, like `RunningProcess.Kill`); the tree is fully reaped when the session is disposed. For a blocking stop, use `StopAsync` or dispose. |
|
Stream merged final-stage stdout line events as they arrive, each tagged `OutputEvent.Stdout` — the pipeline analogue of `RunningProcess.OutputEventsAsync`. A pipeline captures only the final stage's stdout (each earlier stage's stdout is wired into the next stage's stdin, and every stage's stderr is drained under its own byte cap for the pipefail result), so — unlike a single command — no `OutputEvent.Stderr` is produced here. Mutually exclusive with `StdoutLinesAsync`; after it, reap with `StopAsync` (or dispose) rather than `FinishAsync`.
|
Full Usage:
this.StdoutJsonLinesAsync
Parameters:
JsonTypeInfo<'T>
Returns: IAsyncEnumerable<'T>
Type parameters: 'T |
Like the overload above, but deserializes each line via a source-generated `JsonTypeInfo<'T>` — trim-/NativeAOT-safe.
|
Full Usage:
this.StdoutJsonLinesAsync
Parameters:
JsonSerializerOptions
Returns: IAsyncEnumerable<'T>
Type parameters: 'T |
Stream the final stage's stdout as NDJSON / JSON Lines (reflection-based `System.Text.Json`), each non-empty line deserialized into a `'T` as it arrives — the pipeline analogue of `RunningProcess.StdoutJsonLinesAsync`. Not trim-/AOT-safe; prefer the `JsonTypeInfo<'T>` overload in a trimmed/NativeAOT app.
|
|
Stream the FINAL stage's stdout line by line as it arrives — the pipeline analogue of `RunningProcess.StdoutLinesAsync`. Hands out its ONE enumerator exactly once; a second streaming consumer (this again, or `OutputEventsAsync`) throws. Call `FinishAsync` afterwards for the whole-chain outcome + the representative stage's stderr.
|
|
|
|
Gracefully stop the WHOLE chain (soft signal, wait up to `gracePeriod`, then hard-kill the remainder — the same machinery `RunningProcess.StopAsync` drives), reap every stage, and return the pipefail representative's `Outcome`. Safe to call after any streaming verb (or none) and idempotent/race-safe with `Kill`/dispose — the tree is reaped exactly once.
|
Full Usage:
this.WaitForLineAsync
Parameters:
Func<string, bool>
timeout : TimeSpan
?cancellationToken : CancellationToken
Returns: Task<Result<string, ProcessError>>
|
Wait until a final-stage stdout line satisfies `predicate`, or fail with `NotReady` after `timeout` (or `Cancelled` if `cancellationToken` fires first) — the pipeline analogue of `RunningProcess.WaitForLineAsync`. Consumed lines are not re-delivered; a later `StdoutLinesAsync`/ `FinishAsync` sees the rest.
|