pub struct StimulusEvent {
pub elapsed_ms: u64,
pub label: String,
pub op_kind: Option<String>,
pub detail: Option<String>,
pub total_iterations: Option<u64>,
pub step_index: Option<u16>,
pub is_terminal: bool,
pub is_step_end: bool,
}Expand description
A discrete event during scenario execution that may cause observable changes in scheduler behavior. Generated by step executors on the guest side and carried in the VM output alongside monitor samples.
Fields§
§elapsed_ms: u64Milliseconds since scenario start (guest monotonic clock).
label: StringHuman-readable label. Produced as "StepStart[k]" by
Self::from_wire (the 0-indexed scenario Step ordinal),
"ScenarioEnd" by Self::terminal, and the
"BASELINE"/"Step[k]" bucket label by the
phase_from_bucket placeholder. Test fixtures may carry any
label.
op_kind: Option<String>What kind of operation triggered this event.
detail: Option<String>Additional context (e.g. “4 cpus”, “cgroup=cg_0”).
total_iterations: Option<u64>Cumulative worker iterations at this event. Some(_) for every
event built from the wire (the wire counter is always present —
see Self::from_wire); Some(0) is a legitimate “no iterations
accumulated yet” value. None is reserved for synthetic or
placeholder events.
This raw boundary telemetry is not divided by elapsed_ms.
iteration_rate has one definition throughout ktstr:
iterations per delivered guest CPU-second from matching per-cgroup
phase carriers. Deriving another rate here would reintroduce a
host-contention-sensitive wall-throughput metric.
step_index: Option<u16>1-indexed scenario step this event belongs to (the same
encoding the bridge stamps: 1..=N for Step ordinals), or
None for non-step events (including the terminal scenario-end
boundary; see is_terminal). Carried explicitly from the wire
StimulusPayload.step_index so the periodic-capture phase
attribution can map a capture’s workload-relative boundary
offset onto the guest’s own step timeline without parsing the
human-readable label.
is_terminal: boolTrue only for the synthetic scenario-end boundary the eval
walker appends from the ScenarioEnd wire frame’s final
total_iterations. It is retained for raw timeline completeness and
legacy consumers, but is not a denominator for iteration_rate. It is
not a step start:
step_index is None so it seeds no crate::assert::PhaseBucket
(excluded from the step-start timeline), and Timeline::build
skips it when laying out phase boundaries so it never renders a
phantom trailing phase.
is_step_end: boolTrue for a per-step END event (decoded from a
crate::vmm::wire::MsgType::StepEnd frame via
Self::from_step_end). It carries the SAME 1-indexed
step_index as its StepStart and its step’s end-of-hold
total_iterations. It is not a step start, so Timeline::build
filters it out of its step-start list to avoid a phantom phase.
Implementations§
Source§impl StimulusEvent
impl StimulusEvent
Sourcepub fn from_wire(ev: &StimulusEvent) -> Self
pub fn from_wire(ev: &StimulusEvent) -> Self
Build a timeline event from a deserialized wire stimulus event.
Centralizes the wire→timeline mapping so the production eval path
(evaluate_vm_result) and out-of-tree consumers — post_vm
callbacks folding VmResult::stimulus_timeline() (which calls
this internally) through
crate::assert::build_phase_buckets_with_stimulus — produce
identical events. The wire step_index is the bridge 1-indexed
convention (Step[k] -> k + 1, BASELINE owns 0); the human
label renders the 0-indexed Scenario-Step ordinal
(step_index - 1) to match the PhaseBucket Step[k] labels,
while the step_index field keeps the 1-indexed wire value for
phase-bucket remap. total_iterations is carried verbatim as
Some(_): the wire field is a cumulative counter that is always
populated (the guest sums live worker iterations at every step
boundary), so 0 is a legitimate baseline reading — the first
step’s frame fires right after its workers spawn and may genuinely
read zero.
Sourcepub fn from_step_end(ev: &StimulusEvent) -> Self
pub fn from_step_end(ev: &StimulusEvent) -> Self
Build a per-step END event from a crate::vmm::wire::MsgType::StepEnd
frame (reuses the crate::vmm::wire::StimulusEvent wire body).
Carries the SAME 1-indexed step_index as the step’s StepStart
and the step’s end-of-hold total_iterations, with is_step_end
set. is_terminal is false (it is a real per-step boundary, not the
scenario-end terminal).
Sourcepub fn terminal(elapsed_ms: u64, total_iterations: u64) -> Self
pub fn terminal(elapsed_ms: u64, total_iterations: u64) -> Self
Build the synthetic terminal boundary event from the
ScenarioEnd wire frame’s final cumulative total_iterations
and scenario-relative elapsed_ms. Appended once, after every
per-step Self::from_wire event.
step_index is None (it is not a step start — it seeds no
crate::assert::PhaseBucket) and is_terminal is set so
Timeline::build treats it as a right boundary only, never a
phase. elapsed_ms is in the same guest-monotonic frame as the
step events (both come from scenario_start.elapsed()), so the
last-step duration is well-formed.
Sourcepub fn phase(&self) -> Option<Phase>
pub fn phase(&self) -> Option<Phase>
The scenario Phase this event belongs to,
or None for the terminal scenario-end boundary (which seeds no
phase). Use THIS — not the raw Self::step_index field — to key
per-phase lookups. step_index carries the bridge 1-indexed wire
convention (Step k -> Some(k + 1)) while label renders the
0-indexed k, so reading the field directly invites the 0-vs-1
off-by-one this method removes: it maps the wire value onto the same
Phase newtype the
ScenarioStats /
PhaseBucket accessors are keyed by
(Phase::step(k)). Step events carry step_index >= 1, so the
saturating_sub(1) is exact.
Trait Implementations§
Source§impl Clone for StimulusEvent
impl Clone for StimulusEvent
Source§fn clone(&self) -> StimulusEvent
fn clone(&self) -> StimulusEvent
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read moreSource§impl Debug for StimulusEvent
impl Debug for StimulusEvent
Source§impl<'de> Deserialize<'de> for StimulusEvent
impl<'de> Deserialize<'de> for StimulusEvent
Source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
Auto Trait Implementations§
impl Freeze for StimulusEvent
impl RefUnwindSafe for StimulusEvent
impl Send for StimulusEvent
impl Sync for StimulusEvent
impl Unpin for StimulusEvent
impl UnwindSafe for StimulusEvent
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more