pub struct Handle { /* private fields */ }Expand description
A handle to a running expression, returned by the
start method.
Calling start followed by
into_output on the handle is
equivalent to run. Note that unlike
std::process::Child,
most of the methods on Handle take &self rather than &mut self, and a
Handle may be shared between multiple threads.
If you drop a Handle without first waiting on the child to exit, it will
try_wait internally to see if it can reap the child. If the child is
still running, its handle will be added to a global list and polled whenever new child
processes are spawned. This avoids leaking zombie
processes on Unix platforms. This Drop
implementation is omitted on Windows, where zombies aren’t a problem.
See the shared_child
crate for implementation details behind making handles thread safe.
Implementations§
Source§impl Handle
impl Handle
Sourcepub fn wait(&self) -> Result<&Output>
pub fn wait(&self) -> Result<&Output>
Wait for the running expression to finish, and return a reference to its
std::process::Output.
Multiple threads may wait at the same time.
§Errors
In addition to all the IO errors possible with
std::process::Child,
wait will return an
ErrorKind::Other
IO error if child returns a non-zero exit status. To suppress this
error and return an Output even when the exit status is non-zero, use
the unchecked method.
Sourcepub fn try_wait(&self) -> Result<Option<&Output>>
pub fn try_wait(&self) -> Result<Option<&Output>>
Check whether the running expression is finished. If it is, return a
reference to its
std::process::Output.
If it’s still running, return Ok(None).
§Errors
In addition to all the IO errors possible with
std::process::Child,
try_wait will return an
ErrorKind::Other
IO error if child returns a non-zero exit status. To suppress this
error and return an Output even when the exit status is non-zero, use
the unchecked method.
Sourcepub fn into_output(self) -> Result<Output>
pub fn into_output(self) -> Result<Output>
Wait for the running expression to finish, and then return a
std::process::Output
object containing the results, including any captured output. This
consumes the Handle. Calling
start followed by
into_output is equivalent to
run.
§Errors
In addition to all the IO errors possible with
std::process::Child,
into_output will return an
ErrorKind::Other
IO error if child returns a non-zero exit status. To suppress this
error and return an Output even when the exit status is non-zero, use
the unchecked method.
Sourcepub fn kill(&self) -> Result<()>
pub fn kill(&self) -> Result<()>
Kill all the child processes in the running expression.
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. See
gotchas.md
for an extensive discussion of this behavior.
This method does not wait on the child processes to exit. Calling wait
after kill almost always returns quickly, but there are edge cases where it might not.
One case is if a child process is blocked reading an unresponsive FUSE filesystem. Another
is if a child process is paused by a debugger.