Struct LabRuntime 

pub struct LabRuntime {
    pub state: RuntimeState,
    pub scheduler: Arc<Mutex<RawMutex, LabScheduler>>,
    pub oracles: OracleSuite,
    /* private fields */
}

The deterministic lab runtime.

This runtime is designed for testing and provides:

• Virtual time instead of wall-clock time
• Deterministic scheduling based on a seed
• Trace capture for debugging and replay
• Chaos injection for stress testing

Fields

state: RuntimeState

Runtime state (public for tests and oracle access).

scheduler: Arc<Mutex<RawMutex, LabScheduler>>

Scheduler.

oracles: OracleSuite

Oracle suite for invariant verification.

Implementations

impl LabRuntime

pub fn new(config: LabConfig) -> LabRuntime

Creates a new lab runtime with the given configuration.

pub fn with_seed(seed: u64) -> LabRuntime

Creates a lab runtime with the default configuration.

pub const fn now(&self) -> Time

Returns the current virtual time.

pub const fn steps(&self) -> u64

Returns the number of steps executed.

pub const fn config(&self) -> &LabConfig

Returns a reference to the configuration.

pub fn lab_reactor(&self) -> &Arc<LabReactor>

Returns a handle to the lab reactor for deterministic I/O injection.

pub fn trace(&self) -> &TraceBufferHandle

Returns a reference to the trace buffer handle.

pub fn detected_races(&self) -> RaceReport

Returns a race report derived from the current trace buffer.

pub fn chaos_stats(&self) -> &ChaosStats

Returns aggregated chaos statistics for both task-side and reactor-side injection.

pub fn certificate(&self) -> &ScheduleCertificate

Returns the schedule certificate for determinism verification.

pub fn has_replay_recording(&self) -> bool

Returns true if replay recording is enabled.

pub fn replay_recorder(&self) -> &TraceRecorder

Returns a reference to the replay recorder.

pub fn take_replay_trace(&mut self) -> Option<ReplayTrace>

Takes the replay trace, leaving an empty trace in place.

Returns None if recording is disabled.

pub fn finish_replay_trace(&mut self) -> Option<ReplayTrace>

Finishes recording and returns the replay trace.

This consumes the replay recorder. Returns None if recording is disabled.

pub fn has_chaos(&self) -> bool

Returns true if chaos injection is enabled.

pub fn is_quiescent(&self) -> bool

Returns true if the runtime is quiescent.

pub fn advance_time(&mut self, nanos: u64)

Advances virtual time by the given number of nanoseconds.

pub fn advance_time_to(&mut self, time: Time)

Advances time to the given absolute time.

If the target time is before the current time, logs an error and does nothing (time cannot go backward).

pub fn advance_to_next_timer(&mut self) -> usize

Advances virtual time to the next timer deadline.

If a timer is pending, advances time to its deadline, processes the expired timer(s), and returns the number of wakeups triggered. Returns 0 if no timers are pending.

pub fn next_timer_deadline(&self) -> Option<Time>

Returns the next timer deadline, if any timers are pending.

pub fn pending_timer_count(&self) -> usize

Returns the number of pending timers.

pub fn run_with_auto_advance(&mut self) -> VirtualTimeReport

Runs until quiescent, automatically advancing virtual time to pending timer or lab-reactor deadlines whenever all tasks are idle.

This enables “instant timeout testing”: a scenario that would take 24 hours of wall-clock time completes in <1 second because every sleep/timeout deadline is jumped to instantly.

The loop is:

1. Run until idle (no runnable tasks in scheduler).
2. If timers or lab-reactor events are pending, advance time to the next deadline → go to 1.
3. If no pending virtual deadlines and quiescent → done.

Returns a VirtualTimeReport with execution statistics.

pub fn pause_clock(&self)

Pauses the virtual clock, freezing time at the current value.

While paused, advance_time() and timer processing still work at the LabRuntime level (they update the runtime’s own virtual_time field), but the underlying VirtualClock visible to tasks via Cx::now() is frozen. This is useful for testing timeout detection: tasks that call Cx::now() will see time standing still while the runtime can still orchestrate scheduling.

pub fn resume_clock(&self)

Resumes a paused virtual clock.

