Struct subprocess::Communicator

pub struct Communicator { /* fields omitted */ }

Deadlock-free communication with the subprocess.

Normally care must be taken to avoid deadlock when communicating to a subprocess that both expects input and provides output. This implementation avoids deadlock by reading from and writing to the subprocess in parallel. On Unix-like systems this is achieved using poll(), and on Windows using threads.

Methods

impl Communicator

pub fn read(
    &mut self
) -> Result<(Option<Vec<u8>>, Option<Vec<u8>>), CommunicateError>

Return the subprocess's output and error contents.

This will write the input data to the subprocess and read its output and error in parallel, taking care to avoid deadlocks. The output and error are returned as pairs of Option<Vec>, which can be None if the corresponding stream has not been specified as Redirection::Pipe.

By default read() will read all requested data.

If limit_time has been called, the method will read for no more than the specified duration. In case of timeout, an error of kind io::ErrorKind::TimedOut is returned. Communication may be resumed after the timeout by calling read() again.

If limit_size has been called, the method will return no more than the specified amount of bytes in the two vectors combined. (It might internally read a bit more from the subprocess, but the data will remain available for reading.) Subsequent data can be retrieved by calling read() again. The primary use case for this method is preventing a rogue subprocess from breaking the caller by spending all its memory.

Panics

If input_data is provided and stdin was not redirected to a pipe. Also, if input_data is not provided and stdin was redirected to a pipe.

Errors

• Err(CommunicateError) if a system call fails. In case of timeout, the underlying error kind will be ErrorKind::TimedOut.

Regardless of the nature of the error, the content prior to the error can be retrieved using the capture attribute of the error.

pub fn read_string(
    &mut self
) -> Result<(Option<String>, Option<String>), CommunicateError>

Return the subprocess's output and error contents as strings.

Like read(), but returns strings instead of byte vectors. Invalid UTF-8 sequences, if found, are replaced with the the U+FFFD Unicode replacement character.

pub fn limit_size(self, size: usize) -> Communicator

Limit the amount of data the next read() will read from the subprocess.

pub fn limit_time(self, time: Duration) -> Communicator

Limit the amount of time the next read() will spend reading from the subprocess.

Trait Implementations

impl Debug for Communicator

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

Formats the value using the given formatter.