Skip to main content

ProcessHandle

Struct ProcessHandle 

Source
pub struct ProcessHandle { /* private fields */ }
Expand description

Re-exported process-bound signal and exit-watch handle (ProcessHandle) from sysprims-signal. A signal and exit-watch handle bound to a verified process incarnation.

Opening a ProcessHandle reads the target process’s native start-identity, acquires the OS exit/process handle (pidfd on Linux, kqueue EVFILT_PROC NOTE_EXIT on macOS, HANDLE on Windows) with FD_CLOEXEC / non-inheritable flags, and re-reads the native start-identity to prove the PID was neither exited nor reused during registration.

Raw OS descriptors/handles are never exposed and are closed automatically on Drop or ProcessHandle::close.

Implementations§

Source§

impl ProcessHandle

Source

pub fn open(pid: u32) -> Result<ProcessHandle, SysprimsError>

Open a ProcessHandle for pid, bracketing registration with native start-identity checks before and after opening the OS handle.

§Errors
Source

pub fn open_verified( pid: u32, expected_start_identity: &str, ) -> Result<ProcessHandle, SysprimsError>

Open a ProcessHandle for pid and require its bracketed native start-identity to equal expected_start_identity.

If pid is currently held by a different process incarnation (different start-identity), returns SysprimsError::NotFound.

Source

pub const fn pid(&self) -> u32

Numeric PID (1..=MAX_SAFE_PID) verified at handle creation.

Source

pub fn start_identity(&self) -> &str

Canonical native start-identity string captured at handle creation ("<tv_sec>.<tv_usec:06>" on macOS, "<starttime_ticks>" on Linux, "<creation_filetime_100ns>" on Windows).

Source

pub const fn binding(&self) -> SignalBinding

Binding strength for signals sent through this handle.

Source

pub fn is_closed(&self) -> bool

Whether ProcessHandle::close has been called on this handle.

Source

pub fn exited(&self) -> Result<bool, SysprimsError>

Check whether whole-process exit has been observed for the bound process.

This result is latched: once Ok(true) is observed, subsequent calls on the same open handle always return Ok(true) even after the process is reaped or its numeric PID is reused by another process.

Source

pub fn signal(&self, sig: i32) -> Result<SignalBinding, SysprimsError>

Deliver sig to the bound process only, returning the SignalBinding strength used for delivery.

Once exit is observed, no signal is sent and SysprimsError::NotFound is returned.

Source

pub fn signal_by_name( &self, signal_name: &str, ) -> Result<SignalBinding, SysprimsError>

Resolve signal_name (e.g. "SIGTERM", "TERM", "kill") and deliver it to the bound process.

Source

pub fn terminate(&self) -> Result<SignalBinding, SysprimsError>

Convenience wrapper: deliver SIGTERM to the bound process.

Source

pub fn force_kill(&self) -> Result<SignalBinding, SysprimsError>

Convenience wrapper: deliver SIGKILL to the bound process.

Source

pub fn close(&self)

Close the underlying OS resource early (idempotent).

Trait Implementations§

Source§

impl Debug for ProcessHandle

Source§

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

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

impl Drop for ProcessHandle

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

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. Read more

Auto Trait Implementations§

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> Same for T

Source§

type Output = T

Should always be Self
Source§

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

Source§

type Error = !

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

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

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

Source§

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.