swactor/CLAUDE/notes/dispatch_comparison.md

Dispatch Model Comparison: Stakker vs Actix vs Swactor

Stakker — Closure-Based Dispatch (No HashMap, No Downcast)

Architecture: Single-threaded, synchronous actor runtime (like swactor). Messages are FnOnce closures, not typed structs.

Key Design:

• call! macro turns method calls into closures: call!([actor], method(arg1, arg2)) generates a FnOnce that directly calls the method on the actor
• The closure captures the actor reference and method pointer — dispatch is a direct function call, not a downcast
• Closures stored in a flat heterogeneous FnOnce queue (byte Vec) — no per-message heap allocation
• Compiler can inline the closure, reducing message handling to "a single branch to optimised inlined code"

Why It's Fast:

• Zero Box<dyn Any> allocation per message
• Zero TypeId downcast per message
• Zero HashMap lookup per message (actors addressed by direct ActorOwn<A> references, not opaque addresses)
• Queue is a flat contiguous memory region — excellent cache locality

Tradeoffs:

• Single-threaded only (no multi-worker routing)
• No location-transparent addresses (can't route to remote actors)
• Uses unsafe code by default for the FnOnce queue

Actix — Vtable Dispatch (No HashMap, No Downcast)

Architecture: Async actor framework on tokio. Each actor is a pollable Future on an Arbiter thread.

Key Design:

• Addr<A> wraps an AddressSender<A> — a direct channel reference, not an address in a map
• Messages wrapped as Box<dyn EnvelopeProxy<A>> — vtable dispatch, not Box<dyn Any> downcast
• Custom Vyukov lock-free MPSC queue (single AtomicPtr::swap for push)
• Default mailbox capacity: 16

Why It's Fast:

• Addr<A> is a direct channel reference — zero HashMap lookup per send
• EnvelopeProxy vtable call — one virtual dispatch, no TypeId comparison
• Vyukov MPSC queue — lock-free push, minimal atomic operations
• do_send() bypasses backpressure for internal messages

Tradeoffs:

• Requires async runtime (tokio dependency)
• Addr<A> is typed — can't send different message types without Recipient<M> adaptation
• do_send() silently drops messages to closed actors (no error feedback)

Swactor — Type-Erased Dispatch with HashMap Routing

Architecture: Synchronous tick-based runtime with multi-worker support. Messages are Box<dyn Any + Send>.

Message Send Path (per-message costs):

1. Box::new(msg) — heap allocation (~10-15ns)
2. address_map.lookup(&addr) — RwLock read + HashMap get with 32-byte key
3. Push to VecDeque or crossbeam queue

Message Process Path (per-message costs):

1. slot.mailbox.pop_front() — VecDeque pop
2. msg.downcast::<Incoming>() — TypeId comparison (~1ns)
3. catch_unwind(|| actor.handle_any(ctx, msg)) — unwind setup (~3-5ns)

Why It's Slower on Paper:

• HashMap lookup on every send AND every deliver (2 lookups per message)
• ActorAddress is 32 bytes — expensive to hash (SipHash: ~15ns for 32 bytes)
• Box<dyn Any> heap allocation on every send

Why This Architecture Exists:

• Location-transparent 32-byte addresses enable multi-worker routing, transport layer, and distribution
• Type erasure enables heterogeneous mailboxes and type-agnostic forwarding
• HashMap enables O(1) address → worker lookup for any actor, from any thread

Optimization Applied: Identity Hashing

Problem: Every HashMap operation hashes 32 bytes of ActorAddress with SipHash.

Solution (two-layer):

1. Custom Hash impl on ActorAddress — only hashes first 8 bytes via write_u64 (SipHash on 8 bytes is ~3x faster than 32 bytes)
2. Identity hasher (AddrHasher) on hot-path HashMaps — uses the 8-byte hash value directly as the bucket index, skipping SipHash entirely

Microbenchmark Results (same-process A/B comparison, reliable):

Operation	SipHash (8-byte)	Identity	Speedup
Hash	1.35 ns	0.67 ns	2.0x
Lookup (100 entries)	29.8 ns	15.5 ns	1.9x
Lookup (1000 entries)	38.0 ns	8.2 ns	4.6x
Insert 1000	48.2 µs	21.1 µs	2.3x

Why It's Safe: ActorAddress bytes come from getrandom — cryptographically random, providing excellent uniform distribution without additional mixing.

Summary Table

Aspect	Stakker	Actix	Swactor (optimized)
Message type	FnOnce closure	Box<dyn EnvelopeProxy>	Box<dyn Any + Send>
Dispatch	Direct call / inlined	Vtable call	TypeId downcast
Address lookup	None (direct ref)	None (direct channel)	Identity-hash HashMap
Per-msg alloc	None (flat queue)	Box (MPSC node)	Box (heap + VecDeque)
Multi-thread	No	Yes (tokio)	Yes (worker threads)
Location transparency	No	No	Yes (32-byte address)
Remote transport	No	No (without extras)	Yes (pluggable)

Key Insight

Stakker and Actix are faster because they avoid the per-message HashMap lookup entirely — addresses are direct references, not opaque identifiers that need routing. Swactor pays for HashMap routing because its 32-byte addresses enable multi-worker distribution and remote transport. The identity hasher minimizes this cost without changing the architecture.