Struct pwner::tokio::Duplex

pub struct Duplex(_, _);

An implementation of Process that uses tokio::process as the launcher.

All read and write operations are async.

Note: On *nix platforms, the owned process will have 2 seconds between signals, which is run in a spawned task.

Panics

When, on *nix platforms, a process gets dropped without a runtime.

Implementations

impl Duplex

pub fn id(&self) -> Option<u32>

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

Examples

Basic usage:

use tokio::process::Command;
use pwner::Spawner;

let mut command = Command::new("ls");
if let Ok(child) = command.spawn_owned() {
    match child.id() {
      Some(pid) => println!("Child's ID is {}", pid),
      None => println!("Child has already exited"),
    }
} else {
    println!("ls command didn't start");
}

pub fn read_from(&mut self, read_source: ReadSource) -> &mut Self

Choose which pipe to read form next.

Examples

Basic usage:

use tokio::io::AsyncReadExt;
use tokio::process::Command;
use pwner::Spawner;
use pwner::tokio::ReadSource;

let mut child = Command::new("ls").spawn_owned().unwrap();
let mut buffer = [0_u8; 1024];

child.read_from(ReadSource::Both).read(&mut buffer).await.unwrap();

pub async fn wait(self) -> Result<(ExitStatus, ChildStdout, ChildStderr), Error>

Waits for the child to exit completely, returning the status with which it exited, stdout, and stderr.

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.

Examples

Basic usage:

use pwner::Spawner;
use tokio::io::{AsyncReadExt, BufReader};
use tokio::process::Command;

let child = Command::new("ls").spawn_owned().unwrap();
let (status, stdout, stderr) = child.wait().await.unwrap();

let mut buffer = String::new();
if status.success() {
    let mut reader = BufReader::new(stdout);
    reader.read_to_string(&mut buffer).await.unwrap();
} else {
    let mut reader = BufReader::new(stderr);
    reader.read_to_string(&mut buffer).await.unwrap();
}

Errors

Relays the error from tokio::process::Child::wait()

pub fn pipes(&mut self) -> (&mut ChildStdin, &mut ChildStdout, &mut ChildStderr)

Decomposes the handle into mutable references to the pipes.

Examples

Basic usage:

use tokio::io::{ AsyncReadExt, AsyncWriteExt };
use tokio::process::Command;
use pwner::Spawner;

let mut child = Command::new("cat").spawn_owned().unwrap();
let mut buffer = [0_u8; 1024];
let (stdin, stdout, _) = child.pipes();

stdin.write_all(b"hello\n").await.unwrap();
stdout.read(&mut buffer).await.unwrap();

pub fn decompose(self) -> (Simplex, Output)

Separates the process and its input from the output pipes. Ownership is retained by a Simplex which still implements a graceful drop of the child process.

Examples

Basic usage:

use tokio::io::{ AsyncReadExt, AsyncWriteExt };
use tokio::process::Command;
use pwner::Spawner;

let child = Command::new("cat").spawn_owned().unwrap();
let (mut input_only_process, mut output) = child.decompose();

// Spawn printing task
tokio::spawn(async move {
    let mut buffer = [0; 1024];
    while let Ok(bytes) = output.read(&mut buffer).await {
        if let Ok(string) = std::str::from_utf8(&buffer[..bytes]) {
            print!("{}", string);
        }
    }
});

// Interact normally with the child process
input_only_process.write_all(b"hello\n").await.unwrap();

pub fn eject(self) -> (Child, ChildStdin, ChildStdout, ChildStderr)

Completely releases the ownership of the child process. The raw underlying process and pipes are returned and no wrapping function is applicable any longer.

Note: By ejecting the process, graceful drop will no longer be available.

Examples

Basic usage:

use tokio::io::{ AsyncReadExt, AsyncWriteExt };
use tokio::process::Command;
use pwner::Spawner;

let mut child = Command::new("cat").spawn_owned().unwrap();
let mut buffer = [0_u8; 1024];
let (process, mut stdin, mut stdout, _) = child.eject();

stdin.write_all(b"hello\n").await.unwrap();
stdout.read(&mut buffer).await.unwrap();

// Graceful drop will not be executed for `child` as the ejected variable leaves scope here

pub async fn shutdown(self) -> Result<ExitStatus>

Consumes the process to allow awaiting for shutdown.

This method is essentially the same as a drop, however it return a Future which allows the parent to await the shutdown.

Examples

Basic usage:

use tokio::process::Command;
use pwner::Spawner;

let child = Command::new("top").spawn_owned().unwrap();
child.shutdown().await.unwrap();

Errors

• std::io::Error if failure when killing the process.

Trait Implementations

impl AsyncRead for Duplex

fn poll_read(
    self: Pin<&mut Self>,
    ctx: &mut Context<'_>,
    buf: &mut ReadBuf<'_>
) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.

impl AsyncWrite for Duplex

fn poll_write(
    self: Pin<&mut Self>,
    ctx: &mut Context<'_>,
    buf: &[u8]
) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, ctx: &mut Context<'_>) -> Poll<Result<()>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown(self: Pin<&mut Self>, ctx: &mut Context<'_>) -> Poll<Result<()>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_vectored(
    self: Pin<&mut Self>,
    cx: &mut Context<'_>,
    bufs: &[IoSlice<'_>]
) -> Poll<Result<usize, Error>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl Process for Duplex