Struct ProcessHandle 

pub struct ProcessHandle<O: OutputStream> { /* private fields */ }

A handle to a spawned process with captured stdout/stderr streams.

This type provides methods for waiting on process completion, terminating the process, and accessing its output streams. By default, processes must be explicitly waited on or terminated before being dropped (see ProcessHandle::must_be_terminated).

If applicable, a process handle can be wrapped in a TerminateOnDrop to be terminated automatically upon being dropped. Note that this requires a multi-threaded runtime!

Implementations

impl ProcessHandle<BroadcastOutputStream>

pub async fn wait_for_completion_with_output( &mut self, timeout: Option<Duration>, options: LineParsingOptions, ) -> Result<Output, WaitError>

Convenience function, waiting for the process to complete using ProcessHandle::wait_for_completion while collecting both stdout and stderr into individual Vec<String> collections using the provided LineParsingOptions.

You may want to destructure this using:

let Output {
    status,
    stdout,
    stderr
} = proc.wait_for_completion_with_output(None, LineParsingOptions::default()).await.unwrap();

pub async fn wait_for_completion_with_output_or_terminate( &mut self, wait_timeout: Duration, interrupt_timeout: Duration, terminate_timeout: Duration, options: LineParsingOptions, ) -> Result<Output, WaitError>

Convenience function, waiting for the process to complete using ProcessHandle::wait_for_completion_or_terminate while collecting both stdout and stderr into individual Vec<String> collections using the provided LineParsingOptions.

impl ProcessHandle<SingleSubscriberOutputStream>

pub async fn wait_for_completion_with_output( &mut self, timeout: Option<Duration>, options: LineParsingOptions, ) -> Result<Output, WaitError>

Convenience function, waiting for the process to complete using ProcessHandle::wait_for_completion while collecting both stdout and stderr into individual Vec<String> collections using the provided LineParsingOptions.

You may want to destructure this using:

let Output {
    status,
    stdout,
    stderr
} = proc.wait_for_completion_with_output(None, LineParsingOptions::default()).await.unwrap();

pub async fn wait_for_completion_with_output_or_terminate( &mut self, wait_timeout: Duration, interrupt_timeout: Duration, terminate_timeout: Duration, options: LineParsingOptions, ) -> Result<Output, WaitError>

Convenience function, waiting for the process to complete using ProcessHandle::wait_for_completion_or_terminate while collecting both stdout and stderr into individual Vec<String> collections using the provided LineParsingOptions.

impl<O: OutputStream> ProcessHandle<O>

pub fn id(&self) -> Option<u32>

Returns the OS process ID if the process hasn’t exited yet.

Once this process has been polled to completion this will return None.

pub fn is_running(&mut self) -> RunningState

Checks if the process is currently running.

Returns RunningState::Running if the process is still running, RunningState::Terminated if it has exited, or RunningState::Uncertain if the state could not be determined.

pub fn stdin(&mut self) -> &mut Stdin

Returns a mutable reference to the (potentially already closed) stdin stream.

Use this to write data to the child process’s stdin. The stdin stream implements tokio::io::AsyncWrite, allowing you to use methods like write_all() and flush().

Example

// Whether we `spawn_broadcast` or `spawn_single_subscriber` does not make a difference here.
let mut process = Process::new(Command::new("cat"))
    .spawn_broadcast()
    .unwrap();

// Write to stdin.
if let Some(stdin) = process.stdin().as_mut() {
    stdin.write_all(b"Hello, process!\n").await.unwrap();
    stdin.flush().await.unwrap();
}

// Close stdin to signal EOF.
process.stdin().close();

pub fn stdout(&self) -> &O

Returns a reference to the stdout stream.

For BroadcastOutputStream, this allows creating multiple concurrent consumers. For SingleSubscriberOutputStream, only one consumer can be created (subsequent attempts will panic with a helpful error message).

pub fn stderr(&self) -> &O

Returns a reference to the stderr stream.

