Struct Handle

pub struct Handle { /* private fields */ }

A handle to a running Expression, returned by the start method.

Calling start followed by into_output on the handle is equivalent to run. Note that unlike std::process::Child, most of the methods on Handle take &self rather than &mut self, and a Handle may be shared between multiple threads.

If you drop a Handle without first waiting on the child to exit, it will try_wait internally to see if it can reap the child. If the child is still running, its handle will be added to a global list and polled whenever new child processes are spawned. This avoids leaking zombie processes on Unix platforms. This Drop implementation is omitted on Windows, where zombies aren’t a problem.

See the shared_child crate for implementation details behind making handles thread safe.

Implementations

impl Handle

pub fn wait(&self) -> Result<&Output>

Wait for the running Expression to finish, and return a reference to its std::process::Output. Multiple threads may wait at the same time, and waiting more than once returns the same output again.

Errors

In addition to all the IO errors possible with std::process::Child, wait will return an ErrorKind::Other IO error if the child returns a non-zero exit status. To suppress this error and return an Output even when the exit status is non-zero, use the unchecked method.

pub fn wait_timeout(&self, timeout: Duration) -> Result<Option<&Output>>

Same as wait, but with a timeout. If the running Expression finishes within the timeout (or if it’s already finished), return a reference to its std::process::Output. Otherwise, return Ok(None).

Errors

Same as wait.

pub fn wait_deadline(&self, deadline: Instant) -> Result<Option<&Output>>

Same as wait_timeout, but with a deadline instead of a timeout.

Errors

Same as wait.

pub fn try_wait(&self) -> Result<Option<&Output>>

Check whether the running Expression has already finished. If it has, return a reference to its std::process::Output. Otherwise, return Ok(None).

Errors

Same as wait.

pub fn into_output(self) -> Result<Output>

Same as wait, but consume the Handle and return its std::process::Output by value. Calling start followed by into_output is equivalent to run.

Errors

Same as wait.

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

Kill all the child processes in the running Expression.

Note that as with std::process::Child::kill, this does not kill any grandchild processes that the children have spawned on their own. It only kills the child processes that Duct spawned itself. See gotchas.md for an extensive discussion of this behavior.

This method does not wait on the child processes to exit. Calling wait after kill usually returns quickly, but there are edge cases where it might not. The most common case is if a grandchild process has inherited one or more of the child’s stdin/stdout/stderr pipes, and a worker thread related to stdin_bytes/stdout_capture][Expression::stdout_capture]/[stderr_capture is still running. The kill signal might also be delayed if the child is blocked reading an unresponsive FUSE filesystem, or paused by a debugger.

pub fn pids(&self) -> Vec<u32>

Return a Vec<u32> containing the PIDs of all of the child processes. The PIDs are given in pipeline order, from left to right.

Trait Implementations

impl Debug for Handle

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

Formats the value using the given formatter.

impl HandleExt for Handle

fn send_signal(&self, signal: c_int) -> Result<()>

Send a signal to all child processes running under this expression.