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

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");

let do_cleanup = child.map(|_| ()) // Ignore result
                      .map_err(|_| ()); // Ignore errors

tokio::spawn(do_cleanup);

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 Item = ExitStatus

The type of value that this future will resolved with if it is successful.

type Error = Error

The type of error that this future will resolve with if it fails in a normal fashion.

fn poll(&mut self) -> Poll<ExitStatus, Error>

Query this future to see if its value has become available, registering interest if it is not.

fn wait(self) -> Result<Self::Item, Self::Error>

Block the current thread until this future is resolved.

fn map<F, U>(self, f: F) -> Map<Self, F> where
    F: FnOnce(Self::Item) -> U, 

Map this future's result to a different type, returning a new future of the resulting type.

fn map_err<F, E>(self, f: F) -> MapErr<Self, F> where
    F: FnOnce(Self::Error) -> E, 

Map this future's error to a different error, returning a new future.

fn from_err<E>(self) -> FromErr<Self, E> where
    E: From<Self::Error>, 

Map this future's error to any error implementing From for this future's Error, returning a new future.

fn then<F, B>(self, f: F) -> Then<Self, B, F> where
    B: IntoFuture,
    F: FnOnce(Result<Self::Item, Self::Error>) -> B, 

Chain on a computation for when a future finished, passing the result of the future to the provided closure f.

fn and_then<F, B>(self, f: F) -> AndThen<Self, B, F> where
    B: IntoFuture<Error = Self::Error>,
    F: FnOnce(Self::Item) -> B, 

Execute another future after this one has resolved successfully.

fn or_else<F, B>(self, f: F) -> OrElse<Self, B, F> where
    B: IntoFuture<Item = Self::Item>,
    F: FnOnce(Self::Error) -> B, 

Execute another future if this one resolves with an error.

fn select<B>(self, other: B) -> Select<Self, <B as IntoFuture>::Future> where
    B: IntoFuture<Item = Self::Item, Error = Self::Error>, 

Waits for either one of two futures to complete.

fn select2<B>(self, other: B) -> Select2<Self, <B as IntoFuture>::Future> where
    B: IntoFuture, 

Waits for either one of two differently-typed futures to complete.

fn join<B>(self, other: B) -> Join<Self, <B as IntoFuture>::Future> where
    B: IntoFuture<Error = Self::Error>, 

Joins the result of two futures, waiting for them both to complete.

fn join3<B, C>(
    self,
    b: B,
    c: C
) -> Join3<Self, <B as IntoFuture>::Future, <C as IntoFuture>::Future> where
    B: IntoFuture<Error = Self::Error>,
    C: IntoFuture<Error = Self::Error>, 

Same as join, but with more futures.

fn join4<B, C, D>(
    self,
    b: B,
    c: C,
    d: D
) -> Join4<Self, <B as IntoFuture>::Future, <C as IntoFuture>::Future, <D as IntoFuture>::Future> where
    B: IntoFuture<Error = Self::Error>,
    C: IntoFuture<Error = Self::Error>,
    D: IntoFuture<Error = Self::Error>, 

Same as join, but with more futures.

fn join5<B, C, D, E>(
    self,
    b: B,
    c: C,
    d: D,
    e: E
) -> Join5<Self, <B as IntoFuture>::Future, <C as IntoFuture>::Future, <D as IntoFuture>::Future, <E as IntoFuture>::Future> where
    B: IntoFuture<Error = Self::Error>,
    C: IntoFuture<Error = Self::Error>,
    D: IntoFuture<Error = Self::Error>,
    E: IntoFuture<Error = Self::Error>, 

Same as join, but with more futures.

fn into_stream(self) -> IntoStream<Self>

Convert this future into a single element stream.

fn flatten(self) -> Flatten<Self> where
    Self::Item: IntoFuture,
    <Self::Item as IntoFuture>::Error: From<Self::Error>, 

Flatten the execution of this future when the successful result of this future is itself another future.

fn flatten_stream(self) -> FlattenStream<Self> where
    Self::Item: Stream,
    <Self::Item as Stream>::Error == Self::Error, 

Flatten the execution of this future when the successful result of this future is a stream.

fn fuse(self) -> Fuse<Self>

Fuse a future such that poll will never again be called once it has completed.

fn inspect<F>(self, f: F) -> Inspect<Self, F> where
    F: FnOnce(&Self::Item), 

Do something with the item of a future, passing it on.

fn catch_unwind(self) -> CatchUnwind<Self> where
    Self: UnwindSafe, 

Catches unwinding panics while polling the future.

fn shared(self) -> Shared<Self>

Create a cloneable handle to this future where all handles will resolve to the same result.