Crate tokio_process

An implementation of asynchronous process management for Tokio.

This crate provides a CommandExt trait to enhance the functionality of the Command type in the standard library. The three methods provided by this trait mirror the "spawning" methods in the standard library. The CommandExt trait in this crate, though, returns "future aware" types that interoperate with Tokio. The asynchronous process support is provided through signal handling on Unix and system APIs on Windows.

Examples

Here's an example program which will spawn echo hello world and then wait for it using an event loop.

extern crate futures;
extern crate tokio_core;
extern crate tokio_process;

use std::process::Command;

use futures::Future;
use tokio_core::reactor::Core;
use tokio_process::CommandExt;

fn main() {
    // Create our own local event loop
    let mut core = Core::new().unwrap();

    // Use the standard library's `Command` type to build a process and
    // then execute it via the `CommandExt` trait.
    let child = Command::new("echo").arg("hello").arg("world")
                        .spawn_async(&core.handle());

    // Make sure our child succeeded in spawning
    let child = child.expect("failed to spawn");

    match core.run(child) {
        Ok(status) => println!("exit status: {}", status),
        Err(e) => panic!("failed to wait for exit: {}", e),
    }
}

Next, let's take a look at an example where we not only spawn echo hello world but we also capture its output.

extern crate futures;
extern crate tokio_core;
extern crate tokio_process;

use std::process::Command;

use futures::Future;
use tokio_core::reactor::Core;
use tokio_process::CommandExt;

fn main() {
    let mut core = Core::new().unwrap();

    // Like above, but use `output_async` which returns a future instead of
    // immediately returning the `Child`.
    let output = Command::new("echo").arg("hello").arg("world")
                        .output_async(&core.handle());
    let output = core.run(output).expect("failed to collect output");

    assert!(output.status.success());
    assert_eq!(output.stdout, b"hello world\n");
}

We can also read input line by line.

extern crate futures;
extern crate tokio_core;
extern crate tokio_process;
extern crate tokio_io;

use std::io;
use std::process::{Command, Stdio, ExitStatus};

use futures::{BoxFuture, Future, Stream};
use tokio_core::reactor::Core;
use tokio_process::{CommandExt, Child};

fn print_lines(mut cat: Child) -> BoxFuture<ExitStatus, io::Error> {
    let stdout = cat.stdout().take().unwrap();
    let reader = io::BufReader::new(stdout);
    let lines = tokio_io::io::lines(reader);
    let cycle = lines.for_each(|l| {
        println!("Line: {}", l);
        Ok(())
    });
    cycle.join(cat).map(|((), s)| s).boxed()
}

fn main() {
    let mut core = Core::new().unwrap();
    let mut cmd = Command::new("cat");
    let mut cat = cmd.stdout(Stdio::piped());
    let child = cat.spawn_async(&core.handle()).unwrap();
    core.run(print_lines(child)).unwrap();
}

Caveats

While similar to the standard library, this crate's Child type differs importantly in the behavior of drop. In the standard library, a child process will continue running after the instance of std::process::Child is dropped. In this crate, however, because tokio_process::Child is a future of the child's ExitStatus, a child process is terminated if tokio_process::Child is dropped. The behavior of the standard library can be regained with the Child::forget method.

Structs

Child	Representation of a child process spawned onto an event loop.
ChildStderr	The standard error stream for spawned children.
ChildStdin	The standard input stream for spawned children.
ChildStdout	The standard output stream for spawned children.
OutputAsync	Future returned by the CommandExt::output_async method.
StatusAsync	[ Deprecated ] Future returned by the CommandExt::status_async method.
StatusAsync2	Future returned by the CommandExt::status_async2 method.
WaitWithOutput	Future returned from the Child::wait_with_output method.

Traits

CommandExt

Extensions provided by this crate to the Command type in the standard library.