swactor/ARCHITECTURE.md

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   │
  └───────────────────────┘