ic_timers/
lib.rs

1//! Observable and recovery-aware timer primitives for Internet Computer
2//! canisters.
3//!
4//! The private one-shot backend owns IC timer dispatch and cancellation. The
5//! selected CDK executor owns async polling and call-context cleanup; this crate
6//! owns bounded coordination, scheduling, and observation.
7//!
8//! The runtime executes `Once`, after-completion, and pre-armed synchronous
9//! watchdog callbacks through one volatile canister-local registry.
10//! Consumers retain durable application authority and synchronously reconstruct
11//! retained registrations during their existing lifecycle hooks. Transient
12//! remove-on-stop callbacks use direct registration with an initial schedule.
13//! Direct registration returns scheduled authority only after provider binding;
14//! only retained declarations may start inactive. [`TimerStart`] selects
15//! retention together with the initial schedule. Registration capabilities can
16//! observe exact armed provider-wakeup ownership without making snapshots
17//! or observations into scheduling authority.
18//! [`timer_inventory`] returns the epoch together with the complete ordered
19//! timer set, including for an initialized empty registry.
20
21#![deny(unsafe_code)]
22#![forbid(private_interfaces)]
23#![deny(rustdoc::broken_intra_doc_links)]
24#[forbid(unsafe_code)]
25mod callback;
26#[forbid(unsafe_code)]
27mod control;
28mod platform;
29#[forbid(unsafe_code)]
30mod registry;
31#[forbid(unsafe_code)]
32mod runtime;
33#[forbid(unsafe_code)]
34mod schedule;
35#[forbid(unsafe_code)]
36mod snapshot;
37
38pub use callback::{
39    AfterCompletionDecision, AfterCompletionRunResult, OnceDecision, OnceRunResult,
40};
41pub use registry::{MAX_TIMER_REGISTRATIONS, RegisterError};
42pub use runtime::{
43    AfterCompletionContext, AfterCompletionRegistration, OnceContext, OnceRegistration, TimerError,
44    TimerReconcileState, TimerStart, WatchdogContext, WatchdogReconcileState, WatchdogRegistration,
45    consecutive_expected_failures, initialize_runtime, reconcile_after_completion, reconcile_once,
46    reconcile_watchdog, register_after_completion, register_once, register_watchdog,
47    timer_inventory, timer_snapshot,
48};
49pub use schedule::{ScheduleError, TimerCadence, TimerSchedule};
50pub use snapshot::{
51    DeclarationLifetime, InactiveReason, MAX_TIMER_IDENTITY_COMPONENT_BYTES, MeasurementCounter,
52    MeasurementSummary, MemoryPageExtent, MemoryPageSample, MemoryPageSummary,
53    OrdinaryRuntimeStateSnapshot, TimerCompletion, TimerCompletionOutcome, TimerControlFailure,
54    TimerCounters, TimerDirectiveSnapshot, TimerEpoch, TimerIdentity, TimerIdentityError,
55    TimerIdentityField, TimerInventorySnapshot, TimerLastOutcome, TimerObservabilitySnapshot,
56    TimerOutcomeSnapshot, TimerPerformance, TimerPolicy, TimerRegistrationId,
57    TimerRegistrationStatus, TimerRuntimeStateSnapshot, TimerSchedulingMode, TimerSnapshot,
58    WatchdogAttemptStatus, WatchdogDecision, WatchdogRunResult, WatchdogRuntimeStateSnapshot,
59};
ic_timers/lib.rs

ic_timers/
lib.rs
