Crate rightkit_child_process 

OwnedCommand::inherit_handles_only restricts inheritance to caller handles/fds plus stdio; Windows requires windows_spawn_config for opaque Command settings.

Modules

login_shell

The user’s login-shell PATH and selected environment values, for an app launched from the desktop (Finder, the Dock, a launch agent) that inherits only the session’s minimal environment. Unix only: on Windows every function returns nothing and runs nothing.

reveal

Reveal a file or folder in the system file manager, or open it with its default handler, through OwnedCommand, and only inside caller-supplied roots.

Structs

Ack

Handed to the watched party; calling Ack::done proves it is alive.

AdoptedIdentity

A pid together with the start time and executable path that make it a name for exactly one process. See the module documentation.

AdoptedProcess

BreakawayDenied

The error source returned (inside an io::Error of kind PermissionDenied) by OwnedCommand::spawn_uncontained_detached_strict on Windows when the caller’s job object denies CREATE_BREAKAWAY_FROM_JOB. The OS reports this as ERROR_ACCESS_DENIED, which this crate cannot tell apart from other access-denied launch failures; a job that forbids breakaway is the cause this crate expects.

BudgetLabels

Names and scale of the load behind an IdleObservation, for IdleObservation::result_lines.

CapturedOutput

What a capture holds.

ConsecutiveFailures

Cap on restarts granted in a row without the replacement ever reporting ready.

Cooldown

Minimum spacing between expensive actions (HeardRight samples stacks at most once a minute). Pure; the caller supplies now.

Generation

HealthPolicy

HealthTracker

HeartbeatConfig

A file another process rewrites as its heartbeat. The watch reads only its modification time, so the writer needs no protocol: a process that keeps touching the file is alive.

HeartbeatWatch

A running heartbeat-file watch. Dropping it stops and joins the thread.

IdleObservation

What a process did over a quiet window: the idle figures a runtime budget names.

JobAssignmentFailure

MatchSweepOptions

How sweep_matching behaves.

MatchSweepReport

The result of sweep_matching.

MatchedProcess

A process that satisfied a ProcessQuery.

NativeOutputCapture

An owned reader of a native child stdout/stderr pipe, with bounded byte retention.

OutputCapture

A background drain of one output stream into a bounded byte buffer. See the module documentation.

OwnedChild

OwnedCommand

PowerAssertion

A live keep-awake request. Released on drop.

ProcessEntry

One row of the process table.

ProcessHandle

An independent exit reader. On Unix it shares the owner’s cached reap state; on Windows it owns a duplicated process handle, never a borrowed handle value. Keeping this reader alive does not keep an owned process tree alive.

ProcessQuery

Which processes to find. All criteria that are set must hold. Built with the methods below; at least one criterion is required.

ProcessUsage

One snapshot of the current process’s resource usage.

RestartPermit

RestartPolicy

RestartTracker

RunOptions

Limits for run.

RunOutput

What run observed.

StallConfig

StallWatchdog

A running watchdog. Dropping it stops and joins the thread.

StartToken

When a process started, in the host’s own unit (macOS: seconds and microseconds; Linux: clock ticks since boot and 0; Windows: 100 ns ticks since 1601 and 0). Comparable only on the host that produced it.

StderrTail

A background drain of one stderr stream. Keeps the most recent lines whose total size is at most max_bytes; older lines fall off the front. A single line that alone exceeds the budget is cut to its last bytes, so snapshot never returns more than max_bytes bytes.

SweepReport

The result of sweep, as pids.

TerminateAllReport

The result of terminate_all_owned, as pids.

TerminationOptions

TreeTermination

The result of OwnedChild::terminate_tree_deep.

TreeUsage

Resident memory summed over one remembered process and the descendants found while it lived. Members are counted only while their pid-plus-start-time identity still verifies after the table snapshot, so a pid recycled during the scan contributes nothing.

UnixChild

A spawned Unix child. The same API as Windows’ WindowsChild: public stdio fields, id, try_wait, wait and kill. It does not expose the std Child, because a std reap the crate cannot see would make later group signals unsafe (see the module documentation).

UsageRates

Rates between two snapshots. Each rate is None when either snapshot lacks the counter.

Enums

AdoptedSignal

How hard to stop a process. Windows has one way to stop a process, so both are the same there.

HealthOutcome

HealthProbe

HeartbeatEvent

What a HeartbeatWatch reports, edge-triggered like StallEvent.

IdentityCheck

What a pid names now, compared with a remembered identity.

JobAssignmentMode

PowerKind

What to keep awake.

ProcessPriority

Scheduling priority requested for the child. Normal (the default) means “inherit”: it leaves the spawn exactly as it was before this option existed, so the child keeps the parent’s priority class (Windows) or nice value (Unix). It does not reset a lowered parent back to normal. The other values only lower priority, which needs no privilege and never raises a value the child already inherits above a lower one.

ReapOutcome

RestartMode

RestartOutcome

SignalResult

The outcome of AdoptedIdentity::signal.

StallEvent

UnixContainment

WaitOutcome

Constants

