ic_timers/snapshot/
model.rs

1//! Closed policy, state, outcome, and epoch values.
2
3use crate::schedule::{ScheduleError, TimerCadence, TimerDirective, duration_ns};
4
5/// Configured recurrence policy for one logical timer.
6#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
7pub enum TimerPolicy {
8    /// Run at most once unless an explicit directive or request schedules it.
9    Once,
10    /// Permit recurrence at a configured cadence after callback completion.
11    AfterCompletion {
12        /// Validated configured cadence.
13        cadence: TimerCadence,
14    },
15    /// Commit a successor before dispatching synchronous fallible work.
16    Watchdog {
17        /// Validated configured cadence.
18        cadence: TimerCadence,
19    },
20}
21
22impl TimerPolicy {
23    /// Return the stable configured-policy label.
24    #[must_use]
25    pub const fn label(self) -> &'static str {
26        match self {
27            Self::Once => "once",
28            Self::AfterCompletion { .. } => "after_completion",
29            Self::Watchdog { .. } => "watchdog",
30        }
31    }
32
33    /// Return a configured cadence when the policy recurs.
34    #[must_use]
35    pub const fn cadence(self) -> Option<TimerCadence> {
36        match self {
37            Self::Once => None,
38            Self::AfterCompletion { cadence } | Self::Watchdog { cadence } => Some(cadence),
39        }
40    }
41}
42
43/// Whether a stopped declaration remains in the bounded registry.
44#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
45pub enum DeclarationLifetime {
46    /// Keep callback authority available for a later ensure request.
47    Retained,
48    /// Remove the declaration after terminal completion or cancellation.
49    RemoveWhenStopped,
50}
51
52/// Latest effective scheduling reason for a declaration.
53///
54/// The value remains observable while inactive and is not itself evidence of
55/// an armed callback.
56#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
57pub enum TimerSchedulingMode {
58    /// An explicit relative-delay schedule, including initial one-shot work.
59    Once,
60    /// Recurrence delayed from the previous completion.
61    AfterCompletion,
62    /// An explicit absolute deadline.
63    Deadline,
64    /// A delayed retry following an expected failure.
65    Retry,
66    /// Immediate continuation of bounded work.
67    Continuation,
68    /// A successor committed before fallible watchdog work.
69    Watchdog,
70}
71
72impl TimerSchedulingMode {
73    /// Return a stable adapter-friendly label.
74    #[must_use]
75    pub const fn label(self) -> &'static str {
76        match self {
77            Self::Once => "once",
78            Self::AfterCompletion => "after_completion",
79            Self::Deadline => "deadline",
80            Self::Retry => "retry",
81            Self::Continuation => "continuation",
82            Self::Watchdog => "watchdog",
83        }
84    }
85}
86
87/// Portable representation of the effective ordinary scheduling directive
88/// after authoritative completion commands have been applied.
89#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
90pub enum TimerDirectiveSnapshot {
91    /// Stop after the completed invocation.
92    Stop,
93    /// Continue in the next available timer message.
94    ContinueImmediately,
95    /// Retry after a relative delay.
96    RetryAfter {
97        /// Requested delay in nanoseconds.
98        delay_ns: u64,
99    },
100    /// Schedule at one absolute IC timestamp.
101    ScheduleAt {
102        /// Absolute IC timestamp in nanoseconds.
103        deadline_ns: u64,
104    },
105    /// Recur using the registration's configured cadence.
106    RecurAfterCompletion,
107}
108
109impl TryFrom<TimerDirective> for TimerDirectiveSnapshot {
110    type Error = ScheduleError;
111
112    fn try_from(value: TimerDirective) -> Result<Self, Self::Error> {
113        Ok(match value {
114            TimerDirective::Stop => Self::Stop,
115            TimerDirective::ContinueImmediately => Self::ContinueImmediately,
116            TimerDirective::RetryAfter(delay) => Self::RetryAfter {
117                delay_ns: duration_ns(delay)?,
118            },
119            TimerDirective::ScheduleAt(deadline_ns) => Self::ScheduleAt { deadline_ns },
120            TimerDirective::RecurAfterCompletion => Self::RecurAfterCompletion,
121        })
122    }
123}
124
125/// Typed terminal failure in pure timer control.
126#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
127pub enum TimerControlFailure {
128    /// A callback generation counter reached its maximum.
129    GenerationExhausted,
130    /// Checked successor deadline arithmetic overflowed.
131    DeadlineOverflow,
132    /// A requested relative delay cannot be encoded as `u64` nanoseconds.
133    DelayOutOfRange,
134    /// A directive is not legal for the timer's configured policy.
135    DirectiveNotAllowed,
136    /// A checked registry effect could not establish canonical provider ownership.
137    ProviderBindingFailed,
138}
139
140impl TimerControlFailure {
141    /// Return a stable adapter-friendly label.
142    #[must_use]
143    pub const fn label(self) -> &'static str {
144        match self {
145            Self::GenerationExhausted => "generation_exhausted",
146            Self::DeadlineOverflow => "deadline_overflow",
147            Self::DelayOutOfRange => "delay_out_of_range",
148            Self::DirectiveNotAllowed => "directive_not_allowed",
149            Self::ProviderBindingFailed => "provider_binding_failed",
150        }
151    }
152}
153
154/// Why a declaration currently has no scheduled or running callback generation.
155#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
156pub enum InactiveReason {
157    /// The declaration has not yet been scheduled.
158    NeverScheduled,
159    /// Work returned a terminal stop decision.
160    Stopped,
161    /// Explicit cancellation won request arbitration.
162    Cancelled,
163    /// Consumer work reported an invariant or terminal failure.
164    InvariantFailure,
165    /// Checked pure control reached a terminal failure.
166    ControlFailure(TimerControlFailure),
167}
168
169/// Coherent ordinary timer state.
170#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
171pub enum OrdinaryRuntimeStateSnapshot {
172    /// One callback generation is scheduled.
173    Scheduled {
174        /// Generation the callback must present.
175        generation: u64,
176        /// Authoritative absolute deadline.
177        deadline_ns: u64,
178    },
179    /// One callback generation owns logical execution.
180    Running {
181        /// Generation owned by the running callback.
182        generation: u64,
183    },
184}
185
186/// Status of the watchdog attempt paired with a committed successor.
187#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
188pub enum WatchdogAttemptStatus {
189    /// The scheduler committed the work callback, which has not committed a start.
190    Dispatched,
191    /// The accepted work callback is currently executing synchronously.
192    Running,
193}
194
195/// One watchdog work attempt paired with an authoritative successor.
196#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
197pub struct WatchdogAttemptSnapshot {
198    generation: u64,
199    status: WatchdogAttemptStatus,
200}
201
202impl WatchdogAttemptSnapshot {
203    pub(crate) const fn new(generation: u64, status: WatchdogAttemptStatus) -> Self {
204        Self { generation, status }
205    }
206
207    /// Return the attempt generation.
208    #[must_use]
209    pub const fn generation(self) -> u64 {
210        self.generation
211    }
212
213    /// Return whether work is dispatched or running.
214    #[must_use]
215    pub const fn status(self) -> WatchdogAttemptStatus {
216        self.status
217    }
218}
219
220/// Coherent watchdog timer state.
221#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
222pub enum WatchdogRuntimeStateSnapshot {
223    /// One scheduler generation is authoritative and no work is outstanding.
224    Scheduled {
225        /// Generation the scheduler callback must present.
226        scheduler_generation: u64,
227        /// Authoritative absolute successor deadline.
228        deadline_ns: u64,
229    },
230    /// A successor is authoritative while one work attempt is outstanding.
231    AwaitingWork {
232        /// Generation the successor scheduler must present.
233        successor_generation: u64,
234        /// Absolute successor deadline.
235        successor_deadline_ns: u64,
236        /// The one paired work attempt.
237        attempt: WatchdogAttemptSnapshot,
238    },
239}
240
241/// Closed policy-specific runtime state.
242#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
243pub enum TimerRuntimeStateSnapshot {
244    /// The declaration has no scheduled or running callback generation.
245    Inactive {
246        /// Reason scheduling is inactive.
247        reason: InactiveReason,
248    },
249    /// State legal only for `Once` and `AfterCompletion`.
250    Ordinary(OrdinaryRuntimeStateSnapshot),
251    /// State legal only for `Watchdog`.
252    Watchdog(WatchdogRuntimeStateSnapshot),
253}
254
255impl TimerRuntimeStateSnapshot {
256    pub(crate) const fn next_deadline_ns(self) -> Option<u64> {
257        match self {
258            Self::Inactive { .. }
259            | Self::Ordinary(OrdinaryRuntimeStateSnapshot::Running { .. }) => None,
260            Self::Ordinary(OrdinaryRuntimeStateSnapshot::Scheduled { deadline_ns, .. })
261            | Self::Watchdog(WatchdogRuntimeStateSnapshot::Scheduled { deadline_ns, .. }) => {
262                Some(deadline_ns)
263            }
264            Self::Watchdog(WatchdogRuntimeStateSnapshot::AwaitingWork {
265                successor_deadline_ns,
266                ..
267            }) => Some(successor_deadline_ns),
268        }
269    }
270}
271
272/// Portable projection of provider callback-generation state.
273///
274/// This is independent of declaration lifetime: a retained declaration may
275/// report `Unregistered` while it keeps callback authority for a later ensure.
276#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
277pub enum TimerRegistrationStatus {
278    /// No callback generation is scheduled or running.
279    Unregistered,
280    /// A wake-up generation is authoritative and consumer work is not running.
281    Scheduled,
282    /// Consumer work currently owns logical execution.
283    Running,
284}
285
286impl TimerRegistrationStatus {
287    /// Return a stable adapter-friendly label.
288    #[must_use]
289    pub const fn label(self) -> &'static str {
290        match self {
291            Self::Unregistered => "unregistered",
292            Self::Scheduled => "scheduled",
293            Self::Running => "running",
294        }
295    }
296}
297
298impl From<TimerRuntimeStateSnapshot> for TimerRegistrationStatus {
299    fn from(value: TimerRuntimeStateSnapshot) -> Self {
300        match value {
301            TimerRuntimeStateSnapshot::Inactive { .. } => Self::Unregistered,
302            TimerRuntimeStateSnapshot::Ordinary(state) => match state {
303                OrdinaryRuntimeStateSnapshot::Scheduled { .. } => Self::Scheduled,
304                OrdinaryRuntimeStateSnapshot::Running { .. } => Self::Running,
305            },
306            TimerRuntimeStateSnapshot::Watchdog(state) => match state {
307                WatchdogRuntimeStateSnapshot::Scheduled { .. }
308                | WatchdogRuntimeStateSnapshot::AwaitingWork {
309                    attempt:
310                        WatchdogAttemptSnapshot {
311                            status: WatchdogAttemptStatus::Dispatched,
312                            ..
313                        },
314                    ..
315                } => Self::Scheduled,
316                WatchdogRuntimeStateSnapshot::AwaitingWork {
317                    attempt:
318                        WatchdogAttemptSnapshot {
319                            status: WatchdogAttemptStatus::Running,
320                            ..
321                        },
322                    ..
323                } => Self::Running,
324            },
325        }
326    }
327}
328
329/// Operator-facing condition derived from coherent state and scheduling mode.
330#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
331pub enum TimerProcessCondition {
332    /// Explicit cancellation disabled the current declaration.
333    Disabled,
334    /// Declared but without pending work.
335    Idle,
336    /// Scheduled or running normally.
337    Active,
338    /// Waiting for an expected retry.
339    Retrying,
340    /// Stopped by a reported failure or invalid control state.
341    Failed,
342}
343
344impl TimerProcessCondition {
345    /// Return a stable adapter-friendly label.
346    #[must_use]
347    pub const fn label(self) -> &'static str {
348        match self {
349            Self::Disabled => "disabled",
350            Self::Idle => "idle",
351            Self::Active => "active",
352            Self::Retrying => "retrying",
353            Self::Failed => "failed",
354        }
355    }
356}
357
358/// Outcome of one callback that returned to the runtime.
359#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
360pub enum TimerCompletionOutcome {
361    /// Callback completed useful work successfully.
362    Success,
363    /// Callback completed normally but found no work.
364    NoWork,
365    /// Expected failure permits retry policy.
366    RetryableFailure,
367    /// Unexpected invariant or terminal failure.
368    InvariantFailure,
369}
370
371impl TimerCompletionOutcome {
372    /// Return a stable adapter-friendly label.
373    #[must_use]
374    pub const fn label(self) -> &'static str {
375        match self {
376            Self::Success => "success",
377            Self::NoWork => "no_work",
378            Self::RetryableFailure => "retryable_failure",
379            Self::InvariantFailure => "invariant_failure",
380        }
381    }
382}
383
384/// Latest observed terminal event for one timer invocation.
385#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
386pub enum TimerLastOutcome {
387    /// One callback returned with a classified completion.
388    Completed(TimerCompletionOutcome),
389    /// A committed watchdog dispatch was retired without committed completion.
390    Unacknowledged,
391}
392
393/// Classified result of one returned consumer invocation.
394#[derive(Clone, Copy, Debug, Eq, PartialEq)]
395pub struct TimerCompletion {
396    outcome: TimerCompletionOutcome,
397    work_count: u64,
398}
399
400impl TimerCompletion {
401    /// Construct successful completed work.
402    #[must_use]
403    pub const fn success(work_count: u64) -> Self {
404        Self {
405            outcome: TimerCompletionOutcome::Success,
406            work_count,
407        }
408    }
409
410    /// Construct a valid no-work completion.
411    #[must_use]
412    pub const fn no_work() -> Self {
413        Self {
414            outcome: TimerCompletionOutcome::NoWork,
415            work_count: 0,
416        }
417    }
418
419    /// Construct an expected failure, retaining completed partial work.
420    #[must_use]
421    pub const fn retryable_failure(work_count: u64) -> Self {
422        Self {
423            outcome: TimerCompletionOutcome::RetryableFailure,
424            work_count,
425        }
426    }
427
428    /// Construct an invariant failure, retaining completed partial work.
429    #[must_use]
430    pub const fn invariant_failure(work_count: u64) -> Self {
431        Self {
432            outcome: TimerCompletionOutcome::InvariantFailure,
433            work_count,
434        }
435    }
436
437    /// Return the completion class.
438    #[must_use]
439    pub const fn outcome(self) -> TimerCompletionOutcome {
440        self.outcome
441    }
442
443    /// Return application work units reported by the consumer.
444    #[must_use]
445    pub const fn work_count(self) -> u64 {
446        self.work_count
447    }
448}
449
450/// Ordinary callback result with one scheduling proposal.
451///
452/// The registry validates proposals participating in scheduling against the
453/// configured policy. A winning exact reconciliation or terminal pending command
454/// discards the proposal before validation. Explicit invariant failure stops.
455#[derive(Clone, Copy, Debug, Eq, PartialEq)]
456pub struct TimerRunResult {
457    completion: TimerCompletion,
458    directive: TimerDirective,
459}
460
461impl TimerRunResult {
462    /// Construct a result, forcing invariant failures to stop.
463    #[must_use]
464    pub const fn new(completion: TimerCompletion, directive: TimerDirective) -> Self {
465        Self {
466            directive: if matches!(completion.outcome, TimerCompletionOutcome::InvariantFailure) {
467                TimerDirective::Stop
468            } else {
469                directive
470            },
471            completion,
472        }
473    }
474
475    /// Return the completion classification and work count.
476    #[must_use]
477    pub const fn completion(self) -> TimerCompletion {
478        self.completion
479    }
480
481    /// Return the post-run scheduling proposal.
482    #[must_use]
483    pub const fn directive(self) -> TimerDirective {
484        self.directive
485    }
486}
487
488/// Watchdog decision after one synchronous bounded work attempt.
489#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
490pub enum WatchdogDecision {
491    /// Retain the successor committed by the scheduler message.
492    Continue,
493    /// Move the committed successor to the current IC time.
494    ///
495    /// The replacement remains a later scheduler message; this never invokes
496    /// consumer work recursively in the current message.
497    ContinueImmediately,
498    /// Replace the committed successor with an exact absolute IC deadline.
499    ///
500    /// A past deadline schedules a later message with zero delay. If work
501    /// traps, this proposal rolls back and the cadence successor remains.
502    ScheduleAt(u64),
503    /// Terminate and clear the committed successor.
504    Stop,
505}
506
507/// Synchronous watchdog work result.
508#[derive(Clone, Copy, Debug, Eq, PartialEq)]
509pub struct WatchdogRunResult {
510    completion: TimerCompletion,
511    decision: WatchdogDecision,
512}
513
514impl WatchdogRunResult {
515    /// Construct a result, forcing invariant failures to stop.
516    #[must_use]
517    pub const fn new(completion: TimerCompletion, decision: WatchdogDecision) -> Self {
518        Self {
519            decision: if matches!(completion.outcome, TimerCompletionOutcome::InvariantFailure) {
520                WatchdogDecision::Stop
521            } else {
522                decision
523            },
524            completion,
525        }
526    }
527
528    /// Return the completion classification and work count.
529    #[must_use]
530    pub const fn completion(self) -> TimerCompletion {
531        self.completion
532    }
533
534    /// Return how the committed successor should be retained or cleared.
535    #[must_use]
536    pub const fn decision(self) -> WatchdogDecision {
537        self.decision
538    }
539}
540
541/// Latest outcome and functional failure state for one timer.
542#[derive(Clone, Copy, Debug, Eq, PartialEq)]
543pub struct TimerOutcomeSnapshot {
544    last_outcome: Option<TimerLastOutcome>,
545    last_work_count: Option<u64>,
546    last_success_at_ns: Option<u64>,
547    last_failure_at_ns: Option<u64>,
548    last_unacknowledged_at_ns: Option<u64>,
549    consecutive_expected_failures: u64,
550}
551
552impl TimerOutcomeSnapshot {
553    pub(crate) const EMPTY: Self = Self {
554        last_outcome: None,
555        last_work_count: None,
556        last_success_at_ns: None,
557        last_failure_at_ns: None,
558        last_unacknowledged_at_ns: None,
559        consecutive_expected_failures: 0,
560    };
561
562    pub(crate) const fn record_completion(
563        &mut self,
564        completion: TimerCompletion,
565        completed_at_ns: u64,
566    ) {
567        self.last_outcome = Some(TimerLastOutcome::Completed(completion.outcome));
568        self.last_work_count = Some(completion.work_count);
569        match completion.outcome {
570            TimerCompletionOutcome::Success | TimerCompletionOutcome::NoWork => {
571                self.last_success_at_ns = Some(completed_at_ns);
572                self.consecutive_expected_failures = 0;
573            }
574            TimerCompletionOutcome::RetryableFailure => {
575                self.last_failure_at_ns = Some(completed_at_ns);
576                self.consecutive_expected_failures =
577                    self.consecutive_expected_failures.saturating_add(1);
578            }
579            TimerCompletionOutcome::InvariantFailure => {
580                self.last_failure_at_ns = Some(completed_at_ns);
581                self.consecutive_expected_failures = 0;
582            }
583        }
584    }
585
586    pub(crate) const fn record_unacknowledged(&mut self, observed_at_ns: u64) {
587        self.last_outcome = Some(TimerLastOutcome::Unacknowledged);
588        self.last_work_count = None;
589        self.last_unacknowledged_at_ns = Some(observed_at_ns);
590    }
591
592    /// Return the latest terminal event.
593    #[must_use]
594    pub const fn last_outcome(self) -> Option<TimerLastOutcome> {
595        self.last_outcome
596    }
597
598    /// Return work reported by the latest completion.
599    #[must_use]
600    pub const fn last_work_count(self) -> Option<u64> {
601        self.last_work_count
602    }
603
604    /// Return the latest successful or valid no-work completion time.
605    #[must_use]
606    pub const fn last_success_at_ns(self) -> Option<u64> {
607        self.last_success_at_ns
608    }
609
610    /// Return the latest expected or invariant failure completion time.
611    #[must_use]
612    pub const fn last_failure_at_ns(self) -> Option<u64> {
613        self.last_failure_at_ns
614    }
615
616    /// Return when a dispatched watchdog attempt was most recently retired.
617    #[must_use]
618    pub const fn last_unacknowledged_at_ns(self) -> Option<u64> {
619        self.last_unacknowledged_at_ns
620    }
621
622    /// Return consecutive retryable failures since the latest reset outcome.
623    #[must_use]
624    pub const fn consecutive_expected_failures(self) -> u64 {
625        self.consecutive_expected_failures
626    }
627}
628
629/// Identity and start time of one runtime-local observation epoch.
630#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
631pub struct TimerEpoch {
632    canister_version: u64,
633    started_at_ns: u64,
634}
635
636impl TimerEpoch {
637    pub(crate) const fn new(canister_version: u64, started_at_ns: u64) -> Self {
638        Self {
639            canister_version,
640            started_at_ns,
641        }
642    }
643
644    /// Return the IC canister version that owns this volatile epoch.
645    #[must_use]
646    pub const fn canister_version(self) -> u64 {
647        self.canister_version
648    }
649
650    /// Return the IC timestamp at which the epoch began.
651    #[must_use]
652    pub const fn started_at_ns(self) -> u64 {
653        self.started_at_ns
654    }
655}
656
657#[cfg(test)]
658mod tests {
659    use super::*;
660
661    #[test]
662    fn expected_failure_streak_saturates() {
663        let mut outcomes = TimerOutcomeSnapshot {
664            consecutive_expected_failures: u64::MAX,
665            ..TimerOutcomeSnapshot::EMPTY
666        };
667
668        outcomes.record_completion(TimerCompletion::retryable_failure(0), 10);
669
670        assert_eq!(outcomes.consecutive_expected_failures(), u64::MAX);
671    }
672
673    #[test]
674    fn invariant_results_are_forced_to_stop() {
675        let ordinary = TimerRunResult::new(
676            TimerCompletion::invariant_failure(2),
677            TimerDirective::ContinueImmediately,
678        );
679        assert_eq!(ordinary.directive(), TimerDirective::Stop);
680
681        let watchdog = WatchdogRunResult::new(
682            TimerCompletion::invariant_failure(3),
683            WatchdogDecision::ContinueImmediately,
684        );
685        assert_eq!(watchdog.decision(), WatchdogDecision::Stop);
686    }
687}
ic_timers/snapshot/model.rs

ic_timers/snapshot/
model.rs
