pub struct ReaderHandle { /* private fields */ }
Expand description
An incremental reader created with the
Expression::reader
method.
When this reader reaches EOF, it automatically calls
wait
on the inner handle. If the child
returns a non-zero exit status, the read at EOF will return an error,
unless you use unchecked
.
Both ReaderHandle
and &ReaderHandle
implement
std::io::Read
. The
latter makes it possible for one thread to
kill
the ReaderHandle
while
another thread is reading it. That can be useful for effectively canceling
the read and unblocking the reader thread. However, note that killed child
processes return a non-zero exit status, which is an error for the reader
by default, unless you use
unchecked
.
ReaderHandle
contains a Handle
internally, and it takes the same
approach to cleaning up zombie processess on Unix.
§Example
use duct::cmd;
use duct::ReaderHandle;
use std::sync::Arc;
use std::io::prelude::*;
// This child process prints a single byte and then sleeps.
//
// CAUTION: Using Bash for this example would probably hang, because Bash
// would spawn a `sleep` grandchild processes, and that grandchild wouldn't
// receive the kill signal.
let python_child = "\
import sys
import time
print()
sys.stdout.flush()
time.sleep(24 * 60 * 60)
";
let reader: ReaderHandle = cmd!("python3", "-c", python_child)
.unchecked()
.reader()?;
// Spawn two threads that both try to read the single byte. Whichever one
// succeeds then calls kill() to unblock the other.
let arc_reader: Arc<ReaderHandle> = Arc::new(reader);
let mut threads = Vec::new();
for _ in 0..2 {
let arc_reader = arc_reader.clone();
threads.push(std::thread::spawn(move || -> std::io::Result<()> {
let mut single_byte = [0u8];
(&*arc_reader).read(&mut single_byte)?;
arc_reader.kill()?;
Ok(())
}));
}
// Join both threads. Because of the kill() above, both threads will exit
// quickly.
for thread in threads {
thread.join().unwrap()?;
}
Implementations§
Source§impl ReaderHandle
impl ReaderHandle
Sourcepub fn try_wait(&self) -> Result<Option<&Output>>
pub fn try_wait(&self) -> Result<Option<&Output>>
Check whether the underlying expression is finished. This is equivalent
to Handle::try_wait
. If the
ReaderHandle
has indicated EOF successfully, then it’s guaranteed
that this method will return Ok(Some(_))
.
Note that the
stdout
field of the returned
Output
will always be empty, because the ReaderHandle
itself owns the
child’s stdout pipe.
Sourcepub fn kill(&self) -> Result<()>
pub fn kill(&self) -> Result<()>
Kill all the child processes in the running expression.
See Handle::kill
. Note that as with
std::process::Child::kill
,
this does not kill any grandchild processes that the children have
spawned on their own. It only kills the child processes that Duct
spawned itself. This is especially relevant for ReaderHandle
,
because if you’re using kill
to unblock another thread that’s
reading, an unkilled grandchild process might keep the child’s stdout
pipe open and keep your reader thread blocked. For that use case, you
need to ensure that any grandchild processes your child might spawn are
going to be short-lived. See
gotchas.md
for an extensive discussion of these issues.
Trait Implementations§
Source§impl Debug for ReaderHandle
impl Debug for ReaderHandle
Source§impl<'a> Read for &'a ReaderHandle
impl<'a> Read for &'a ReaderHandle
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>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> 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 moreSource§impl Read for ReaderHandle
impl Read for ReaderHandle
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>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> 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