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) -> 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. 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::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)
    }
}

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 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) -> 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.