pub struct ProcessSubscription<M: Send + 'static> { /* private fields */ }Expand description
A subscription that spawns and monitors an external process.
Captures stdout/stderr line-by-line and sends ProcessEvent messages.
Termination is requested when the subscription’s StopSignal fires or
when the optional timeout expires. ProcessEvent::Killed requires a
successful kill request and confirmed reaping (with SIGKILL status on Unix).
Failed or unconfirmed cleanup produces ProcessEvent::Error.
Normal exit waits for stdout/stderr forwarding to finish, including bounded
channel backpressure. The timeout remains active during that drain. If the
drain is canceled after the child exits, an error describes the exit and
incomplete output. Cancellation can reject an unsent line, preview, or final
status when the model queue is full; final-status delivery is not guaranteed.
Each UTF-8 line is limited to MAX_PROCESS_LINE_BYTES payload bytes.
LF and its immediately preceding CR are excluded from the limit. An
unterminated final line is delivered at EOF (preserving any trailing CR).
Opt-in partial_output also previews growing valid
prefixes before the next read blocks. It does not change completed lines.
Oversized lines, invalid UTF-8, and read failures stop forwarding, request
termination of the immediate child, and produce one error instead of a
normal exit. That error reports incomplete output and the cleanup outcome.
Monitoring and input failures use the same cleanup path. After an accepted
kill request, foreground reaping is limited to 500 ms; a rejected request
never leads to a blocking foreground wait. If ownership remains safe, an
unconfirmed child is handed to a background reaper. If that thread cannot
start, the error says so; a later wait failure is logged and leaves restart
disabled. Late reaping does not turn the earlier error into success. Linux
retains a pidfd when available; after a wait error, targets without a
retained process handle refuse further waits and signals for that PID.
On Unix, parent pipe endpoints use nonblocking I/O and readiness waits;
cancellation stops the workers even if descendants retain their endpoints.
Other targets still use blocking pipes and bounded joins, so an inherited
endpoint can keep a detached worker alive after cancellation.
Input is closed by default; stdin enables a bounded input
worker. Descendant termination and reaping are not provided on any target.
Cancellation is not an atomic write boundary: a prefix may already have
reached the child, and an I/O syscall can race with the stop request.
Optional control admits interrupts independently of those
queues. Its generation belongs to one run. Restart only after that run’s
terminal event and confirmed child cleanup, using a fresh control handle.
Implementations§
Source§impl<M: Send + 'static> ProcessSubscription<M>
impl<M: Send + 'static> ProcessSubscription<M>
Sourcepub fn new(
program: impl Into<String>,
make_msg: impl Fn(ProcessEvent) -> M + Send + Sync + 'static,
) -> Self
pub fn new( program: impl Into<String>, make_msg: impl Fn(ProcessEvent) -> M + Send + Sync + 'static, ) -> Self
Create a new process subscription for the given program.
The make_msg closure converts ProcessEvent into your model’s
message type.
Sourcepub fn args(self, args: impl IntoIterator<Item = impl Into<String>>) -> Self
pub fn args(self, args: impl IntoIterator<Item = impl Into<String>>) -> Self
Add multiple command-line arguments.
Sourcepub fn env(self, key: impl Into<String>, value: impl Into<String>) -> Self
pub fn env(self, key: impl Into<String>, value: impl Into<String>) -> Self
Set an environment variable for the child process.
Sourcepub fn timeout(self, duration: Duration) -> Self
pub fn timeout(self, duration: Duration) -> Self
Set a timeout after which the process is killed.
Sourcepub fn stdin(self, input: ProcessInput) -> Self
pub fn stdin(self, input: ProcessInput) -> Self
Connect bounded input for this process run.
Reuse clones of the same handle when rebuilding subscriptions. A new handle changes the automatic subscription ID. An already-used handle produces an error before spawning; use a new handle for a restart.
Sourcepub fn control(self, control: ProcessControl) -> Self
pub fn control(self, control: ProcessControl) -> Self
Attach supervisor-owned interrupt control for this run.
Clones preserve the automatic subscription ID. A fresh handle changes it, including when stdin is disabled. A used handle cannot spawn again.
Sourcepub fn partial_output(self, enabled: bool) -> Self
pub fn partial_output(self, enabled: bool) -> Self
Preview pending stdout/stderr lines before LF or EOF (default: false).
Each nonempty preview replaces the prior preview for that stream. It
contains the original cumulative valid UTF-8 prefix, including controls;
sanitize the whole prefix when rendering, rather than individual pieces.
An incomplete UTF-8 scalar and one possible CRLF delimiter are retained
until resolved. Completed ProcessEvent::Stdout and
ProcessEvent::Stderr events remain unchanged, including trailing CR
at EOF. Clear previews on completed lines and terminal events.
Previews share the bounded, interruptible output queue and the 64 KiB line bound; they can be delayed by backpressure. Earlier prefixes may already be visible when a later read fails UTF-8 or size validation. This does not force an unflushed child to write or provide arbitrary binary streaming. Unix pipe cancellation is independent of this setting; other targets can still block in OS reads. Changing this setting changes the automatic subscription ID.