ic_timers/snapshot/
mod.rs

1//! Provider-neutral timer identity and canonical snapshot values.
2//!
3//! This module defines the 0.2 observability contract without owning registry
4//! storage, callback execution, platform effects, or consumer serialization.
5
6mod identity;
7mod metrics;
8mod model;
9
10pub use identity::{
11    MAX_TIMER_LABEL_BYTES, TimerIdentity, TimerIdentityError, TimerIdentityField, TimerLabel,
12    TimerLabelError,
13};
14pub use metrics::{
15    MeasurementSummary, TimerCounters, TimerMeasurement, TimerObservabilitySnapshot,
16    TimerPerformance,
17};
18pub use model::{
19    PreArmedSuccessor, TimerCompletion, TimerCompletionOutcome, TimerDirectiveSnapshot, TimerEpoch,
20    TimerLastOutcome, TimerOutcomeSnapshot, TimerPolicy, TimerProcessCondition,
21    TimerRegistrationStatus, TimerSchedulingMode, TimerSchedulingSnapshot, TimerStateSnapshot,
22};
23
24/// Canonical provider-neutral operator snapshot for one logical timer.
25#[derive(Clone, Debug, Eq, PartialEq)]
26pub struct TimerSnapshot {
27    /// Stable structured identity used for lookup and deterministic inventory ordering.
28    pub identity: TimerIdentity,
29    /// Configured policy and authoritative scheduling details.
30    pub scheduling: TimerSchedulingSnapshot,
31    /// Current logical and operator-facing state.
32    pub state: TimerStateSnapshot,
33    /// Epoch-scoped outcomes, counters, measurements, and functional failure streak.
34    pub observability: TimerObservabilitySnapshot,
35}
36
37impl TimerSnapshot {
38    /// Construct an unregistered timer snapshot for one observation epoch.
39    #[must_use]
40    pub fn new(identity: TimerIdentity, policy: TimerPolicy, epoch: TimerEpoch) -> Self {
41        Self {
42            identity,
43            scheduling: TimerSchedulingSnapshot::new(policy),
44            state: TimerStateSnapshot {
45                enabled: true,
46                registration: TimerRegistrationStatus::Unregistered,
47                condition: TimerProcessCondition::Idle,
48                generation: 0,
49                in_flight: false,
50            },
51            observability: TimerObservabilitySnapshot::new(epoch),
52        }
53    }
54
55    /// Return recovery-sensitive expected-failure state for this timer.
56    ///
57    /// A registry can expose this after one ordered lookup by `identity`;
58    /// callers do not need to scan counters or rebuild an adapter snapshot.
59    #[must_use]
60    pub const fn consecutive_expected_failures(&self) -> u64 {
61        self.observability.consecutive_expected_failures()
62    }
63}
64
65#[cfg(test)]
66mod tests;
ic_timers/snapshot/mod.rs

ic_timers/snapshot/
mod.rs
