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
impl ProcessHandle
Sourcepub fn open(pid: u32) -> Result<ProcessHandle, SysprimsError>
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
SysprimsError::InvalidArgumentifpid == 0orpid > MAX_SAFE_PIDSysprimsError::NotFoundif the process does not exist, is already exited/zombie, or changed incarnation during registrationSysprimsError::PermissionDeniedif the caller is not permitted to signal/inspectpid
Sourcepub fn open_verified(
pid: u32,
expected_start_identity: &str,
) -> Result<ProcessHandle, SysprimsError>
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.
Sourcepub fn start_identity(&self) -> &str
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).
Sourcepub const fn binding(&self) -> SignalBinding
pub const fn binding(&self) -> SignalBinding
Binding strength for signals sent through this handle.
Sourcepub fn is_closed(&self) -> bool
pub fn is_closed(&self) -> bool
Whether ProcessHandle::close has been called on this handle.
Sourcepub fn exited(&self) -> Result<bool, SysprimsError>
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.
Sourcepub fn signal(&self, sig: i32) -> Result<SignalBinding, SysprimsError>
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.
Sourcepub fn signal_by_name(
&self,
signal_name: &str,
) -> Result<SignalBinding, SysprimsError>
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.
Sourcepub fn terminate(&self) -> Result<SignalBinding, SysprimsError>
pub fn terminate(&self) -> Result<SignalBinding, SysprimsError>
Convenience wrapper: deliver SIGTERM to the bound process.
Sourcepub fn force_kill(&self) -> Result<SignalBinding, SysprimsError>
pub fn force_kill(&self) -> Result<SignalBinding, SysprimsError>
Convenience wrapper: deliver SIGKILL to the bound process.