Trait ChildWrapper 

pub trait ChildWrapper:
    Any
    + Debug
    + Send
    + Sync {
    // 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) -> Option<u32> { ... }
    fn kill(&mut self) -> Box<dyn Future<Output = Result<()>> + Send + '_> { ... }
    fn start_kill(&mut self) -> Result<()> { ... }
    fn try_wait(&mut self) -> Result<Option<ExitStatus>> { ... }
    fn wait(
        &mut self,
    ) -> Pin<Box<dyn Future<Output = Result<ExitStatus>> + Send + '_>> { ... }
    fn wait_with_output(
        self: Box<Self>,
    ) -> Box<dyn Future<Output = Result<Output>> + Send>
       where Self: 'static { ... }
    fn signal(&self, sig: i32) -> Result<()> { ... }
}

Available on crate feature tokio1 only.

Wrapper for tokio::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. Together they expose each lower layer, allowing wrappers to be unwrapped and the native Child to be used directly when necessary.

Each non-terminal wrapper must use them to expose its direct lower layer. A terminal non-native child returns itself from all three methods. Wrapper chains must otherwise be acyclic and terminate in either a native Child or a self-returning non-native child.

The try_inner_child, try_inner_child_mut, and try_into_inner_child convenience methods on the trait object traverse these layers when access to a native Child is required.

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::tokio::*;
use tokio::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)
    }

    #[cfg(windows)]
    fn process_handle(
        &self,
    ) -> Option<std::os::windows::io::BorrowedHandle<'_>> {
        self.0.process_handle()
    }
}

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 Tokio’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) -> Option<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.

Returns an Option to resemble Tokio’s API, but isn’t expected to be None in practice.

fn kill(&mut self) -> Box<dyn Future<Output = Result<()>> + Send + '_>

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 a passthrough to the underlying Child, which:

• on Unix, sends a SIGKILL signal to the process;
• otherwise, passes through to the kill() method.

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

Check if the Child has exited without waiting, and if it has, 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, ) -> Pin<Box<dyn Future<Output = Result<ExitStatus>> + Send + '_>>

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>, ) -> Box<dyn Future<Output = Result<Output>> + Send>

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.

By default this is a reimplementation of the Tokio 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 Tokio’s Child, nor on std’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 try_inner_child(&self) -> Option<&Child>

Try to obtain a reference to the underlying native Child.

Returns None if the wrapper chain terminates in a non-native child.

pub unsafe fn try_inner_child_mut(&mut self) -> Option<&mut Child>

Try to obtain a mutable reference to the underlying native Child.

Returns None if the wrapper chain terminates in a non-native child.

Safety

The caller must ensure that using the returned mutable child does not violate invariants maintained by any wrapper in the chain.

pub unsafe fn try_into_inner_child(self: Box<Self>) -> Result<Child, Box<Self>>

Try to consume the wrapper chain and obtain the underlying native Child.

If the chain terminates in a non-native child, returns that terminal child without calling its into_inner method. Wrappers already traversed before reaching it have been consumed.

Safety

The caller must ensure that removing every traversed wrapper does not violate wrapper invariants or bypass required cleanup. This also applies when the method returns Err, because wrappers above the returned terminal child have already been consumed.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

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) -> Option<u32>

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

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

fn wait( &mut self, ) -> Pin<Box<dyn Future<Output = Result<ExitStatus>> + Send + '_>>

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

Available on Unix only.

Implementors

impl ChildWrapper for ProcessGroupChild

Available on Unix and crate feature process-group only.