Struct Handle 

pub struct Handle { /* private fields */ }

A handle to a child process created via Spawner::spawn() If input/output/error redirection were setup in the Spawner, you can use their related functions to access them.

Additionally, if there are other associated handles (Such as an auxiliary task to the one launched by the handle), you can delegate them as associates and allow the caller to manage their lifetimes. This allows you to only manage a single handle, with all its associates being cleanup when it does.

You should never construct a Handle yourself, it should always be returned through a Spawner.

Implementations

impl Handle

pub fn new( name: String, pid: Pid, mode: Mode, stdin: Option<OwnedFd>, stdout: Option<OwnedFd>, stderr: Option<OwnedFd>, associates: Vec<Handle>, ) -> Self

Construct a new Handle from a Child PID and pipes

pub fn name(&self) -> &str

Get the name of the handle.

pub fn pid(&self) -> &Option<Pid>

Get the pid of the child.

pub fn wait_timeout(self, timeout: Duration) -> Result<i32, Error>

Wait for the child to exit, with a timeout in case of no activity.

Note that this function uses a signal handler to ensure it does not hang the process, as well as efficiently wait the timeout. You cannot use this function in multi-threaded environments.

pub fn wait_and(&mut self) -> Result<i32, Error>

Wait for the child to exit.

Note that this function uses a signal handler to ensure it does not hang the process. You cannot use this function in multi-threaded environments.

pub fn wait(self) -> Result<i32, Error>

Consume the handle and return the exit code of the process.

pub fn wait_blocking(&mut self) -> Result<i32, Error>

Wait for the child without signal handlers.

This function is a thread-safe version of wait, but means that signals will not be caught.

pub fn alive(&mut self) -> Result<Option<Pid>, Error>

Check if the process is still alive, non-blocking.

pub fn terminate(&mut self) -> Result<(), Error>

Terminate the process with a SIGTERM request, but do not consume the Handle.

pub fn signal(&mut self, sig: Signal) -> Result<(), Error>

Send a signal to the child.

pub fn signal_group(&mut self, sig: Signal) -> Result<(), Error>

Send the signal to the child, and all associated handles.

pub fn detach(self) -> Option<Pid>

Detach the thread from manual cleanup. This function does nothing more than move the Pid of the child out of the Handle. When the Handle falls out of scope, it will not have a Pid to terminate, so the child process will linger.

Spawner sets Death Sig to SIGKILL, which means that when the parent dies, its children are sent SIGKILL. This means a detached thread should not become a Zombie Process, even if the Pid is dropped on program exit.

You therefore have three options on what to do with the return value of this function:

1. If there was no child to detach, you’ll get a None, and do nothing.
2. If you want to manage the child yourself (Or associate it with another Handle), capture the value.
3. If you want to truly detach it, don’t capture the return value. It will run in the background, and will be killed if its still running at program exit.

pub fn get_associate(&mut self, name: &str) -> Option<&mut Handle>

Returns a mutable reference to an associate within the Handle, if it exists. The associate is another Handle instance.

pub fn error(&mut self) -> Result<&mut Stream, Error>

Return the Stream associated with the child’s standard error, if it exists. Note that pulling from the Stream consumes the contents–calling error_all will only return the contents from when you last pulled from the Stream.

pub fn error_all(self) -> Result<String, Error>

Waits for the child to terminate, then returns its entire standard error.

pub fn output(&mut self) -> Result<&mut Stream, Error>

Return the Stream associate with the child’s standard output, if it exists. Note that pulling from the Stream consumes the contents–calling output_all will only return the contents from when you last pulled from the Stream.

pub fn output_all(self) -> Result<String, Error>

Waits for the child to terminate, then returns its entire standard output. If you need the exit code, use wait() first.

pub fn close(&mut self) -> Result<(), Error>

Closes the Handle’s side of the standard input pipe, if it exists. This sends an EOF to the child.

Trait Implementations

impl Drop for Handle

fn drop(&mut self)

Executes the destructor for this type.

impl Write for Handle

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.