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>

Communicate with the subprocess, return the contents of its standard output and error.

This will write input data to the subprocess's standard input and simultaneously read its standard output and error. The output and error contents are returned as a pair of Option<Vec>. The None options correspond to streams not specified as Redirection::Pipe when creating the subprocess.

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, it will limit the allocation done by this method. If the subprocess provides more data than the limit specifies, read() will successfully return as much data as specified by the limit. (It might internally read a bit more from the subprocess, but the data will remain available for future reads.) Subsequent data can be retrieved by calling read() again, which can be repeated until read() returns all-empty data, which marks EOF.

Note that this method does not wait for the subprocess to finish, only to close its output/error streams. It is rare but possible for the program to continue running after having closed the streams, in which case Popen::Drop will wait for it to finish. If such a wait is undesirable, it can be prevented by waiting explicitly using wait(), by detaching the process using detach(), or by terminating it with terminate().

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.