Struct PreemptionWriter 

pub struct PreemptionWriter { /* private fields */ }

A writer for a stream of preemption events.

Implementations

impl PreemptionWriter

pub fn new(path: Option<PathBuf>) -> Self

A new, empty record of preemptions, with an optional location on disk that it will be written to. If no path is supplied, the results will accumulate in memory only.

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

Write the record in format (None for format 1): the newest (PREEMPTION_RECORD_FORMAT) for a run that follows no record, or the format of the record a replay follows, whose rules it ran by.

pub fn insert_time_skip(&mut self, skip: TimeSkip)

Record a jump of global time (PreemptionRecord::time_skips), which puts the record in format 2 at least (TIME_SKIPS_FORMAT).

pub fn stream_position(&self) -> u64

The position the next stored record takes in the recorded stream: where a jump made now falls (TimeSkip::event).

pub fn with_slice_boundaries(self) -> Result<Self, String>

Select the explicit boundary protocol before recording any global event. Metadata stays in the legacy history, with exactly one global stream in the new envelope. Existing writers remain legacy by default.

pub fn records_slice_boundaries(&self) -> bool

Whether this writer must retain the complete versioned boundary stream.

pub fn with_epoch(self, epoch: DateTime<Utc>) -> Self

Store the virtual-time epoch the recorded logical times are measured from, so a replay can start its clock at the same instant.

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

Store the run’s --pipe-wake-latency (None for off, which leaves the record as it was before the field existed).

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

Store whether the run kept the signal-state copy (Config::signal_state_copy).

pub fn with_rng_seed(self, rng_seed: u64) -> Self

Store the seed of the guest’s randomness, so a replay can hand the guest the same values.

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

Store whether the run charged a run of expired timed waits one turn (Scheduler::expired_wait_runs_charged_once; false leaves the record as it was before the field existed).

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

Store whether the run capped preemption charges (--cap-preemption-charge; off leaves the record as it was before the field existed).

pub fn set_host_inputs(&mut self, inputs: HostInputSet)

Store the host files the run’s guest opened, once the run has ended and before the record is flushed.

pub fn record_store_exclusive_failures(&mut self, failures: u64)

Store the store-exclusives that failed in the run (aarch64), counted once every thread has exited.

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

Store the --max-timeslice the run drew under --chaos-timeslice-draw=run (Config::chaos_timeslice; None writes nothing).

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

Store how the run numbered its guest (Config::guest_ids), unless its PID namespace did, which leaves the record as it was before the field existed.

pub fn set_guest_ids(&mut self, ids: GuestIds)

Self::with_guest_ids on a writer in use: a run whose guest got a host ID after all states GuestIds::Host.

pub fn is_empty(&self) -> bool

Does the record have zero entries?

pub fn len(&self) -> usize

Total number of elements in the record, across all threads.

pub fn register_thread(&mut self, tid: DetTid, prio: Priority)

Register a thread with its default/final priority.

pub fn insert_reprioritization( &mut self, tid: DetTid, time: LogicalTime, rcbs: u64, prior_prio: Priority, next_prio: Priority, )

Insert a new preemption point for the given thread. It must monotonically increase in time.

For now it (redundantly) takes both the priority of the timeslice just finished, and the next one coming up. This serves as a sanity check.

pub fn mark_replay_departed(&mut self, event: u64)

Mark this record as written by a preemption replay that left a change point out of it, first at global event count event (PreemptionRecord::replay_departed_at). Warns once, naming the file, so nobody replays it as an exact record.

pub fn last_reprioritization_time(&self, tid: DetTid) -> Option<LogicalTime>

The time of the last change point recorded for tid, if any. A new one must be strictly later (Self::insert_reprioritization).

pub fn insert_chaos_epoch( &mut self, tid: DetTid, transition: ChaosEpochTransition, )

Record a deterministic slowdown epoch transition for replay.

pub fn insert_schedevent(&mut self, ev: SchedEvent)

Add a SchedEvent to the global log of thread behavior.

pub fn insert_slice_boundary( &mut self, boundary: Boundary, ) -> Result<usize, String>

Append the observation of an existing slice-end request at its exact stream position. Refuse use with a legacy writer rather than silently dropping the boundary. Full stream ordering is checked before output.

pub fn set_current(&mut self, tid: DetTid, new_prio: Priority)

Set the priority of the current thread after a change.

pub fn into_string(self) -> String

Abort writing to disk and instead gather the output thusfar into a string.

pub fn flush(self) -> Result<(), String>

Finish any IO necessary to flush the record to disk. This will also happen automatically on drop.

Trait Implementations

impl Debug for PreemptionWriter

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

Formats the value using the given formatter.

impl Drop for PreemptionWriter

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.