Struct PreemptionRecord 

pub struct PreemptionRecord { /* private fields */ }

A record of all the preemptions and other scheduling events that occur during execution.

Implementations

impl PreemptionRecord

pub fn with_reserved_input(self, metadata: ReservedInputMetadata) -> Self

Preserve the source’s optional metadata on an edit. This is not a live producer certificate; unmarked/unknown input remains unmarked/unknown.

pub fn reserved_input(&self) -> &ReservedInputMetadata

The exact optional standalone JSON metadata, without interpreting it.

pub fn validate_replay_inputs( &self, source: &str, guest_ids: GuestIds, ) -> Result<(), RecordAdmissionRefusal>

Reconcile numbering and private-input provenance on the complete decoded record that an authoritative replay loader will install.

pub fn validate_combined_reserved_inputs( &self, other: &Self, ) -> Result<(), RecordAdmissionRefusal>

Validate a combination before any endpoint or identity shortcut. A Chosen input requires the same recognized descriptor on every source. Non-Chosen edits retain their former admission and opaque metadata.

impl PreemptionRecord

pub fn from_sched_events(events: Vec<SchedEvent>) -> Self

TODO: This is not ideal because PreemptionRecord shouldn’t be doing double duty as an eventlog.

pub fn expired_wait_runs_charged_once(&self) -> bool

Whether the run this record came from charged a run of expired timed waits one turn (false for each wait charged, and for records that do not say).

pub fn with_expired_wait_runs_charged_once(self, once: bool) -> Self

The same record, stating how the run it came from charged runs of expired timed waits.

pub fn schedule_prefix(&self, len: usize) -> PreemptionRecord

The record a replay of only the first len scheduled events of this one follows: those events, and the callback checkpoints they reach.

A checkpoint names the callback that ended one of a thread’s slices and the thread’s progress there (the sum of its events’ counts, as replay counts it, callback_history::Progress). The checkpoints of threads the prefix runs, up to the progress each thread reaches in it, end the prefix’s slices where the recording did, so a replay of the prefix keeps the software-expiry turns they mark. A schedule replayed without them has no record of those turns, and its virtual time drifts from the recording’s. The scheduler runs freely after the prefix, so later checkpoints are dropped, and so are those of threads the prefix does not run, progress-0 ones included.

Progress alone places a checkpoint, so one taken at exactly the progress a thread reaches at the prefix end is kept: it ended the thread’s last slice in the prefix. Another one at the same progress, from a later callback of the same handler after other threads ran past the prefix, is kept too, and the replay applies it only when its recorded time and branch count are reached.

The thread that runs the prefix’s last event is the exception while another event follows: its checkpoints at the progress that event reaches end its slice at the prefix’s own end, which decides what runs next, so they belong to the event after the prefix and are dropped. A replay of the prefix then lets that thread run on, as it does past any event the prefix leaves out. A prefix of the whole schedule keeps the record’s checkpoints.

The per-thread histories stay whole, for the rows the checkpoints name; a schedule replay reads only the events and the checkpoints.

pub fn with_schedule(&self, events: Vec<SchedEvent>) -> Option<PreemptionRecord>

The same record with events as its schedule, or None if its callback checkpoints do not fit those events (see Self::validate). For a schedule that replayed this record’s events and went on past them: its own recording keeps no checkpoints, since a replay records none, but the replayed part ended its slices where this record did.

pub fn interpolate_events( &self, other: &Self, events: Vec<SchedEvent>, ) -> Result<Self, String>

Attach the metadata of two interpolation inputs to events.

The caller first reconciles the existing guest-ID, signal-copy and other option policies. An exact source schedule keeps that source’s complete record, including callback checkpoints and time jumps. Both formats must agree: a single output cannot follow two charging rules.

A genuinely mixed order has no established mapping for either source’s jumps or checkpoints, so refuse those inputs. For jump/checkpoint-free inputs, every remaining metadata field must agree. Keep those fields, but clear the per-thread priority histories, as an event-order edit follows its global stream rather than either original priority history. Host-observed failure counts must agree too; retain their warning, without claiming that an unrun edit has measured that many failures.

pub fn chaos_timeslice(&self) -> Option<u64>

The --max-timeslice the run that produced this record drew under --chaos-timeslice-draw=run, if it drew one.

pub fn with_chaos_timeslice(self, timeslice: Option<u64>) -> Self

The same record, stating the timeslice its run drew.

pub fn with_time_skips(self, skips: Vec<TimeSkip>) -> Self

The same record, listing skips as its jumps of global time, in format 2 at least when there are any. Analyze and bisect carry a source record’s jumps into a trial schedule spliced from its prefix.

pub fn with_current_format(self) -> Self

The same record in the newest format (PREEMPTION_RECORD_FORMAT), which a record from a run of this Hermit has.

pub fn with_format(self, format: Option<u32>) -> Self

The same record in format (None for format 1). Analyze and bisect require one shared timing format across the recordings they read (hermit-cli’s time_skip_carry).

pub fn format_version(&self) -> Option<u32>

The record’s format: None for format 1.

pub fn charges_replayed_switch_ins(&self) -> bool

Whether a schedule replay of this record charges a replayed switch-in under which guest code runs (format 3 or later, SWITCH_IN_CHARGE_FORMAT).

pub fn lists_its_time_skips(&self) -> bool

Whether the record lists every jump of global time its run made (format 2 or later), so that a replay makes exactly those.

pub fn with_pipe_wake_latency(self, latency: Option<u64>) -> Self

