swactor/docs/channels.md

Channels & Shared State

All communication between workers (and between the Runtime and workers) goes through lock-free channels. There are no mutexes in the hot path.

HybridChannel

The core primitive. A lock-free MPSC queue with bounded fast path and unbounded overflow.

┌─ HybridChannel<T> ───────────────────────────────────────────────────────┐
│                                                                           │
│  ┌─ ring: ArrayQueue<T> (crossbeam) ─────────────────────────────────┐   │
│  │  Pre-allocated, fixed capacity, lock-free CAS                      │   │
│  │  ┌───┬───┬───┬───┬───┬───┬───┬───┐                                │   │
│  │  │   │   │   │   │   │   │   │   │                                │   │
│  │  └───┴───┴───┴───┴───┴───┴───┴───┘                                │   │
│  └────────────────────────────────────────────────────────────────────┘   │
│                                                                           │
│  ┌─ overflow: SegQueue<T> (crossbeam) ───────────────────────────────┐   │
│  │  Unbounded linked-list queue, lock-free                            │   │
│  │  Only used when ring is full                                       │   │
│  └────────────────────────────────────────────────────────────────────┘   │
│                                                                           │
│  push(v):                                                                 │
│    ring.push(v) → Ok:  done                                              │
│    ring.push(v) → Err: overflow.push(v)                                  │
│                                                                           │
│  pop():                                                                   │
│    ring.pop()     → Some: return it                                      │
│    overflow.pop() → Some: return it                                      │
│    otherwise      → None                                                 │
│                                                                           │
└───────────────────────────────────────────────────────────────────────────┘

The fast path (ring) avoids allocation. The overflow (SegQueue) acts as a safety net — the system never drops messages due to capacity, but performance degrades under sustained overflow.

Sender and Receiver

┌─ Sender<T> ──────────┐          ┌─ Receiver<T> ────────────┐
│                       │          │                           │
│  queue: Arc<Hybrid>   │──same──▶│  queue: Arc<Hybrid>       │
│                       │   Arc    │                           │
│  try_send(v) → push   │          │  try_recv() → pop         │
│                       │          │                           │
│  Clone: new_sender()  │          │  Single consumer          │
│  (clones the Arc)     │          │  (not Clone)              │
│                       │          │                           │
└───────────────────────┘          └───────────────────────────┘

Sender is Clone — multiple producers can send into the same channel. Receiver is not Clone — exactly one consumer drains it.

What Channels Exist

Each worker gets two inbound channels, created at Runtime::new() time:

  Per Worker:

    transfer channel:  carries Envelope (messages to actors)
      Senders:   Runtime, other workers (via TickContext)
      Receiver:  this Worker

    spawn channel:     carries (ActorAddress, Box<dyn AnyActor>)
      Senders:   Runtime, other workers (via TickContext)
      Receiver:  this Worker

For N workers, the runtime holds N transfer senders and N spawn senders. Every worker can reach every other worker's queues through TickContext.

AddressMap

Global directory mapping actor addresses to the worker that owns them.

┌─ AddressMap ──────────────────────────────────────────────────────────────┐
│                                                                           │
│  RwLock< HashMap<ActorAddress, WorkerId> >                                │
│                                                                           │
│  Read path (very frequent):                                               │
│    Every ctx.send() and Runtime.send_to() does a lookup.                  │
│    RwLock allows concurrent readers — no contention.                      │
│                                                                           │
│  Write path (rare):                                                       │
│    Only on spawn. Takes exclusive lock briefly.                           │
│                                                                           │
└───────────────────────────────────────────────────────────────────────────┘

Placement

Decides which worker gets a newly spawned actor.

┌─ Placement ───────────────────────────────────────────────────────────────┐
│                                                                           │
│  next: AtomicUsize                                                        │
│  num_workers: usize                                                       │
│                                                                           │
│  next_worker() → WorkerId( next.fetch_add(1) % num_workers )              │
│                                                                           │
│  Simple round-robin. No load balancing, no affinity.                      │
│  Actors stay on their assigned worker for life.                           │
│                                                                           │
└───────────────────────────────────────────────────────────────────────────┘

Where Things Live in the Code

Concept	File
HybridChannel, Sender, Receiver	src/channel.rs
AddressMap, WorkerId, Placement	src/address_map.rs
Envelope	src/runtime.rs
InboxRegistry	src/runtime.rs
RuntimeConfig, BackoffPolicy	src/config.rs