Struct Child 

pub struct Child<M = Local>
where
    M: Mode,
{
    pub stdin: Option<ChildStdin<M>>,
    pub stdout: Option<ChildStdout<M>>,
    pub stderr: Option<ChildStderr<M>>,
    /* private fields */
}

A spawned child process, with the pipes to it that its command asked for.

Command::spawn creates it on a runtime. A Child<Local> (Local is the default) stays on the thread that created it, and a Child<Shared> can be sent to and used from any thread. See the module documentation for what drives it.

The pipes are public fields. Each is Some if the command asked for it with Stdio::piped(), and None otherwise. To move a pipe elsewhere, take it out, as in child.stdout.take() or let Child { stdout, .. } = child;. Child has no Drop implementation, so this works for every field.

Dropping a Child leaves the process running unless the command said otherwise: see the module documentation.

Example

Reads the output of a child as it is written, then waits for its exit status:

use futures::AsyncReadExt;
use zruntime::{
    LocalRuntime,
    process::{Command, Stdio},
};

let runtime = LocalRuntime::new()?;

runtime.block_on(async {
    let mut child = Command::new("echo")
        .arg("hello")
        .stdout(Stdio::piped())
        .spawn(&runtime)?;

    let mut greeting = String::new();
    let mut stdout = child.stdout.take().expect("stdout is piped");
    stdout.read_to_string(&mut greeting).await?;

    assert_eq!(greeting, "hello\n");
    assert!(child.status().await?.success());
})?;

Fields

stdin: Option<ChildStdin<M>>

The pipe to the standard input of the process, if its command asked for one.

Dropping it closes the pipe, and a child that reads its input to the end sees the end then. status and output drop it themselves.

stdout: Option<ChildStdout<M>>

The pipe from the standard output of the process, if its command asked for one.

stderr: Option<ChildStderr<M>>

The pipe from the standard error of the process, if its command asked for one.

Implementations

impl<M> Child<M>

where M: Mode,

pub fn id(&self) -> u32

The process ID of the child.

The ID refers to this process until it has exited and its status has been collected, by status or try_status. After that, the system may give it to another process.

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

Forces the process to exit, without waiting for it to do so.

This sends SIGKILL on unix and calls TerminateProcess on Windows. To wait until the process is gone, call status afterwards. As with std’s kill, killing a process whose status has already been collected is not an error.

Errors

Fails if the OS cannot kill the process.

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

Checks whether the process has exited, without waiting.

Returns the exit status if it has, and None if it is still running. Unlike status, this leaves the pipe to the standard input open. When the process has exited, this collects its status, and every later call returns the same status.

Errors

Fails if the OS cannot report the status of the process.

pub async fn status(&mut self) -> Result<ExitStatus>

Waits for the process to exit and resolves to its exit status.

The pipe to the standard input is dropped first, as std’s wait does. Otherwise a process that reads its input to the end would wait for the pipe to close, while this waits for the process to exit. The pipes from the process stay open. A process that fills a pipe that nothing reads blocks, so read them while waiting, or use output, which does.

If the process has already exited, or its status was collected earlier, this resolves at once, with the same status each time. See the module documentation for how the wait works.

Errors

Fails if the OS cannot report the status of the process, or the runtime cannot wait for it.

Cancel safety

Dropping the future loses nothing. The next call takes up the wait, and finds a process that exited in the meantime as it is.

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

Reads everything the process writes to its standard output and error, then waits for it to exit.

The pipe to the standard input is dropped first, so that a process that reads its input to the end does not wait for this to close it. Then the pipes from the process, those it has, are read to their ends, both at the same time. Reading them one after the other could deadlock: a process that fills one pipe while this reads the other would never write the rest. A stream that is not piped is not captured, and the output holds nothing of it. Finally this waits for the process, as status does.

Only the pipes of this child are read. To run a command for its output, use Command::output, which pipes the right ones.

Errors

Fails if reading a pipe fails, or if waiting for the process fails. If reading fails, this does not wait for the process, and the child is dropped.

Cancel safety

Not cancel safe. This takes the child by value, so dropping the future drops the child and discards what was read. See Dropping a child for what that does to the process.

Trait Implementations

impl<M> Debug for Child<M>

where M: Mode,

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

Formats the value using the given formatter.