For BroadcastOutputStream, this allows creating multiple concurrent consumers. For SingleSubscriberOutputStream, only one consumer can be created (subsequent attempts will panic with a helpful error message).

pub fn must_be_terminated(&mut self)

Sets a panic-on-drop mechanism for this ProcessHandle.

This method enables a safeguard that ensures that the process represented by this ProcessHandle is properly terminated or awaited before being dropped. If must_be_terminated is set and the ProcessHandle is dropped without invoking terminate() or wait(), an intentional panic will occur to prevent silent failure-states, ensuring that system resources are handled correctly.

You typically do not need to call this, as every ProcessHandle is marked by default. Call must_not_be_terminated to clear this safeguard to explicitly allow dropping the process without terminating it.

Panic

If the ProcessHandle is dropped without being awaited or terminated after calling this method, a panic will occur with a descriptive message to inform about the incorrect usage.

pub fn must_not_be_terminated(&mut self)

Disables the panic-on-drop safeguard, allowing the spawned process to be kept running uncontrolled in the background, while this handle can safely be dropped.

pub fn terminate_on_drop( self, graceful_termination_timeout: Duration, forceful_termination_timeout: Duration, ) -> TerminateOnDrop<O>

Wrap this process handle in a TerminateOnDrop instance, terminating the controlled process automatically when this handle is dropped.

SAFETY: This only works when your code is running in a multithreaded tokio runtime!

Prefer manual termination of the process or awaiting it and relying on the (automatically configured) must_be_terminated logic, raising a panic when a process was neither awaited nor terminated before being dropped.

pub fn send_interrupt_signal(&mut self) -> Result<(), Error>

Manually send a SIGINT on unix or equivalent on Windows to this process.

Prefer to call terminate instead, if you want to make sure this process is terminated.

pub fn send_terminate_signal(&mut self) -> Result<(), Error>

Manually send a SIGTERM on unix or equivalent on Windows to this process.

Prefer to call terminate instead, if you want to make sure this process is terminated.

pub async fn terminate( &mut self, interrupt_timeout: Duration, terminate_timeout: Duration, ) -> Result<ExitStatus, TerminationError>

Terminates this process by sending a SIGINT, SIGTERM or even a SIGKILL if the process doesn’t run to completion after receiving any of the first two signals.

This handle can be dropped safely after this call returned, no matter the outcome. We accept that in extremely rare cases, failed SIGKILL, a rogue process may be left over.

pub async fn kill(&mut self) -> Result<()>

Forces the process to exit. Most users should call ProcessHandle::terminate instead.

This is equivalent to sending a SIGKILL on unix platforms followed by wait.

pub async fn wait_for_completion( &mut self, timeout: Option<Duration>, ) -> Result<ExitStatus, WaitError>

Wait for this process to run to completion. Within timeout, if set, or unbound otherwise.

If the timeout is reached before the process terminated, an error is returned but the process remains untouched / keeps running. Use ProcessHandle::wait_for_completion_or_terminate if you want immediate termination.

This does not provide the processes output. You can take a look at the convenience function ProcessHandle::::wait_for_completion_with_output to see how the ProcessHandle::stdout and ProcessHandle::stderr streams (also available in *_mut variants) can be used to inspect / watch over / capture the processes output.

pub async fn wait_for_completion_or_terminate( &mut self, wait_timeout: Duration, interrupt_timeout: Duration, terminate_timeout: Duration, ) -> Result<ExitStatus, TerminationError>

Wait for this process to run to completion within timeout.

If the timeout is reached before the process terminated normally, external termination of the process is forced through ProcessHandle::terminate.

Note that this function may return Ok even though the timeout was reached, carrying the exit status received after sending a termination signal!

pub fn into_inner(self) -> (Child, O, O)

Consumes this handle to provide the wrapped tokio::process::Child instance as well as the stdout and stderr output streams.

Trait Implementations

impl<O: Debug + OutputStream> Debug for ProcessHandle<O>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.