runact 1.0.0

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

## Overview

Runact uses a BEAM-style scheduler with work stealing. The scheduler multiplexes many actors over a relatively small number of OS threads.

## Core Principle

> **Do NOT create one OS thread per actor.**

```text
100,000 Actors
       │
       ▼
Runact Scheduler
       │
 ┌─────┼─────┐
 ▼     ▼     ▼
Worker Worker Worker
```

## Architecture

```text
┌─────────────────────────────────────────────────────────┐
│                    Scheduler                            │
├─────────────┬─────────────┬─────────────┬──────────────┤
│  Worker 0   │  Worker 1   │  Worker 2   │  Worker 3    │
│  ┌───────┐  │  ┌───────┐  │  ┌───────┐  │  ┌───────┐  │
│  │ RunQ  │  │  │ RunQ  │  │  │ RunQ  │  │  │ RunQ  │  │
│  │[A,B,C]│  │  │[D,E,F]│  │  │[G,H,I]│  │  │[J,K,L]│  │
│  └───────┘  │  └───────┘  │  └───────┘  │  └───────┘  │
│      │      │      │      │      │      │      │      │
│      ▼      │      ▼      │      ▼      │      ▼      │
│  Actor A    │  Actor D    │  Actor G    │  Actor J    │
└─────────────┴─────────────┴─────────────┴──────────────┘
                    │
            Work Stealing
```

## Components

### Scheduler

Top-level coordinator.

```rust
pub struct Scheduler {
    workers: Vec<Worker>,
    sender: Option<Sender<Task>>,
    handles: Vec<JoinHandle<()>>,
}
```

### Worker

Per-core scheduler with own run queue.

```rust
struct Worker {
    id: usize,
    queue: Arc<Mutex<VecDeque<Task>>>,
}
```

### RunQueue

Lock-free MPSC queue per worker.

```rust
struct RunQueue {
    queue: Arc<Mutex<VecDeque<Task>>>,
}
```

### ReductionCounter

Prevents starvation by counting message processing.

```rust
pub const MAX_REDUCTIONS: u64 = 4000;

struct ReductionCounter {
    count: AtomicU64,
}
```

## Algorithm

### Basic Flow

```text
1. Actor spawns → added to worker queue
2. Worker picks actor from queue
3. Actor processes one message
4. Reduction counter increments
5. If counter >= MAX_REDUCTIONS → preempt
6. Otherwise → continue with next message
7. If no work → try to steal from other workers
```

### Work Stealing

```text
Worker 0 idle
    │
    ▼
Check own queue → empty
    │
    ▼
Try to steal from random worker
    │
    ├── Found work → execute
    │
    └── No work → sleep briefly → retry
```

## Priorities

The scheduler should prioritize:

1. **Responsiveness** — Actors respond quickly
2. **Fairness** — No actor starves
3. **Throughput** — Process many messages
4. **Predictability** — Consistent behavior

## Implementation

### Spawning an Actor

```rust
impl Scheduler {
    pub fn spawn<F>(&self, f: F)
    where
        F: FnOnce() + Send + 'static,
    {
        if let Some(sender) = &self.sender {
            let _ = sender.send(Box::new(f));
        }
    }
}
```

### Worker Loop

```rust
fn worker_loop(id: usize, queue: Arc<Mutex<VecDeque<Task>>>) {
    loop {
        let task = {
            let mut q = queue.lock().unwrap();
            q.pop_front()
        };

        match task {
            Some(task) => {
                task();
            }
            None => {
                // No work available, yield
                thread::yield_now();
            }
        }
    }
}
```

## Configuration

### Default Settings

```rust
let scheduler = Scheduler::new();
```

- Workers = available parallelism (usually CPU cores)
- Queue capacity = unbounded initially
- Reduction limit = 4000

### Custom Settings

```rust
let scheduler = Scheduler::with_config(SchedulerConfig {
    num_workers: 8,
    max_reductions: 2000,
});
```

## Cooperative Scheduling

### Why Cooperative?

Rust code cannot safely be arbitrarily preempted at any instruction boundary. Runact uses cooperative scheduling at safe execution boundaries.

### How It Works

```rust
fn handle(&mut self, msg: Message, ctx: &mut ActorContext) -> Result<(), ActorError> {
    // Process one message
    self.process(msg);
    
    // Yield back to scheduler
    // (Implicit - handler returns)
    
    Ok(())
}
```

### What Actors Should Do

- Process one message
- Perform bounded work
- Return quickly
- Don't loop forever
- Don't block on I/O

### What Actors Should NOT Do

- Run for milliseconds
- Block on external resources
- Spin in loops
- Call `thread::sleep`
- Perform CPU-intensive work (use compute pool)

## Monitoring

### Metrics

```rust
pub struct SchedulerMetrics {
    pub worker_count: usize,
    pub total_actors: usize,
    pub messages_processed: u64,
    pub steals_attempted: u64,
    pub steals_succeeded: u64,
}
```

### Observability

```rust
// Trace actor execution
tracing::debug!(
    actor_id = %actor_id,
    message_count = count,
    duration_ms = elapsed.as_millis(),
    "Actor executed"
);
```

## Future Enhancements

### Priority Scheduling

```rust
enum Priority {
    Critical,
    High,
    Normal,
    Low,
}
```

### Actor Affinity

```rust
// Pin actor to specific worker
scheduler.spawn_with_affinity(actor, worker_id);
```

### Work Stealing Strategies

- Random victim
- Least loaded victim
- Nearest neighbor