Struct ChildHandle

pub struct ChildHandle { /* 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.

Like std::process::Child, Handle doesn’t do anything special in its destructor. If you drop a handle without waiting on it, child processes and background IO threads will keep running, and the children will become zombie processes when they exit. That’s a resource leak, similar to leaking memory or file handles. Note that in contrast to Handle, a ReaderHandle kills child processes in its destructor, to avoid creating zombies.

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

Implementations

impl Handle

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

Wait for the running expression to finish, and return a reference to its std::process::Output. Multiple threads may wait at the same time.

Errors

In addition to all the IO errors possible with std::process::Child, wait will return an ErrorKind::Other IO error if 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 try_wait(&self) -> Result<Option<&Output>, Error>

Check whether the running expression is finished. If it is, return a reference to its std::process::Output. If it’s still running, return Ok(None).

Errors

In addition to all the IO errors possible with std::process::Child, try_wait will return an ErrorKind::Other IO error if 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 into_output(self) -> Result<Output, Error>

Wait for the running expression to finish, and then return a std::process::Output object containing the results, including any captured output. This consumes the Handle. Calling start followed by into_output is equivalent to run.

Errors

In addition to all the IO errors possible with std::process::Child, into_output will return an ErrorKind::Other IO error if 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 kill(&self) -> Result<(), Error>

Kill the running expression and await all the child processes. Any errors that would normally result from a non-zero exit status are ignored, as with unchecked.

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.

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<(), Error>

Formats the value using the given formatter.