Struct tokio_process::Child

#[must_use = "futures do nothing unless polled"]
pub struct Child { /* 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.

Note: The behavior of drop on a child in this crate is different than the behavior of the standard library. If a tokio_process::Child is dropped before the process finishes then the process will be terminated. In the standard library, however, the process continues executing. This is done because futures in general take drop as a sign of cancellation, and this Child is itself a future. If you'd like to run a process in the background, though, you may use the forget method.

Methods

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.

pub fn stdin(&mut self) -> &mut Option<ChildStdin>

Returns a handle for writing to the child's stdin, if it has been captured

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

Returns a handle for writing to the child's stdout, if it has been captured

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

Returns a handle for writing to the child's stderr, if it has been captured

Important traits for WaitWithOutput

impl Future for WaitWithOutput type Output = Result<Output>;

pub fn wait_with_output(self) -> WaitWithOutput

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.

pub fn forget(self)

Drop this Child without killing the underlying process.

Normally a Child is killed if it's still alive when dropped, but this method will ensure that the child may continue running once the Child instance is dropped.

Note: this method may leak OS resources depending on your platform. To ensure resources are eventually cleaned up, consider sending the Child instance into an event loop as an alternative to this method.

let child = Command::new("echo").arg("hello").arg("world")
                    .spawn_async()
                    .expect("failed to spawn");

tokio::spawn(async {
  let _ = child.await;
});

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.