Crate ic_timers 

Observable and recovery-aware timer primitives for Internet Computer canisters.

ic-timers is a higher-level wrapper around ic-cdk-timers, which remains the provider that arms and clears platform timers. This crate adds bounded coordination, scheduling, and observation above it.

The runtime executes Once, after-completion, and pre-armed synchronous watchdog callbacks through one volatile canister-local registry. Consumers retain durable application authority and synchronously reconstruct retained registrations during their existing lifecycle hooks. Transient remove-on-stop callbacks use direct registration. Registration capabilities can observe exact armed provider-wakeup ownership without making snapshots or observations into scheduling authority. timer_inventory returns the epoch together with the complete ordered timer set, including for an initialized empty registry.

Structs

AfterCompletionContext

Delegated control capability scoped to one exact after-completion work attempt.

AfterCompletionRegistration

Opaque non-clone claim for one callback with configured after-completion recurrence.

MeasurementSummary

Saturating aggregate for one instruction measurement role.

MemoryPageExtent

Wasm and stable memory extents in 64 KiB pages at one instant.

MemoryPageSample

Page extents observed at the start and end of one normally completed callback.

MemoryPageSummary

Bounded page-extent observations for one callback role.

OnceContext

Delegated control capability scoped to one exact Once work attempt.

OnceRegistration

Opaque non-clone claim for one registered Once callback.

TimerCadence

Validated positive recurrence cadence.

TimerCompletion

Classified result of one returned consumer invocation.

TimerCounters

Epoch-local timer event counters.

TimerEpoch

Identity and start time of one runtime-local observation epoch.

TimerIdentity

Stable, low-cardinality identity for one logical canister timer.

TimerInventorySnapshot

Atomic provider-neutral snapshot of one complete canister-local inventory.

TimerObservabilitySnapshot

Epoch-scoped outcomes, counters, and performance for one timer.

TimerOutcomeSnapshot

Latest outcome and functional failure state for one timer.

TimerPerformance

Completed instruction and memory-page measurements split by callback role.

TimerRunResult

Ordinary callback result with one scheduling proposal.

TimerSnapshot

Canonical provider-neutral operator snapshot for one logical timer.

WatchdogAttemptSnapshot

One watchdog work attempt paired with an authoritative successor.

WatchdogContext

Delegated control capability scoped to one exact watchdog work attempt.

WatchdogRegistration

Opaque non-clone claim for one pre-armed watchdog callback.

WatchdogRunResult

Synchronous watchdog work result.

Enums

DeclarationLifetime

Whether a stopped declaration remains in the bounded registry.

InactiveReason

Why a declaration currently has no scheduled or running callback generation.

OrdinaryRuntimeStateSnapshot

Coherent ordinary timer state.

RegisterError

Failure to claim one canonical timer identity.

ScheduleError

Failure to represent a cadence or requested deadline.

TimerCompletionOutcome

Outcome of one callback that returned to the runtime.

TimerControlFailure

Typed terminal failure in pure timer control.

TimerDirective

Scheduling decision returned after one bounded ordinary invocation.

TimerDirectiveSnapshot

Portable representation of the latest ordinary scheduling directive.

TimerError

Failure from the canister-local timer runtime API.

TimerIdentityError

Invalid structured timer identity.

TimerIdentityField

The identity component whose validation failed.

TimerLastOutcome

Latest observed terminal event for one timer invocation.

TimerPolicy

Configured recurrence policy for one logical timer.

TimerProcessCondition

Operator-facing condition derived from coherent state and scheduling mode.

TimerReconcileState

Desired volatile scheduling state during synchronous lifecycle reconciliation.

TimerRegistrationStatus

Portable projection of provider callback-generation state.

TimerRuntimeStateSnapshot

Closed policy-specific runtime state.

TimerSchedule

Initial or explicit request for an ordinary timer deadline.

TimerSchedulingMode

Latest effective scheduling reason for a declaration.

WatchdogAttemptStatus

Status of the watchdog attempt paired with a committed successor.

WatchdogDecision

Watchdog decision after one synchronous bounded work attempt.

WatchdogRuntimeStateSnapshot

Coherent watchdog timer state.

Constants

MAX_TIMER_IDENTITY_COMPONENT_BYTES

Maximum encoded length of one timer identity component.

MAX_TIMER_REGISTRATIONS

Maximum declarations owned by one canonical registry.

Functions

consecutive_expected_failures

Return functional expected-failure state by identity without a full inventory.

initialize_runtime

Initialize the volatile canister-local runtime once for this Wasm instance.

reconcile_after_completion

Reconstruct or reconcile one after-completion declaration synchronously.

reconcile_once

Reconstruct or reconcile one Once declaration synchronously.

reconcile_watchdog

Reconstruct or reconcile one watchdog declaration synchronously.

register_after_completion

Register one asynchronous callback with configured after-completion recurrence.

register_once

Register one asynchronous Once callback without scheduling it.

register_watchdog

Register one synchronous pre-armed watchdog callback without scheduling it.

timer_inventory

Return one atomic bounded inventory with its volatile runtime epoch.

timer_snapshot

Return one coherent inert snapshot by identity.