The same record, stating the --pipe-wake-latency of the trials it came from. Every record analyze, minimize or bisect writes from trials carries it, so that a replay under another value is refused.

pub fn pipe_wake_latency(&self) -> Option<u64>

The --pipe-wake-latency this record was produced under (None for off).

pub fn epoch(&self) -> Option<DateTime<Utc>>

The virtual-time epoch this record was produced under, if it was stored.

pub fn signal_state_copy(&self) -> Option<bool>

Whether the signal-state copy was on in the run this record came from, if the record says.

pub fn host_inputs(&self) -> Option<&HostInputSet>

The host files the recorded run’s guest opened, if the record says.

pub fn store_exclusive_failures(&self) -> u64

The store-exclusives that failed in the run this record came from (zero where none were counted).

pub fn replay_departed_at(&self) -> Option<u64>

A retained source event count where a replay omitted a change point. After transformations it need not index this record’s global events.

pub fn require_faithful_replay(&self) -> Result<()>

Refuse a known omission before replay or analysis can certify it. Unmarked legacy records retain their existing admission policy; their absence of this field is not proof of historical completeness.

pub fn retain_replay_departure(self, source: Option<u64>) -> Self

Retain an omission observed in a source record, never clearing one. When sources differ, the smaller count is only a retained source observation: it is neither a common causal order nor an event index in a transformed output. Admission depends only on its presence.

pub fn with_signal_state_copy(self, on: Option<bool>) -> Self

The same record, stating whether the copy was on in the trials it came from (None for unknown). Every record analyze, minimize or bisect writes from trials carries it, as it carries the pipe-wake latency.

pub fn with_cap_preemption_charge(self, on: bool) -> Self

The same record, stating whether the trials it came from capped preemption charges, as it states the pipe-wake latency.

pub fn cap_preemption_charge(&self) -> bool

Whether this record was produced under --cap-preemption-charge.

pub fn guest_ids(&self) -> Option<GuestIds>

How the run this record came from numbered its guest, if no PID namespace of its own did.

pub fn with_guest_ids(self, ids: GuestIds) -> Self

The same record, retaining the guest numbering of schedules used to construct it. Namespace numbering keeps the legacy omitted field.

pub fn extract_all(&self) -> BTreeMap<DetTid, ThreadHistory>

Make a copy of everything in the PreemptionRecord in a public format.

pub fn as_vecs(&self) -> BTreeMap<DetTid, Vec<(LogicalTime, Priority)>>

Inverse of from_vecs.

pub fn strip_contents(self) -> Self

TODO: provide a better way to create an empty PreemptionRecord but with entries for a given set of tids.

pub fn split_map<F, R>(&mut self, splitter: F)

where R: IntoIterator<Item = SchedEvent>, F: Fn(SchedEvent, &ReplayCursor<SchedEvent>) -> R,

Iterates over each sched event and applies function event -> *event yielding resulting iterator as new events This effectively moves content of global allowing to split or delete events based on the function provided

pub fn schedevents_iter_mut(&mut self) -> IterMut<'_, SchedEvent>

Iterate over the schedevents.

pub fn preemptions_only(&mut self)

Leave only the per-thread preemption records, not the global schedule.

pub fn clone_preemptions_only(&self) -> Self

Make a copy just of the preemptions (cheap) rather than the whole schedule trace (expensive)

pub fn schedevents(&self) -> &Vec<SchedEvent>

Read-only access to the raw event schedule.

pub fn contains_schedevents(&self) -> bool

Returns true if the schedule trace (SchedEvent) record is nonempty.

pub fn from_vecs(bt: &BTreeMap<DetTid, Vec<(LogicalTime, Priority)>>) -> Self

Convert from a flat vector representation (Time,Priority_AFTER_Time) into the internal representation. The very first timeslice should have a zero timestamp, but it is ignored if nonzero.

pub fn time_skips(&self) -> Option<&[TimeSkip]>

The jumps of global time the recorder saw (time_skips), or None when the record does not say.

pub fn into_global(self) -> Vec<SchedEvent>

Extracts the inner global events.

pub fn write_to_disk(&self, path: &Path) -> Result<(), String>

Save to disk.

pub fn validate(&self) -> Result<(), String>

Perform internal invariant checks on the PreemptionRecord and return an error if it is not well formed.

pub fn validate_contents(&self) -> Result<(), String>

Check everything Self::validate does but the format (Self::validate_format), whose failure is a refusal rather than a malformed record, and which readers check separately for that reason.

pub fn validate_format(&self) -> Result<(), String>

Check the record’s format and its jumps of global time: a format this Hermit reads, with the list that format requires, in stream order, to later and finite deadlines. A failure is a refusal of the record, not a malformed file (RecordFormatRefusal).

pub fn normalize(&self) -> PreemptionRecord

Normalize priorities for readibility.

pub fn with_latest_preempt_removed(&self) -> PreemptionRecord

Remove whichever is the latest preemption across all thread histories. If there are no priority changes in any thread history, the entire last thread (highest thread number) is completely removed. Note this function assumes the last priority change in the list has the latest preempt time.

Trait Implementations

impl Clone for PreemptionRecord

fn clone(&self) -> PreemptionRecord

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PreemptionRecord

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

Formats the value using the given formatter.

impl Default for PreemptionRecord

fn default() -> PreemptionRecord

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for PreemptionRecord

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Display for PreemptionRecord

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

Formats the value using the given formatter.

impl Eq for PreemptionRecord

impl Hash for PreemptionRecord

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for PreemptionRecord

fn eq(&self, other: &PreemptionRecord) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for PreemptionRecord

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for PreemptionRecord