Struct shadow_rs::utility::childpid_watcher::ChildPidWatcher

pub struct ChildPidWatcher { /* private fields */ }

Utility for monitoring a set of child pid’s, calling registered callbacks when one exits or is killed. Starts a background thread, which is shut down when the object is dropped.

Implementations

impl ChildPidWatcher

pub fn new() -> Self

Create a ChildPidWatcher. Spawns a background thread, which is joined when the object is dropped.

pub unsafe fn fork_watchable( &self, child_fn: impl FnOnce(), ) -> Result<Pid, Errno>

Fork a child and register it. Uses fork internally; it vfork is desired, use register_pid instead.

Panics if child_fn returns. TODO: change the type to FnOnce() -> ! once that’s stabilized in Rust. https://github.com/rust-lang/rust/issues/35121

Safety

As for fork in Rust in general. Probably, mostly, safe, since the child process gets its own copy of the address space and OS resources etc. Still, there may be some dragons here. Best to call exec before too long in the child.

pub fn register_pid(&self, pid: Pid)

Register interest in pid.

Will succeed even if pid is already dead, in which case callbacks registered for this pid will immediately be scheduled to run.

pid must refer to some process, but that process may be a zombie (dead but not yet reaped). Panics if pid doesn’t exist at all. The caller should ensure the process has not been reaped before calling this function both to avoid such panics, and to avoid accidentally watching an unrelated process with a recycled pid.

pub fn unregister_pid(&self, pid: Pid)

Unregister the pid. After unregistration, no more callbacks may be registered for the given pid. Already-registered callbacks will still be called if and when the pid exits unless individually unregistered.

Safe to call multiple times.

pub fn register_callback( &self, pid: Pid, callback: impl Send + FnOnce(Pid) + 'static, ) -> WatchHandle

Call callback from another thread after the child pid has exited, including if it has already exited. Does not reap the child itself.

The returned handle is guaranteed to be non-zero.

Panics if pid isn’t registered.

pub fn unregister_callback(&self, pid: Pid, handle: WatchHandle)

Unregisters a callback. After returning, the corresponding callback is guaranteed either to have already run, or to never run. i.e. it’s safe to free data that the callback might otherwise access.

No-op if pid isn’t registered.

Trait Implementations

impl Debug for ChildPidWatcher

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

Formats the value using the given formatter.

impl Default for ChildPidWatcher

fn default() -> Self

Returns the “default value” for a type.

impl Drop for ChildPidWatcher

fn drop(&mut self)

Executes the destructor for this type.