Struct duct::Handle

source ·
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.

Like std::process::Child, Handle doesn’t do anything special in its destructor. If you drop a handle without waiting on it, child processes and background IO threads will keep running, and the children will become zombie processes when they exit. That’s a resource leak, similar to leaking memory or file handles. Note that in contrast to Handle, a ReaderHandle kills child processes in its destructor, to avoid creating zombies.

See the shared_child crate for implementation details behind making handles thread safe.

Implementations§

source§

impl Handle

source

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.

source

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.

source

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.

source

pub fn kill(&self) -> Result<()>

Kill the running expression and await all the child processes. Any errors that would normally result from a non-zero exit status are ignored, as with unchecked.

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.

source

pub fn pids(&self) -> Vec<u32>

Return a Vec<u32> containing the PIDs of all of the child processes. The PIDs are given in pipeline order, from left to right.

Trait Implementations§

source§

impl Debug for Handle

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl HandleExt for Handle

source§

fn send_signal(&self, signal: c_int) -> Result<()>

Send a signal to all child processes running under this expression.

Auto Trait Implementations§

§

impl !RefUnwindSafe for Handle

§

impl Send for Handle

§

impl Sync for Handle

§

impl Unpin for Handle

§

impl !UnwindSafe for Handle

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.