Module timer 

Tokio-based timer substrate for deferred emissions.

Feature-gated behind tokio. Core’s dispatcher stays fully synchronous; this module provides a minimal async boundary for timer scheduling.

Design (2026-05-11)

Timer-dependent operators (debounce, throttle, delay, audit) and infrastructure consumers (storage debounce_ms) need to schedule deferred work — “emit this handle in 50ms” or “flush after 200ms of quiet.” These are async concerns that Core’s sync dispatcher can’t own directly.

The substrate provides:

• TimerTaskHandle — command channel from sync code to a tokio task. Non-blocking send; drop-to-shutdown.
• spawn_timer_task — spawns a tokio task that manages tagged timer slots for one node, wires the channel, returns the handle.

Operators send TimerCmd from their sync fn-fire to schedule, cancel, or cancel-all timers. The task manages deadlines via tokio::time and, when a timer fires, posts an Emit request to the cross-thread Arc<CoreMailbox> (D223/D227/D230). The owner drains the mailbox via Core::drain_mailbox, applying each emit via the sync Core::emit. Under S2c/D248 single-owner Core this is the only cross-thread bridge into the otherwise !Send Core; the prior partition wave_owner serialization machinery is deleted (one owner thread, no cross-thread interleaving wave to serialize).

Timer sources (fromTimer, interval) use the producer substrate + this module: the producer’s build closure spawns a timer task on activation; deactivation drops the handle, shutting down the task.

Testing

Use tokio::time::pause() + tokio::time::advance() for deterministic timer control in tests. No mock infrastructure needed.

Structs

TimerTaskHandle

Handle to a running timer task. Dropping this shuts down the task.

Enums

TimerCmd

Command sent from the operator fn (sync) to the timer task (async).

Functions

spawn_timer_task

Spawn a timer task for a single operator/source node.

Type Aliases

TimerCallback

Callback invoked when a timer fires. Runs on the tokio task thread. Must not block or hold locks across Core::emit.

TimerSender

Sender half — stored in the operator’s scratch for sync command dispatch.