swactor-development-history/cfuzz/CYCLE_10_TIMERS.md

Cycle 10: Per-Worker Tick-Counting Timers — Development History

Commit: d58a999 · 5 files · 247 insertions, 5 deletions

---

Motivation

Actors often need to schedule delayed or periodic work (timeouts, heartbeats, polling intervals). Before this change, swactor had no timer mechanism — actors had to manually count ticks or rely on external scheduling. The synchronous tick model makes wall-clock timers inappropriate, but tick-counting timers are a natural fit and provide deterministic behavior.

Competitor Analysis

Framework	Timer Model	Deterministic?
Erlang	timer:send_after, erlang:start_timer (wall-clock ms)	No
Akka	scheduleOnce, scheduler (wall-clock duration)	No
Actix	ctx.run_later, ctx.run_interval (wall-clock)	No
Kameo	tokio::time::sleep (wall-clock)	No
Tokio	tokio::time (wall-clock, pausable for testing)	With time::pause()
Go	time.After, time.NewTicker (wall-clock)	No
Swactor	Tick-counting	Yes — fully deterministic

Key Insight

Swactor's synchronous tick model makes tick-counting timers uniquely valuable: a timer scheduled for "5 ticks from now" fires at exactly tick N+5, regardless of wall-clock speed. This makes timer behavior reproducible in tests and simulations — something no other framework provides natively.

Also researched but rejected: priority messages (lifecycle hooks from Cycle 9 cover 95% of use cases) and SmallBox optimization (deferred: measure allocation cost first before adding unsafe code).

Implementation

Timer Types

• OnceTimer — fire once at fire_at tick, consumed after firing
• IntervalTimer — fire every period ticks, message cloned via CloneMsg trait

Timer Infrastructure

• CloneMsg trait — type-erased clone for interval timer messages (blanket impl for Message + Clone)
• TimerRequest enum: Once { dest, msg, ticks } | Interval { dest, msg, period }
• Per-worker TimerWheel — stores pending timers, checked each tick

Integration into tick_once

• Phase 2.5: Fire due timers, route through full delivery system (pool.deliver for local actors, transfer_txs for cross-worker, inbox_registry for inboxes)
• Phase 5.5: Drain timer requests from handler buffer into TimerWheel
• After cleanup_dead: GC interval timers for dead actors

API

• ctx.send_after_ticks(addr, msg, ticks) — one-shot timer
• ctx.send_interval_ticks(addr, msg, period) — interval timer
• Runtime::schedule_timer() — no-op with warning (timers are per-worker only, must be scheduled from within a handler)

Key files modified: src/actor.rs, src/worker.rs, src/runtime.rs, src/delivery.rs, tests/runtime_api.rs

Design Decisions

• Tick-counting, not wall-clock — deterministic behavior is a core swactor advantage. Wall-clock timers would break test reproducibility and simulation fidelity.
• Per-worker timer wheel — timers are local to the worker that owns the actor. No cross-worker synchronization needed. Timer routing uses the same delivery system as regular messages.
• CloneMsg trait — interval timers need to clone the message for each firing. A blanket impl covers all Message + Clone types, so users don't need to implement anything extra.
• Timer GC for dead actors — interval timers must be cleaned up when their target actor dies, otherwise they fire forever into the void.

Bug Fixed

gc_dead_intervals was initially over-aggressive — it removed timers for ANY address not in the local pool, including inboxes and cross-worker actors. Fixed to only GC timers for addresses in the dead set from cleanup_dead.

Tests Added

6 new tests (82 → 88 total):

• one_shot_timer_fires_after_n_ticks — timer with delay=3 fires on tick 4
• handler_can_schedule_one_shot_timer — timer scheduled from within a handler fires correctly
• one_shot_timer_fires_only_once — consumed after firing, doesn't repeat
• interval_timer_fires_repeatedly — period=2, fires every 2 ticks (3 firings verified)
• interval_timer_cleaned_up_when_actor_dies — GC removes orphaned interval timers
• timer_with_zero_delay_fires_next_tick — delay=0 fires on next tick (not same tick)

Result

• 88 tests pass
• All workspace crates compile
• Bug found and fixed: over-aggressive timer GC for cross-worker addresses