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 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 first-observation order of raw fdinfo IDs absent from that table.

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 only records a barrier observation when the backend advertises physical-exit reporting; it is therefore a no-op for ptrace, DBT, KVM, and LiteInst execution. The exact process’s barrier is released at this physical-waitability boundary.

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 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 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>, )

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.

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

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.

type Config = Config

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

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 that requires controlled process signals must reject missing capabilities here.

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.

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,

Consume a real signal boundary before user entry. This hook must retain ownership across cancellation; it is not an ordinary grant or syscall.

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 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. The ptrace backend polls the returned future again only after the waker it was last polled with fires, 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.