runact 1.3.3

A Rust-native actor runtime with BEAM-style processes
Documentation
# Timers

## Overview

Timers deliver messages to actors on a schedule. Runact supports one-shot timers and periodic timers with drift correction.

## One-Shot Timer

Send a message after a delay:

```rust
use std::time::Duration;

// From outside an actor:
runtime.schedule_timer(
    Duration::from_secs(5),
    actor_id,
    "wake up".to_string(),
);

// From inside an actor:
ctx.schedule_timer(Duration::from_millis(500), "ping".to_string())
    .map_err(|e| ActorError::Handler(e.to_string()))?;
```

## Periodic Timer

Send a message repeatedly at intervals:

```rust
// From outside an actor:
runtime.schedule_interval(
    Duration::from_secs(1),
    actor_id,
    Tick,  // Must be Clone + Send + Sync
);

// From inside an actor:
ctx.schedule_interval(Duration::from_secs(1), Tick)
    .map_err(|e| ActorError::Handler(e.to_string()))?;
```

The message must implement `Clone + Send + Sync` because it is cloned for each tick.

## Drift Correction

Periodic timers use scheduled-at-based rescheduling to avoid drift:

```rust
// Instead of: scheduled_at = now + interval  (drifts over time)
// Runact uses: scheduled_at = previous_scheduled_at + interval  (no drift)
```

This means intervals stay accurate even if message handling takes time.

## Cancelling Timers

```rust
use runact::TimerId;

let timer_id = ctx.schedule_timer(Duration::from_secs(10), "delayed".to_string())
    .map_err(|e| ActorError::Handler(e.to_string()))?;

// Later, cancel it:
ctx.cancel_timer(timer_id);
```

Or from outside:

```rust
let timer_id = runtime.schedule_timer(Duration::from_secs(10), actor_id, "delayed".to_string());
runtime.cancel_timer(timer_id);
```

## Handling Timer Messages

Timer messages arrive as regular actor messages. Use an enum variant to distinguish them:

```rust
enum AppMsg {
    Tick,
    UserInput(String),
}

impl Actor for App {
    type Message = AppMsg;

    fn handle(&mut self, msg: AppMsg, ctx: &mut ActorContext) -> Result<(), ActorError> {
        match msg {
            AppMsg::Tick => {
                // Periodic work
                self.update();
            }
            AppMsg::UserInput(input) => {
                // Handle input
            }
        }
        Ok(())
    }
}
```

## TimerId

Each timer gets a unique `TimerId` that can be used for cancellation:

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct TimerId(u64);
```

## Timer Implementation

Runact's timer service runs on a dedicated thread that polls scheduled timers every 1ms:

- One-shot timers fire once, then are removed
- Periodic timers fire at intervals, rescheduled based on previous scheduled time (drift correction)
- Timer messages are sent directly to the actor's mailbox via `MessageEnvelope::Message`
- Cancellation removes the timer entry from the timer list

## Best Practices

1. **Use periodic timers for polling** — Check for updates, refresh UI, heartbeat
2. **Use one-shot timers for delays** — Debouncing, timeouts, scheduled actions
3. **Always cancel timers you no longer need** — Prevents stale message delivery
4. **Clone messages must be cheap** — Use `Arc<str>` or small enums for periodic messages
5. **Use actor-context timers for actor-owned timers** — `ctx.schedule_timer` / `ctx.schedule_interval`
6. **Use runtime timers for external scheduling** — `runtime.schedule_timer` / `runtime.schedule_interval`