Trait StdChildWrapper

pub trait StdChildWrapper:
    Debug
    + Send
    + Sync
    + Any {
    // Required methods
    fn inner(&self) -> &Child;
    fn inner_mut(&mut self) -> &mut Child;
    fn into_inner(self: Box<Self>) -> Child;

    // Provided methods
    fn try_clone(&self) -> Option<Box<dyn StdChildWrapper>> { ... }
    fn stdin(&mut self) -> &mut Option<ChildStdin> { ... }
    fn stdout(&mut self) -> &mut Option<ChildStdout> { ... }
    fn stderr(&mut self) -> &mut Option<ChildStderr> { ... }
    fn id(&self) -> u32 { ... }
    fn kill(&mut self) -> Result<()> { ... }
    fn start_kill(&mut self) -> Result<()> { ... }
    fn try_wait(&mut self) -> Result<Option<ExitStatus>> { ... }
    fn wait(&mut self) -> Result<ExitStatus> { ... }
    fn wait_with_output(self: Box<Self>) -> Result<Output>
       where Self: 'static { ... }
    fn signal(&self, sig: i32) -> Result<()> { ... }
}

Available on crate features std and downcasting only.

Wrapper for std::process::Child.

This trait exposes most of the functionality of the underlying Child. It is implemented for StdChild (a thin wrapper around Child) (because implementing directly on Child would loop) and by wrappers.

The required methods are inner, inner_mut, and into_inner. That provides access to the underlying Child and allows the wrapper to be dropped and the Child to be used directly if necessary.

It also makes it possible for all the other methods to have default implementations. Some are direct passthroughs to the underlying Child, while others are more complex.

Here’s a simple example of a wrapper:

use process_wrap::std::*;
use std::process::Child;

#[derive(Debug)]
pub struct YourChildWrapper(Child);

impl StdChildWrapper for YourChildWrapper {
    fn inner(&self) -> &Child {
        &self.0
    }

    fn inner_mut(&mut self) -> &mut Child {
        &mut self.0
    }

    fn into_inner(self: Box<Self>) -> Child {
        (*self).0
    }
}

Required Methods

fn inner(&self) -> &Child

Obtain a reference to the underlying Child.

fn inner_mut(&mut self) -> &mut Child

Obtain a mutable reference to the underlying Child.

fn into_inner(self: Box<Self>) -> Child

Consume the wrapper and return the underlying Child.

Note that this may disrupt whatever the wrappers were doing. However, wrappers must ensure that the Child is in a consistent state when this is called or they are dropped, so that this is always safe.

Provided Methods

fn try_clone(&self) -> Option<Box<dyn StdChildWrapper>>

Obtain a clone if possible.

Some implementations may make it possible to clone the implementing structure, even though std’s Child isn’t Clone. In those cases, this method should be overridden.

fn stdin(&mut self) -> &mut Option<ChildStdin>

Obtain the Child’s stdin.

By default this is a passthrough to the underlying Child.

fn stdout(&mut self) -> &mut Option<ChildStdout>

Obtain the Child’s stdout.

By default this is a passthrough to the underlying Child.

fn stderr(&mut self) -> &mut Option<ChildStderr>

Obtain the Child’s stderr.

By default this is a passthrough to the underlying Child.

fn id(&self) -> u32

Obtain the Child’s process ID.

In general this should be the PID of the top-level spawned process that was spawned However, that may vary depending on what a wrapper does.

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

Kill the Child and wait for it to exit.

By default this calls start_kill() and then wait(), which is the same way it is done on the underlying Child, but that way implementing either or both of those methods will use them when calling kill(), instead of requiring a stub implementation.

fn start_kill(&mut self) -> Result<()>

Kill the Child without waiting for it to exit.

By default this is:

• on Unix, sending a SIGKILL signal to the process;
• otherwise, a passthrough to the underlying kill() method.

The start_kill() method doesn’t exist on std’s Child, and was introduced by Tokio. This library uses it to provide a consistent API across both std and Tokio (and because it’s a generally useful API).

fn try_wait(&mut self) -> Result<Option<ExitStatus>>

Check if the Child has exited without blocking, and if so, return its exit status.

Wrappers must ensure that repeatedly calling this (or other wait methods) after the child has exited will always return the same result.

By default this is a passthrough to the underlying Child.

fn wait(&mut self) -> Result<ExitStatus>

Wait for the Child to exit and return its exit status.

Wrappers must ensure that repeatedly calling this (or other wait methods) after the child has exited will always return the same result.

By default this is a passthrough to the underlying Child.

fn wait_with_output(self: Box<Self>) -> Result<Output>

where Self: 'static,

Wait for the Child to exit and return its exit status and outputs.

Note that this method reads the child’s stdout and stderr to completion into memory.

On Unix, this reads from stdout and stderr simultaneously. On other platforms, it reads from stdout first, then stderr (pull requests welcome to improve this).

By default this is a reimplementation of the std method, so that it can use the wrapper’s wait() method instead of the underlying Child’s wait().

fn signal(&self, sig: i32) -> Result<()>

Available on Unix only.

Send a signal to the Child.

This method is only available on Unix. It doesn’t exist on std’s Child, nor on Tokio’s. It was introduced by command-group to abstract over the signal behaviour between process groups and unwrapped processes.

Implementors

impl StdChildWrapper for ProcessGroupChild

Available on Unix and crate feature process-group only.

impl StdChildWrapper for StdChild