# 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