Struct GlobalState 

pub struct GlobalState { /* private fields */ }

Global state associated with the detcore tool.

This is a singleton, and the one object of this type lives inside a central address space, generally the “tracer” in a Reverie backend.

Implementations

impl GlobalState

pub fn native_exec_host_config(&self) -> &Config

The complete actual host configuration retained by this GlobalState, including legitimate host-only fields omitted from the Tool wire. Native admission uses this owner rather than a separate caller Config.

pub fn install_native_exec_registry( &self, registry: NativeExecRegistry, ) -> Result<(), ExecControlError>

Install the genuine watched authority once, before native controls. Ordinary runs leave this absent. No request can create this capability.

pub fn native_exec_registry(&self) -> Option<&Mutex<NativeExecRegistry>>

The very same retained store for native admission and birth watchers. Callbacks must drop this guard before acquiring the scheduler mutex.

impl GlobalState

pub fn take_unsupported_syscalls(&mut self) -> BTreeSet<String>

Transfer the completed run’s diagnostic aggregate to its output owner. The backend must first reclaim exclusive ownership after all RPC clients have drained. Callers that do not take it retain the ordinary Drop warning.

pub fn retired_inodes(&self) -> Vec<DetInode>

The deterministic numbers of the files whose last name the run removed while they were numbered and that no later name showed to be reused (see InodePool::retire), in increasing order. Diagnostic, for tests of the removal paths (https://github.com/rrnewton/hermit/issues/3840).

pub fn reused_inode_count(&self) -> u64

How many retired inode numbers a later name or open showed the host had given to another file. Diagnostic, for tests that make a host reuse an inode (https://github.com/rrnewton/hermit/issues/3840).

pub fn mount_identity_provenance( &self, ) -> Result<Option<MountIdentityProvenance>, &'static str>

Return the producer-observed mount identity order after a run.

The first vector is the exact mountinfo row/parent order. The second is the order in which the run numbered raw mount IDs.

pub fn init_for_external_scheduler(cfg: &Config) -> Self

Initializes global state whose sequential scheduler is driven by an external backend executor.

pub fn run_external_scheduler( &self, observer: Arc<dyn Fn(&'static str) + Send + Sync>, ) -> impl Future<Output = ()> + use<>

Returns the sequential scheduler loop for a backend-owned executor to run.

This is deliberately not an async fn: the announcement is logged when this is called, not when the returned future is first polled. A backend can then order it ahead of anything it releases before polling (DBT publishes READY_IMAGE, which lets the root guest thread log its seeding lines). See https://github.com/rrnewton/hermit/issues/3463.

pub fn complete_physical_process_exit(&self, raw_pid: i32)

Reports that a backend supervisor received a process’s final kernel exit status.

This records a barrier observation when the backend advertises physical-exit reporting or asynchronous exit completion; it is a no-op for ptrace, DBT and KVM. The exact process’s barrier is released at this physical-waitability boundary.

With asynchronous exit completion, registrations the process did not deregister itself are retired here first, in the same locked step, and a determinism loss is recorded: such a process died without finishing its exit hook, at a moment the host chose, so the run must not be compared.

pub fn release_all_physical_process_exits(&self)

Releases all physical-process-exit barriers after a backend supervisor has drained every tracee and no guest thread can race another lifecycle event.

pub fn note_syscall_observation_gap(&self, gap: SyscallObservationGap)

Record that the run’s syscall histogram cannot count every syscall the guest makes, for gap. Its summary then reports a partial observation scope.

pub fn policy_refusal(&self) -> Option<String>

Why the fail-closed policy ended the run, when a Tool image reported it before exiting (GlobalRequest::PolicyRefusal).

pub fn force_shutdown_with_error(&self)

Unrecoverable fatal erorr. Bring things to a close cleanly, but as quickly as possible.

pub async fn cancel_internal_scheduler(&mut self)

Cancels the internally spawned scheduler task after a backend guest exits abnormally.

External-scheduler states do not own a task and are left unchanged.

pub fn terminal_outcome(&self) -> Option<TerminalOutcome>

The terminal outcome this run ended with, when its backend unwound the guest for it (TerminalOutcomeUnwindGuard): the status the run completed with is then the outcome’s, not one the guest exited with.

pub async fn clean_up_after_backend_failure(self) -> BackendFailureCleanup

Consume failed-run state after the scheduler has naturally finished.

A failed run has no successful run summary. Preserve the scheduler’s join error and any requested partial preemption recording’s write error for the caller, without allowing either to replace the backend failure.

pub async fn clean_up( self, to_stderr: bool, print_summary_to_json_file: &Option<PathBuf>, ) -> Result<()>

Shut down anything running, in particular wait on the scheduler.

This is basically the destructor for the global state, but is here rather than in the Drop instance so that it can be async, and is more explicitly sequenced in the program.

Print a summary of the execution, typically called when it is complete.

If the boolean argument is true, print to stderr, otherwise only print the summary to the log.

Returns terminal replay, recording, or summary errors after consuming the remaining recording writer. Callers retain their outer owners until this returns and must not publish completed metadata on failure.

pub async fn clean_up_with_dispatch_stats( self, to_stderr: bool, print_summary_to_json_file: &Option<PathBuf>, dispatch_stats: Option<DispatchStats>, ) -> Result<()>

Self::clean_up, also carrying the backend’s dispatch record into the machine-readable summary. The human-readable report, including the INFO view --verify compares, never shows it.

Trait Implementations

impl Debug for GlobalState

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

Formats the value using the given formatter.

impl Default for GlobalState

fn default() -> Self

Returns the “default value” for a type.

impl Drop for GlobalState

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.

impl GlobalTool for GlobalState

type Request = (DetTime, MmId, GlobalRequest)

A request asks the scheduler to perform an RPC, which includes multiple kinds of actions, and, most importantly, permission to acquire resources and run the guest thread.

Irrespective of which method we execute, we can “tick” our local component of the global time in the process.

type Response = (Option<LogicalTime>, GlobalResponse)

Response from the global portion of the Detcore instrumentation tool. The exact form of the response depends on which method was executed.

Irrespective of which method was called, the global handling may have consumed logical time, in which case the scheduler can send a new thread-local time back to the caller. Unfortunately, information is lost as this is collapsed to a flat scalar instead of a rich DetTime.

fn init_global_state<'life0, 'async_trait>( cfg: &'life0 Config, ) -> Pin<Box<dyn Future<Output = GlobalState> + Send + 'async_trait>>

where 'life0: 'async_trait,

Called once during startup.

fn observe_signal_dequeues(&self, mode: BackendSignalControlMode) -> bool

Dequeues carry real-timer signals only in a run that installed the backend’s control; any other run leaves them to the guest kernel.

fn skip_empty_signal_boundaries(&self) -> bool

Detcore lets the backend skip an empty user-return boundary. Only reverie-kvm reads this answer, and only once Detcore’s install_signal_control returned ToolControlled, which needs the backend’s process signal control and --sequentialize-threads. The ptrace, DBT, SaBRe and LiteInst backends never ask, so the constant is fixed for the run on every backend, as the contract requires.

An empty boundary is one where the thread holds no permit and the backend shows no pending signal its mask leaves unblocked, no parked ledger, no signalfd in the process, no dequeue-journal entry of the thread, and no stored dequeue failure. There the full round trip is authorize_signal_boundary, a selection of nothing, and a NoHandler receipt to consume_signal_boundary. Skipping it is unobservable:

• Authorization publishes nothing. Detcore’s own signals (real-timer and POSIX-timer expiry, child-exit SIGCHLD) are published under the scheduler lock at scheduler time into the backend’s pending sets or dequeue journal, which make a boundary non-empty, so none is lost.

• The round trip’s permit is read by no other decision. Permits are per thread (https://github.com/rrnewton/hermit/issues/4899), and apart from the holder’s own authorization and receipt, every reader of parked.permits reads one named thread’s entry, or only the observation permits of parked waits, which a boundary’s permit never is:

  • another thread’s authorization, the exit reservation (reserve_exit_boundary) and the parked-request retirements (retire_parked_requests, retire_replaced_parked_request, retire_child_wait_signal_request) read their own thread’s entry;
  • alarm selection (select_parked_alarm) skips a process only for an observation permit (one with a site) and otherwise reads each recipient’s own entry, and a thread at a boundary is no parked-wait recipient;
  • an observation’s finish (finish_observation) and another thread’s receipt remove only their own thread’s entry;
  • process retirement (finish_process_retirement) reads every entry of the process, but only once its leader has joined every thread, never during a live thread’s boundary.

  So with or without the round trip, every decision sees the same permits of every other thread, and the boundary’s thread holds none once the round trip ends.

• The round trip runs inside the thread’s own serial grant. Authorization succeeds only for parked.running. The only skippable boundaries follow a completed Tool callback or a backend-owned rt_sigreturn (thread entry checks only when a signal is eligible). Every request is awaited, and every background release (BlockingExternalIO, BlockingRtSigsuspend, a vfork parent) awaits its BlockedExternalContinue grant before the callback returns, so such a boundary is always inside the thread’s own serial grant (holds_serial_grant). No grant, alarm selection or step2 drain runs then: they wait for quiescence, and are_all_quiesced waits on the running thread’s empty request. The control-intent drain (drain_control_intents) does run on every pass of the turn loop, but its intents only finish or resume an observed parked wait, and touch only that wait’s own permit.

• The receipt’s cleanup is redundant there. Every grant settles the parked request it answers (settle_parked_grant), and every request the scheduler substitutes for a filed one retires the replaced request’s ownership (retire_replaced_parked_request), so no ownership outlives its request. An observed wait’s request and Observation owner, and a ReturningCaught owner, always come with a permit, which makes the boundary non-empty.

• The rest is bookkeeping no decision reads: parked.nonce stays monotonic, only smaller, and is never logged; parked.completed only recognises an exact duplicate receipt.

The cost is that Detcore’s identity checks at authorization (ESRCH, EINVAL) now run only at non-empty boundaries.

Held once before, while a backgrounded KVM rt_sigsuspend race was open (https://github.com/rrnewton/hermit/issues/4360). That race is fixed: a KVM rt_sigsuspend now runs in its caller’s turn. Before that fix the race fired about as often with this opt-in as without it.

An earlier form of this proof called an observed wait’s permit short-lived and unseen by other decisions. It is not short-lived: it lasts until the observed thread’s return-boundary receipt, across that thread’s InboundSignal turn, during which siblings run. While permits were one per process, a sibling’s boundary saw it and was refused (https://github.com/rrnewton/hermit/issues/4899). The argument above no longer depends on any permit’s lifetime.

Re-prove or drop this if Detcore ever holds pending signals, or its own mask copy, that the backend cannot see and delivers them through authorization, or if the backend’s KVM signal policy moves into Detcore: the skip trusts the backend’s pending sets and mask.

fn on_backend_signal_boundary<'life0, 'async_trait>( &'life0 self, receipt: SignalBoundaryReceipt, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

A terminal receipt of a death by a fatal signal also lets go of the dying threads’ descriptor tables (GlobalState::release_tables_at_death), before the receipt returns to the backend, so before the backend publishes the death to a parent or retires the process: the control barrier the receipt installed holds every later turn until then.

fn on_backend_process_exited(&self, pid: i32)

A backend whose process exits complete asynchronously reports each physical exit here; see GlobalState::complete_physical_process_exit.

fn backend_pending_process_exits(&self) -> Vec<i32>

The processes held between their exit grant and their physical exit, for the backend’s watchdog.

type Config = Config

Static, read-only configuration data that is available everywhere the tool runs code.

fn install_inherited_input(&mut self, input: InheritedInputLease)

Offer the actual launcher-created input before sharing this run’s global state or starting any guest hook. The default does not need the binding.

fn install_mapping_capture_run(&mut self, run: MappingCaptureRun)

Install launcher-owned capture accounting before the first guest hook. Only an external controller may retain this handle. Capture authority is enabled only when existing containment performs whole-run cleanup; disabled accounting retains refusals without authorizing capture. Default Tools do not use it. See [crate::MappingCaptureRun]. This capability does not certify the controller’s filesystem context. A Tool reading path-rendered procfs views must independently authenticate an equal target/reader root and mount namespace and ensure that no controller callback or shared-FS executor changes that context during the synchronous read. Endpoint equality alone does not exclude ABA.

fn install_reserved_input_control( &mut self, control: ReservedInputControl, ) -> Result<(), Error>

Install the backend-owned local input registry before guest creation. The handle is never part of Config, RPC, or serialized thread state.

fn on_reserved_input_task( &self, task: InputTaskRegistration, ) -> Result<(), Error>

Observe a native task incarnation before logical retirement can name it. Called synchronously outside all registry locks.

fn admit_reserved_input_initial_state( &self, facts: &InputNativeFacts, ) -> Result<InputAdmission, Error>

Admit physical initial facts before callbacks can expose a target image. The default does not certify an environment for private input.

fn on_reserved_input_setup( &self, receipt: InputSetupReceipt, ) -> Result<(), Error>

Observe actual target-image setup, including unsuccessful qualification. A launch bootstrap is not a target image. No default or Drop path emits it.

fn install_backend_signal_control( &self, control: Option<BackendSignalControl>, ) -> Result<BackendSignalControlMode, Error>

Install one run-scoped backend capability before the first guest hook. The default preserves backend-owned selection. A Tool may reject a missing capability here. A Tool whose [Tool::requires_signal_control] holds need not: reverie-kvm refuses that run with EINVAL when it offered a control and this did not return ToolControlled, and with ENOSYS, before asking, when it has no control to offer.

fn authorize_backend_signal_boundary( &self, task: SignalTaskIdentity, ) -> Result<Option<SignalDeliveryPermit>, Error>

Authorize the current real user-return boundary. The backend calls this outside signal locks; host callback arrival is not authorization. See [Self::skip_empty_signal_boundaries] for the boundaries a Tool may let the backend skip.

fn on_backend_process_retired( &self, event: BackendProcessRetirement, ) -> Result<(), Error>

Reports final process cleanup after the leader has joined every guest thread and released their descriptor references, including its own. Only a backend offering BackendSignalControl sends this callback. A Tool may retain a fence awaiting it only with that capability installed in ToolControlled mode; a backend offering that mode must complete the callback after successful process retirement. A terminal boundary receipt can establish this fence and must remain able to cancel peer RPCs. The fence then keeps other processes from observing host-timed EOF.

fn on_fatal_signal_exit(&self, exit: &FatalSignalExit)

Called by a backend that holds guest thread exit.tid at its exit stop while the thread’s whole process is exiting because of a signal whose default action dumps core, before the thread is released to finish exiting. The kernel has already made the fatal decision and its own core dump step is over, so the thread’s exit status cannot change.

fn report_backend_failure(&self, event: BackendFailure)

Reports a fatal backend failure before cleanup can wait on another Tool callback. This is a failed run, not a guest exit, signal, or RPC reply. Implementations must finish their terminal transition synchronously, including making concurrent consuming cleanup safe, before returning. Complete that transition before waking any failure subscriber. Several workers may report distinct errors in one run, so this method must be idempotent and preserve the first terminal cause. It must not wait for Tool callbacks or physical worker joins that depend on that transition.

fn wait_for_backend_failure<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Waits until this run cannot continue faithfully. Each call must subscribe independently: multiple Tool callbacks and the scheduler may be waiting. The default preserves Tools that do not own a scheduler. Returning allows the backend to drop in-flight callbacks, including receive_rpc, and proceed to consuming exit hooks. Shared state must already support that cleanup; returning is not an ordinary RPC reply. A backend may poll the returned future again only after the waker it was last polled with fires (the ptrace backend does, and so does the KVM backend’s kept callback failure wait), so a pending future must arrange that wake rather than rely on being polled again for another reason.

fn on_backend_child_wait_event<'life0, 'async_trait>( &'life0 self, event: BackendChildWaitEvent, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Reports that a backend observed a child transition and committed its waitability for the parent process.

fn receive_rpc<'life0, 'async_trait>( &'life0 self, from: Tid, gr: Self::Request, ) -> Pin<Box<dyn Future<Output = Self::Response> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Receive a (potentially) inter-process upcall on the global state object. This intended to be IPC, inter-process communication, in some backends, and a local method call in others, but never truly a communication between different machines.

fn on_watchpoint_hit(&self, _hit: &WatchHit)

Receives an access that a hardware watchpoint caught (Guest::set_watchpoints). Hits of one thread arrive in the order the thread made the accesses.