Struct subprocess::Communicator
source · [−]pub struct Communicator { /* private fields */ }
Expand description
Unattended data exchange with the subprocess.
When a subprocess both expects input and provides output, care must be
taken to avoid deadlock. The issue arises when the subprocess responds to
part of the input data by providing some output which must be read for the
subprocess to accept further input. If the parent process is blocked on
writing the input, it cannot read the output and a deadlock occurs. This
implementation avoids this issue by by reading from and writing to the
subprocess in parallel. On Unix-like systems this is achieved using
poll()
, and on Windows using threads.
Implementations
sourceimpl Communicator
impl Communicator
sourcepub fn read(
&mut self
) -> Result<(Option<Vec<u8>>, Option<Vec<u8>>), CommunicateError>
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 data until end-of-file.
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 beErrorKind::TimedOut
.
Regardless of the nature of the error, the content prior to the error
can be retrieved using the capture
attribute of the error.
sourcepub fn read_string(
&mut self
) -> Result<(Option<String>, Option<String>), CommunicateError>
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.
sourcepub fn limit_size(self, size: usize) -> Communicator
pub fn limit_size(self, size: usize) -> Communicator
Limit the amount of data the next read()
will read from the
subprocess.
sourcepub fn limit_time(self, time: Duration) -> Communicator
pub fn limit_time(self, time: Duration) -> Communicator
Limit the amount of time the next read()
will spend reading from the
subprocess.
Trait Implementations
Auto Trait Implementations
impl RefUnwindSafe for Communicator
impl Send for Communicator
impl Sync for Communicator
impl Unpin for Communicator
impl UnwindSafe for Communicator
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more