CREATE_BREAKAWAY_FROM_JOB

The Windows CREATE_BREAKAWAY_FROM_JOB creation flag, exposed on every platform so a caller that composes its own flags (for example a deliberately detached replacement process) can OR it in. It asks the new process to leave the creator’s job object; the launch fails with access denied when that job forbids breakaway.

CREATE_NO_WINDOW

The Windows CREATE_NO_WINDOW creation flag, exposed on every platform so a caller that composes its own flags can OR it in.

DEFAULT_DROP_REAP_TIMEOUT

How long Drop waits for a killed leader to be reaped before handing the reap to a background thread.

DEFAULT_ENV_ALLOWLIST

Traits

NoWindow

Suppresses the child’s console window on Windows. A no-op elsewhere.

Functions

command_std

A std::process::Command for program that already has the no-window flag set on Windows, returned by value so it chains: command_std("git").args(["status"]).output(). Same effect as Command::new(program) followed by NoWindow::no_window. The async variant is tokio_support::command (feature tokio).

find_processes

Every process that satisfies query, newest first (children tend to come before the parents that started them). Nothing is signalled. Processes that cannot be inspected (they exited, or belong to another user, or deny access) are skipped, never an error.

launch_app

Launches the installed app id: a macOS bundle identifier on macOS, a Windows AppUserModelID on Windows. Other Unix hosts return Unsupported.

observe_idle

Sleeps duration on the calling thread and reports the process’s usage over it. Run it after the load has stopped; it is for benches and tests, so a host reads process_usage instead.

open_url

Opens url with the handler registered for its scheme (for example claude://).

owned_count

How many owned children are listed and still alive (their OwnedChild has not been dropped). A child that exited but was not dropped is still counted.

process_group_exists

Observation-only existence probe for a Unix process group: sends signal 0 and nothing else. EPERM means members exist that this process may not signal, so the group is present. Group 1 (init’s group) and any id that cannot name a group are refused with InvalidInput; NonZeroU32 already excludes 0, which would name this process’s own group. A group holding only zombies whose parent is elsewhere stays present until they are reaped: this is a group observation, not a per-member liveness check (use AdoptedIdentity::is_running for a remembered member).

process_table

Snapshot every process the OS lets this process see.

process_usage

Resource usage of the current process, computed now.

read_bounded

Reads reader to its end on the calling thread, keeping the first max_bytes bytes. The rest is read and discarded. Use this when the caller can block until the stream closes.

resume_session

Resumes (SIGCONT) every process group in session sid; same contract as signal_session. Unix only.

run

Runs program with args to completion or until options.timeout, then returns its status and bounded output. Fails when the program or native output capture cannot start, or lifecycle waiting fails. A non-zero exit is a normal Ok with status set.

run_with_stdin

run with input written to the child’s stdin. The bytes are written on their own thread while output is drained concurrently, so input larger than a pipe buffer cannot deadlock against a chatty child; the writer closes stdin when done, delivering EOF. A child that exits before consuming the input closes the pipe: that broken-pipe outcome is a normal early exit, not an error, and the child’s status/output are returned as usual. Any other stdin write failure is returned as Err after the tree is down. A process that outlived the tree and still holds stdin without reading it cannot hold run past its deadline: once the tree is down the writer gets a short grace, then it is cancelled (Unix: non-blocking write end; Windows: CancelIoEx) and joined.

signal_session

Sends signal to every process group in session sid (see [session_groups]). Returns true when at least one group was found and reached. Unix only. Best effort: the groups are found by a process-table scan and signalled by group id, so a group that exits and whose id is reused between the scan and the signal can be hit. Use it for a session the caller created (a pseudo-terminal leader), not for an arbitrary session.

suspend_current_process

Suspends the current process with SIGTSTP (the terminal Ctrl-Z stop), so a shell or TUI can hand the terminal back and resume on SIGCONT. Returns once the process is continued. Unix only.

suspend_session

Suspends (SIGSTOP) every process group in session sid; same contract as signal_session. Unix only.

sweep

Stops every process in targets that is still the process it was remembered as: a graceful signal to each, up to grace for them to leave, then a forced signal to those still present. A target whose pid names a different process is refused, never signalled. Targets are signalled in the order given; pass leaves first (the reverse of AdoptedIdentity::descendants).

sweep_descendants

sweep of root’s current descendants, leaves first. The root itself is left alone.

sweep_matching

find_processes, then stop what was found with the identity-checked sweep (unless options ask for a dry run).

terminate_all_owned

Stops every child this process owns (everything started with OwnedCommand::spawn whose OwnedChild has not been dropped), tree and all, in one call: for an application’s shutdown path, replacing an app-kept list of running children.

tree_usage

TreeUsage for root and its current descendants (see AdoptedIdentity::descendants for which descendants can be found). A root that is gone or replaced yields an empty usage, not an error. Member figures come from one process_table snapshot, then every member is verified again before it is counted.

wait_process_group_empty

Waits at most timeout for a process group to empty; Ok(false) when members remain then. Observation only (see process_group_exists); it never signals the group.

Type Aliases

RawHandleOrFd