199 lines
13 KiB
Markdown
199 lines
13 KiB
Markdown
|
# Swactor Architecture
|
||
|
|
|
||
|
|
## System Diagram
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
|
|
│ Runtime │
|
||
|
|
│ (composes everything) │
|
||
|
|
│ │
|
||
|
|
│ ┌───────────────────────────────────────────────────────────────────────┐ │
|
||
|
|
│ │ Address Map │ │
|
||
|
|
│ │ ActorAddress → WorkerId │ │
|
||
|
|
│ │ (shared across all workers, read-heavy) │ │
|
||
|
|
│ └──────┬──────────────────┬──────────────────────┬─────────────────────┘ │
|
||
|
|
│ │ │ │ │
|
||
|
|
│ ▼ ▼ ▼ │
|
||
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||
|
|
│ │ Worker 0 │ │ Worker 1 │ ... │ Worker N │ │
|
||
|
|
│ │ (thread) │ │ (thread) │ │ (thread) │ │
|
||
|
|
│ │ │ │ │ │ │ │
|
||
|
|
│ │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │
|
||
|
|
│ │ │ Actor A │ │ │ │ Actor C │ │ │ │ Actor E │ │ │
|
||
|
|
│ │ │ [═════] │ │ │ │ [═════] │ │ │ │ [═════] │ │ │
|
||
|
|
│ │ │ mailbox │ │ │ │ mailbox │ │ │ │ mailbox │ │ │
|
||
|
|
│ │ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │ │
|
||
|
|
│ │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │
|
||
|
|
│ │ │ Actor B │ │ │ │ Actor D │ │ │ │ Actor F │ │ │
|
||
|
|
│ │ │ [═════] │ │ │ │ [═════] │ │ │ │ [═════] │ │ │
|
||
|
|
│ │ │ mailbox │ │ │ │ mailbox │ │ │ │ mailbox │ │ │
|
||
|
|
│ │ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │ │
|
||
|
|
│ │ │ │ │ │ │ │
|
||
|
|
│ │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │
|
||
|
|
│ │ │Transfer │◄├────├─┤Transfer │◄├───────├─┤Transfer │ │ │
|
||
|
|
│ │ │ Queue │ │ │ │ Queue │ │ │ │ Queue │ │ │
|
||
|
|
│ │ │ (MPSC) │─├────├►│ (MPSC) │─├───────├►│ (MPSC) │ │ │
|
||
|
|
│ │ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │ │
|
||
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||
|
|
│ │
|
||
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
||
|
|
|
||
|
|
|
||
|
|
══ = VecDeque (no atomics)
|
||
|
|
```
|
||
|
|
|
||
|
|
## Message Flow
|
||
|
|
|
||
|
|
```
|
||
|
|
SAME WORKER (fast path — zero atomics)
|
||
|
|
═══════════════════════════════════════
|
||
|
|
|
||
|
|
Actor A Actor B
|
||
|
|
handle() { mailbox (VecDeque)
|
||
|
|
ctx.send(addr_B, msg) ▲
|
||
|
|
│ │
|
||
|
|
├─ address_map[addr_B] │
|
||
|
|
│ → Worker 0 (that's me!) │
|
||
|
|
│ │
|
||
|
|
└─ mailbox_B.push(msg) ──────┘
|
||
|
|
} no atomics, no envelope
|
||
|
|
|
||
|
|
|
||
|
|
CROSS-WORKER (one atomic hop)
|
||
|
|
═══════════════════════════════
|
||
|
|
|
||
|
|
Actor A (Worker 0) Worker 1 Actor C (Worker 1)
|
||
|
|
handle() { transfer queue mailbox (VecDeque)
|
||
|
|
ctx.send(addr_C, msg) ▲ ▲
|
||
|
|
│ │ │
|
||
|
|
├─ address_map[addr_C] │ │
|
||
|
|
│ → Worker 1 (not me) │ │
|
||
|
|
│ │ │
|
||
|
|
└─ envelope(addr_C, msg) ──────┘ │
|
||
|
|
(atomic push) │ │
|
||
|
|
└── worker 1 pops ─────┘
|
||
|
|
and distributes
|
||
|
|
(local, no atomic)
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Worker Loop
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────┐
|
||
|
|
│ Worker Thread │
|
||
|
|
│ │
|
||
|
|
│ loop { │
|
||
|
|
│ ┌──────────────────────────────────────┐ │
|
||
|
|
│ │ 1. DRAIN TRANSFER QUEUE │ │
|
||
|
|
│ │ while let Some((addr, env)) = │ │
|
||
|
|
│ │ transfer_queue.pop() │ │
|
||
|
|
│ │ { │ │
|
||
|
|
│ │ local_actors[addr].mailbox │ │
|
||
|
|
│ │ .push(env.unpack()) │ │
|
||
|
|
│ │ } │ │
|
||
|
|
│ └──────────────────────────────────────┘ │
|
||
|
|
│ ┌──────────────────────────────────────┐ │
|
||
|
|
│ │ 2. TICK ACTORS │ │
|
||
|
|
│ │ for actor in &mut actor_pool { │ │
|
||
|
|
│ │ let n = drain_count(actor); │ │
|
||
|
|
│ │ for _ in 0..n { │ │
|
||
|
|
│ │ let msg = actor.mailbox.pop();│ │
|
||
|
|
│ │ actor.handle(&ctx, msg); │ │
|
||
|
|
│ │ } │ │
|
||
|
|
│ │ } │ │
|
||
|
|
│ └──────────────────────────────────────┘ │
|
||
|
|
│ ┌──────────────────────────────────────┐ │
|
||
|
|
│ │ 3. IDLE? │ │
|
||
|
|
│ │ if no messages processed: │ │
|
||
|
|
│ │ spin → yield → park │ │
|
||
|
|
│ └──────────────────────────────────────┘ │
|
||
|
|
│ } │
|
||
|
|
└───────────────────────────────────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
## File Tree
|
||
|
|
|
||
|
|
```
|
||
|
|
src/
|
||
|
|
├── lib.rs # crate root, feature flags, public exports
|
||
|
|
├── error.rs # Error type
|
||
|
|
│
|
||
|
|
├── actor.rs # Message trait, ActorInterface trait, ActorAddress
|
||
|
|
│ # - ActorInterface::handle(&mut self, ctx: &dyn Context, msg)
|
||
|
|
│ # - actors depend ONLY on Context, nothing else
|
||
|
|
│
|
||
|
|
├── context.rs # Context trait — the "syscall interface" for actors
|
||
|
|
│ # - send(), self_addr(), spawn()
|
||
|
|
│ # - this is ALL actors can see of the framework
|
||
|
|
│
|
||
|
|
├── envelope.rs # Envelope type — type erasure for cross-thread messages
|
||
|
|
│ # - wraps typed messages for the transfer queue
|
||
|
|
│ # - unwraps back to concrete type at destination
|
||
|
|
│
|
||
|
|
├── address_map.rs # ActorAddress → WorkerId mapping
|
||
|
|
│ # - shared read-heavy structure
|
||
|
|
│ # - written on spawn, read on every send
|
||
|
|
│
|
||
|
|
├── transfer.rs # Transfer queue — per-worker MPSC
|
||
|
|
│ # - the ONE concurrent data structure on the hot path
|
||
|
|
│ # - carries (ActorAddress, Envelope) pairs
|
||
|
|
│
|
||
|
|
├── worker/
|
||
|
|
│ ├── mod.rs # Worker struct and worker loop
|
||
|
|
│ │ # - owns actor pool + transfer queue
|
||
|
|
│ │ # - the thread boundary: concurrent outside, local inside
|
||
|
|
│ │ # - drain transfer queue → tick actors → backoff
|
||
|
|
│ │
|
||
|
|
│ ├── mailbox.rs # VecDeque-based local mailbox
|
||
|
|
│ │ # - NO atomics, NO Arc, NO crossbeam
|
||
|
|
│ │ # - only touched by the owning worker thread
|
||
|
|
│ │
|
||
|
|
│ └── pool.rs # Actor pool — stores actors assigned to this worker
|
||
|
|
│ # - local HashMap or Vec for ActorAddress → Actor lookup
|
||
|
|
│ # - insert on spawn, remove on shutdown
|
||
|
|
│
|
||
|
|
├── runtime.rs # Runtime — the composition point
|
||
|
|
│ # - creates workers, address map
|
||
|
|
│ # - implements Context (delegates to address map + transfer queues)
|
||
|
|
│ # - public API: new(), spawn(), send_to(), run(), tick(), shutdown()
|
||
|
|
│
|
||
|
|
├── config.rs # RuntimeConfig — tuning knobs
|
||
|
|
│ # - num_threads, max_actors, mailbox capacity
|
||
|
|
│ # - drain strategy, backoff policy
|
||
|
|
│ # - placement strategy (round-robin, caller-affinity, etc.)
|
||
|
|
│
|
||
|
|
└── placement.rs # Actor placement strategy
|
||
|
|
# - decides which worker a new actor goes to
|
||
|
|
# - round-robin, least-loaded, caller-affinity
|
||
|
|
```
|
||
|
|
|
||
|
|
## Components
|
||
|
|
|
||
|
|
| Component | File(s) | What It Does | Concurrent? |
|
||
|
|
|---|---|---|---|
|
||
|
|
| **Worker** | `worker/mod.rs` | Owns a thread, a pool of actors, their mailboxes, and a transfer queue. Runs the tick loop. Everything inside is single-threaded. | No (that's the point) |
|
||
|
|
| **Mailbox** | `worker/mailbox.rs` | `VecDeque<M>` per actor. Zero atomics. Only the owning worker reads/writes. | No |
|
||
|
|
| **Actor Pool** | `worker/pool.rs` | Stores actors on this worker. Local lookup by address. | No |
|
||
|
|
| **Transfer Queue** | `transfer.rs` | MPSC queue per worker. The only atomic boundary. Other workers push, this worker pops. | Yes (the ONE place) |
|
||
|
|
| **Address Map** | `address_map.rs` | Maps ActorAddress → WorkerId. Read on every cross-thread send, written on spawn. | Yes (read-heavy) |
|
||
|
|
| **Envelope** | `envelope.rs` | Type-erases messages for the transfer queue. Unwrapped at destination. | No (data format) |
|
||
|
|
| **Context** | `context.rs` | Trait that actors see. `send()`, `self_addr()`, `spawn()`. Hides all framework internals. | N/A (trait) |
|
||
|
|
| **Runtime** | `runtime.rs` | Wires it all together. Creates workers, holds address map, exposes public API. | Minimal (delegates) |
|
||
|
|
| **Placement** | `placement.rs` | Decides which worker gets a new actor. | No (called at spawn time) |
|
||
|
|
|
||
|
|
## Single-Threaded / WASM Mode
|
||
|
|
|
||
|
|
One worker. No transfer queue needed. No address map needed (everything is local). The system collapses to:
|
||
|
|
|
||
|
|
```
|
||
|
|
Worker 0
|
||
|
|
┌───────────────────────┐
|
||
|
|
│ Actor A [mailbox] │
|
||
|
|
│ Actor B [mailbox] │ All sends are local.
|
||
|
|
│ Actor C [mailbox] │ All mailboxes are VecDeque.
|
||
|
|
│ │ Zero atomics anywhere.
|
||
|
|
│ tick() drives loop │
|
||
|
|
└───────────────────────┘
|
||
|
|
```
|