Struct ContainedChild 

pub struct ContainedChild { /* private fields */ }

A spawned child leading its own process group, with tree-wide termination.

While the leader is unreaped and the handle is armed, dropping it SIGKILLs the group — the containment guarantee under task abort. Once reaped, the guard stands down: the id is no longer safely ours to signal.

Implementations

impl ContainedChild

pub fn spawn(command: Command) -> Result<Self, ProcessGroupError>

Spawn command as the leader of a fresh process group.

The caller configures stdio before calling: piping it captures output, inheriting it sends the child’s output wherever this process’s goes.

Errors

Returns ProcessGroupError::Unsupported on a target without process groups, ProcessGroupError::Spawn when the command cannot start, and ProcessGroupError::MissingProcessId or ProcessGroupError::ProcessIdOutOfRange when the started child cannot be addressed as a group.

pub fn id(&self) -> Option<u32>

The direct child’s process id, while it has not been reaped.

pub const fn process_group_id(&self) -> Option<i32>

The raw process-group id, on a target that has process groups.

None off Unix, where Self::spawn refuses in the first place.

pub const fn exit_status(&self) -> Option<ExitStatus>

The exit status recorded by whichever call reaped the leading child.

pub fn take_stdout(&mut self) -> Option<ChildStdout>

Take the captured stdout pipe, when the command was configured with one.

pub fn take_stderr(&mut self) -> Option<ChildStderr>

Take the captured stderr pipe, when the command was configured with one.

pub async fn wait(&mut self) -> Result<ExitStatus, ProcessGroupError>

Wait for the DIRECT child to exit, REAPING it.

After this returns, the process-group id is no longer safely ours: see the module header. Callers that still need to stop the tree must use [Self::wait_for_exit] instead, which observes the exit without consuming it.

Errors

Returns ProcessGroupError::Reap when waiting fails.

pub async fn terminate( &mut self, grace: Duration, ) -> Result<(), ProcessGroupError>

Stop the whole group, then reap the leading child.

SIGTERM → grace → SIGKILL, BOTH sent while the leader is unreaped, so the group being signalled is provably the one this handle created. Once the leader has already been reaped no signal is sent at all: the id may belong to anyone by then, and a stop that cannot be aimed is a stop that must not be attempted.

The SIGKILL is unconditional rather than conditional on surviving the SIGTERM. Checking first would mean either reaping the leader (which forfeits the right to signal) or reading a probe that a live-or-zombie leader always answers “alive” to — so the check cannot work, and an extra signal to an empty group costs nothing.

This says nothing about whether the group ended up EMPTY. Proving that is the caller’s job: Self::confirm_group_gone where there is nothing else to go on, or end-of-file on captured output, which no surviving descendant holding the write end could produce.

Errors

Returns ProcessGroupError::Unsupported off Unix, ProcessGroupError::Signal when the OS refuses to signal, and ProcessGroupError::Reap when the leader cannot be reaped.

pub async fn confirm_group_gone( &self, within: Duration, ) -> Result<(), ProcessGroupError>

Poll until the group is provably gone, or the window closes.

A read, never an act — which is what makes it safe after the leader has been reaped, where acting on a wrong answer would be the disaster.

Errors

Returns ProcessGroupError::Unsupported off Unix, ProcessGroupError::Probe when the probe itself fails, and ProcessGroupError::GroupStillAlive when the window closes with the group still observable.

pub const fn disarm(&mut self)

Release the drop guard without signalling anything.

For a caller that has established the group is gone by other means — the captured pipes reaching EOF, for instance, which no descendant holding the write end could allow.

Trait Implementations

impl Debug for ContainedChild

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

Formats the value using the given formatter.

impl Drop for ContainedChild

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

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

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.