pub fn is_clock_paused(&self) -> bool

Returns true if the virtual clock is currently paused.

pub fn inject_clock_skew(&mut self, skew_nanos: u64)

Injects a clock skew by jumping time forward by skew_nanos.

This simulates clock drift or NTP corrections. A warning is logged because large jumps may affect lease/timeout correctness.

pub fn run_until_quiescent(&mut self) -> u64

Runs until quiescent or max steps reached.

Returns the number of steps executed.

pub fn run_until_idle(&mut self) -> u64

Runs until there are no runnable tasks in the scheduler.

This is intentionally weaker than Self::run_until_quiescent:

• It does not require all tasks to complete.
• It does not require all obligations to be resolved.

Use this when a test wants to “poll once” until the system is idle (e.g. a task is blocked on a channel receive) without forcing full completion and drain.

pub fn run_until_quiescent_with_report(&mut self) -> LabRunReport

Runs until quiescent (or max_steps is reached) and returns a structured report.

pub fn report(&mut self) -> LabRunReport

Build a structured report for the current runtime state.

This does not advance execution.

pub fn run_until_quiescent_spork_report( &mut self, app: impl Into<String>, attachments: Vec<HarnessAttachmentRef>, ) -> SporkHarnessReport

Runs until quiescent (or max_steps is reached) and returns a Spork harness report.

pub fn spork_report( &mut self, app: impl Into<String>, attachments: Vec<HarnessAttachmentRef>, ) -> SporkHarnessReport

Build a Spork harness report for the current runtime state.

This does not advance execution.

pub fn build_crashpack_for_report( &self, run: &LabRunReport, ) -> Option<CrashPack>

Build an in-memory crashpack for a failing report.

Returns None for passing reports.

pub fn enable_deadline_monitoring(&mut self, config: MonitorConfig)

Enable deadline monitoring with the default warning handler.

pub fn enable_deadline_monitoring_with_handler<F>( &mut self, config: MonitorConfig, f: F, )

where F: Fn(DeadlineWarning) + Send + Sync + 'static,

Enable deadline monitoring with a custom warning handler.

pub fn deadline_monitor_mut(&mut self) -> Option<&mut DeadlineMonitor>

Returns a mutable reference to the deadline monitor, if enabled.

pub fn notify_cancellation_oracle_task_create( &mut self, task_id: TaskId, region_id: RegionId, )

Notifies the cancellation protocol oracle about runtime events.

pub fn notify_cancellation_oracle_region_create( &mut self, region_id: RegionId, parent: Option<RegionId>, )

Notifies the cancellation protocol oracle about region creation.

pub fn notify_cancellation_oracle_task_transition( &mut self, task_id: TaskId, from: &TaskState, to: &TaskState, )

Notifies the cancellation protocol oracle about task state transitions.

pub fn notify_cancellation_oracle_cancel_request( &mut self, task_id: TaskId, reason: CancelReason, )

Notifies the cancellation protocol oracle about cancel requests.

pub fn notify_cancellation_oracle_cancel_ack(&mut self, task_id: TaskId)

Notifies the cancellation protocol oracle about cancel acknowledgments.

pub fn notify_cancellation_oracle_task_poll(&mut self, task_id: TaskId)

Notifies the cancellation protocol oracle about task polling.

pub fn notify_cancellation_oracle_mask_enter(&mut self, task_id: TaskId)

Notifies the cancellation protocol oracle about mask entry.

pub fn notify_cancellation_oracle_mask_exit(&mut self, task_id: TaskId)

Notifies the cancellation protocol oracle about mask exit.

pub fn notify_cancellation_oracle_region_cancel( &mut self, region_id: RegionId, reason: CancelReason, )

Notifies the cancellation protocol oracle about region cancellation.

pub fn check_cancellation_protocol( &mut self, ) -> Result<(), CancellationProtocolViolation>

Checks the cancellation protocol oracle for violations and optionally enforces them.

pub fn step_for_test(&mut self)

Public wrapper for step() for use in tests.

This is useful for testing determinism across multiple step executions.

pub fn check_invariants(&mut self) -> Vec<InvariantViolation>

Checks invariants and returns any violations.

Trait Implementations

impl Debug for LabRuntime

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

Formats the value using the given formatter.