Struct grep_cli::CommandReader
source · pub struct CommandReader { /* private fields */ }
Expand description
A streaming reader for a command’s output.
The purpose of this reader is to provide an easy way to execute processes whose stdout is read in a streaming way while also making the processes’ stderr available when the process fails with an exit code. This makes it possible to execute processes while surfacing the underlying failure mode in the case of an error.
Moreover, by default, this reader will asynchronously read the processes’ stderr. This prevents subtle deadlocking bugs for noisy processes that write a lot to stderr. Currently, the entire contents of stderr is read on to the heap.
Example
This example shows how to invoke gzip
to decompress the contents of a
file. If the gzip
command reports a failing exit status, then its stderr
is returned as an error.
use std::{io::Read, process::Command};
use grep_cli::CommandReader;
let mut cmd = Command::new("gzip");
cmd.arg("-d").arg("-c").arg("/usr/share/man/man1/ls.1.gz");
let mut rdr = CommandReader::new(&mut cmd)?;
let mut contents = vec![];
rdr.read_to_end(&mut contents)?;
Implementations§
source§impl CommandReader
impl CommandReader
sourcepub fn new(cmd: &mut Command) -> Result<CommandReader, CommandError>
pub fn new(cmd: &mut Command) -> Result<CommandReader, CommandError>
Create a new streaming reader for the given command using the default configuration.
The caller should set everything that’s required on the given command before building a reader, such as its arguments, environment and current working directory. Settings such as the stdout and stderr (but not stdin) pipes will be overridden so that they can be controlled by the reader.
If there was a problem spawning the given command, then its error is returned.
If the caller requires additional configuration for the reader
returned, then use CommandReaderBuilder
.
sourcepub fn close(&mut self) -> Result<()>
pub fn close(&mut self) -> Result<()>
Closes the CommandReader, freeing any resources used by its underlying child process. If the child process exits with a nonzero exit code, the returned Err value will include its stderr.
close
is idempotent, meaning it can be safely called multiple times.
The first call closes the CommandReader and any subsequent calls do
nothing.
This method should be called after partially reading a file to prevent
resource leakage. However there is no need to call close
explicitly
if your code always calls read
to EOF, as read
takes care of
calling close
in this case.
close
is also called in drop
as a last line of defense against
resource leakage. Any error from the child process is then printed as a
warning to stderr. This can be avoided by explicitly calling close
before the CommandReader is dropped.
Trait Implementations§
source§impl Debug for CommandReader
impl Debug for CommandReader
source§impl Drop for CommandReader
impl Drop for CommandReader
source§impl Read for CommandReader
impl Read for CommandReader
source§fn read(&mut self, buf: &mut [u8]) -> Result<usize>
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
1.36.0 · source§fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
read
, except that it reads into a slice of buffers. Read moresource§fn is_read_vectored(&self) -> bool
fn is_read_vectored(&self) -> bool
can_vector
)1.0.0 · source§fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
buf
. Read more1.0.0 · source§fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
buf
. Read more1.6.0 · source§fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
buf
. Read moresource§fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)source§fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)cursor
. Read more1.0.0 · source§fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
fn by_ref(&mut self) -> &mut Selfwhere Self: Sized,
Read
. Read more