Struct tokio::process::Child

#[must_use = "futures do nothing unless polled"]pub struct Child {
    pub stdin: Option<ChildStdin>,
    pub stdout: Option<ChildStdout>,
    pub stderr: Option<ChildStderr>,
    // some fields omitted
}

Representation of a child process spawned onto an event loop.

This type is also a future which will yield the ExitStatus of the underlying child process. A Child here also provides access to information like the OS-assigned identifier and the stdio streams.

Caveats

Similar to the behavior to the standard library, and unlike the futures paradigm of dropping-implies-cancellation, a spawned process will, by default, continue to execute even after the Child handle has been dropped.

The Command::kill_on_drop method can be used to modify this behavior and kill the child process if the Child wrapper is dropped before it has exited.

Fields

stdin: Option<ChildStdin>

The handle for writing to the child’s standard input (stdin), if it has been captured.

stdout: Option<ChildStdout>

The handle for reading from the child’s standard output (stdout), if it has been captured.

stderr: Option<ChildStderr>

The handle for reading from the child’s standard error (stderr), if it has been captured.

Implementations

impl Child

pub fn id(&self) -> u32

Returns the OS-assigned process identifier associated with this child.

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

Forces the child to exit.

This is equivalent to sending a SIGKILL on unix platforms.

If the child has to be killed remotely, it is possible to do it using a combination of the select! macro and a oneshot channel. In the following example, the child will run until completion unless a message is sent on the oneshot channel. If that happens, the child is killed immediately using the .kill() method.

use tokio::process::Command;
use tokio::sync::oneshot::channel;

#[tokio::main]
async fn main() {
    let (send, recv) = channel::<()>();
    let mut child = Command::new("sleep").arg("1").spawn().unwrap();
    tokio::spawn(async move { send.send(()) });
    tokio::select! {
        _ = &mut child => {}
        _ = recv => {
            &mut child.kill();
            // NB: await the child here to avoid a zombie process on Unix platforms
            child.await.unwrap();
        }
    }
}

pub async fn wait_with_output(self) -> Result<Output>

Returns a future that will resolve to an Output, containing the exit status, stdout, and stderr of the child process.

The returned future will simultaneously waits for the child to exit and collect all remaining output on the stdout/stderr handles, returning an Output instance.

The stdin handle to the child process, if any, will be closed before waiting. This helps avoid deadlock: it ensures that the child does not block waiting for input from the parent, while the parent waits for the child to exit.

By default, stdin, stdout and stderr are inherited from the parent. In order to capture the output into this Output it is necessary to create new pipes between parent and child. Use stdout(Stdio::piped()) or stderr(Stdio::piped()), respectively, when creating a Command.

Trait Implementations

impl Debug for Child

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Future for Child

type Output = Result<ExitStatus>

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempt to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.