Trait ChildWrapper

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

    // Provided methods
    fn try_clone(&self) -> Option<Box<dyn ChildWrapper>> { ... }
    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 feature std only.

Wrapper for std::process::Child.

This trait exposes most of the functionality of the underlying Child. It is implemented for Child and by wrappers.

The required methods are inner, inner_mut, and into_inner. That provides access to the lower layer and ultimately allows the wrappers to be unwrap and the Child to be used directly if necessary. There are convenience inner_child, inner_child_mut and into_inner_child methods on the trait object.

It also makes it possible for all the other methods to have default implementations. Some are direct passthroughs to the lower layers, 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 ChildWrapper for YourChildWrapper {
    fn inner(&self) -> &dyn ChildWrapper {
        &self.0
    }

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

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

Required Methods

fn inner(&self) -> &dyn ChildWrapper

Obtain a reference to the wrapped child.

fn inner_mut(&mut self) -> &mut dyn ChildWrapper

Obtain a mutable reference to the wrapped child.

fn into_inner(self: Box<Self>) -> Box<dyn ChildWrapper>

Consume the current wrapper and return the wrapped child.

Note that this may disrupt whatever the current wrapper was doing. However, wrappers must ensure that the wrapped 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 ChildWrapper>>

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 wrapped child.

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

Obtain the Child’s stdout.

By default this is a passthrough to the wrapped child.

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

Obtain the Child’s stderr.

By default this is a passthrough to the wrapped 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.

Implementations

impl dyn ChildWrapper

pub fn inner_child(&self) -> &Child

Obtain a reference to the underlying Child.

pub unsafe fn inner_child_mut(&mut self) -> &mut Child

Obtain a mutable reference to the underlying Child.

Modifying the raw child may be unsound depending on the layering of wrappers.

pub unsafe fn into_inner_child(self: Box<Self>) -> Child

Obtain the underlying Child.

Unwrapping everything may be unsound depending on the state of the wrappers.

Implementations on Foreign Types

impl ChildWrapper for Child

fn inner(&self) -> &dyn ChildWrapper

fn inner_mut(&mut self) -> &mut dyn ChildWrapper

fn into_inner(self: Box<Self>) -> Box<dyn ChildWrapper>

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 start_kill(&mut self) -> Result<()>

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

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

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

Available on Unix only.

Implementors

impl ChildWrapper for ProcessGroupChild

Available on Unix and crate feature process-group only.