core(actor_ref): rebuild from kameo reference — ActorRef / Weak / Recipient

[joeldsouzax]

Part of the core-rebuild epic — follows the shared rigor contract there.

Component

src/actor/actor_ref.rs (~3,008 LOC — the largest file). ActorRef, WeakActorRef, Recipient/ReplyRecipient, tell/ask entry points, strong/weak ref counting.

Learning & discussion

The handle you hold to talk to an actor. Last strong-ref drop → actor stops. Recipient is a type-erased handle for heterogeneous fan-in. At 3k LOC this file is doing too much — split into focused modules as part of the rebuild (ref + counting + recipient + entry).

Existing crates

Arc/Weak (std) — evaluate; possibly triomphe for a leaner Arc.

Research — best algorithm/approach

Strong/weak lifecycle → shutdown semantics; ref-count-driven stop; type-erasure for Recipient without vtable bloat.

Testing — hard as fuck

Lifecycle (last strong ref drop stops actor; weak upgrade after stop → None), linearizability (concurrent tell/ask/drop, snapshot assertions), defensive boundary. DST over ref drop/upgrade races. Mutation: cargo-mutants, zero survivors.

[joeldsouzax]

FINALIZED — ref model: sharded-slab generational store + typed sender in the ref

Validated against kameo 0.21 + tokio 1.52 source (read directly) and sharded-slab docs. Verdict: sound; the hot path is contention-free (identical floor to kameo); death-detection holds and is stronger than a pure-key scheme; the consistency invariant resolves in #116's teardown.

The model

• ActorRef<A> = { key: SlabKey(index, generation), tx: mpsc::Sender<Signal<A>> (cloned/cached), abort: AbortHandle }. The cached typed sender is load-bearing — it keeps send off the slab (and zero-box, per core(message): rebuild from kameo reference — Message trait + Context dispatch #114).
• WeakActorRef<A> = key + WeakSender (downgrade). For death-watchers / registry / graph edges that must not pin the channel allocation (kameo's WeakMailboxSender precedent). Strong = can send + pins channel; weak = validate liveness via the slab without pinning.
• Slot store = Arc<sharded_slab::Slab<Slot>> — per-thread-sharded inserts, lock-free &self get/remove, generation-guarded. Slot holds cold-path state only: generation (implicit), supervision-graph edges, AbortHandle, AID mapping. The actor instance A stays in the tokio task (the loop owns &mut self, core(actor): rebuild from kameo reference — Actor trait, lifecycle hooks, run-loop #116) — never in the slab (that would reintroduce heterogeneity/erasure, the ractor trap).
• Name/AID → ref registry (core(registry): rebuild from kameo reference — local name to actor lookup #119) = dashmap (RwLock-sharded, simplest) or flurry (lock-free reads). Same "don't hold the guard across .await" discipline.

Hot path — contention-free (verified)

tell/ask = tx.send(Signal::Message(msg)). Never touches the slab, never checks liveness, never hits a global atomic — the only synchronization is the tokio channel's internal atomics, the identical floor kameo pays. Death is observed as SendError (send-and-observe); a pre-send liveness read of the slab would be TOCTOU-wrong, not just wasteful.

Death-detection — verified, stronger than pure-key

• sharded-slab: reap → the old (index, generation) key get()s None → death-watch (design: link-death — per-actor liveliness vs per-node + explicit death #8) + passivation (feat: matching status -> interest-driven (lazy) actors #20) for free.
• tokio: the channel closes on receiver drop, independent of sender clones — a held/leaked ActorRef can never resurrect a reaped actor; every cached sender returns SendError once the loop drops its receiver.
• Cross-generation misdelivery impossible by construction: the cached sender is bound to a specific channel instance (its own Arc); a stale ref can't reach the reused slot's new actor (dead old channel + failed gen check). Generation is belt-and-suspenders for the by-name/death-watch paths.

The consistency invariant (resolves in #116's teardown)

Receiver-drop (makes sends fail) and generation-bump+slot-reap (makes key-validation fail) are two events; if they aren't sequenced the two liveness views disagree. Discipline: the actor-loop teardown is the single owner of both the mailbox Receiver and the slab slot — drop the receiver, then publish the generation bump (Release), then free the slot. (See the #116 update.)

Concurrency discipline (rule #5 — structural, not vibes)

• Generation ordering: Relaxed only if the generation is a pure uniqueness tag (kameo-id precedent — nothing read conditionally on it). The instant a validator reads slot payload gated on the generation → Release on the reap-write, Acquire on the validator-read, justified as "the generation publishes the slot's reinitialized contents" (gen N+1 observed ⇒ N+1 contents observed, no torn leftovers). Wrong → use-after-reap read. sharded-slab handles its own internals; this applies to any slot metadata we gate on generation ourselves.
• ABA budget: sharded-slab default = 13 generation bits → 8192 reuses/slot before a long-lived stale key could alias. Widen via Config/RESERVED_BITS if a hot slot could passivate→reactivate that many times under a retained stale ref (feat: matching status -> interest-driven (lazy) actors #20). The slot generation solves ABA for actor identity, not a hand-rolled free-list's node ABA — sharded-slab owns that; if we ever hand-roll, use a sharded Mutex (honest) or epoch reclamation.
• Entry guard hazard: slab.get() returns a live guard that defers removal (take spins). Rule: get() → clone the handle → drop the Entry → then .await. The hot path takes no guard, so it's immune.

Memory-pin residual

A cached strong sender pins the channel's heap allocation until all senders + the receiver are gone (same as kameo). Mitigate with WeakActorRef for watchers/registry/graph. Correctness unaffected (death still detected) — it's a leak-avoidance discipline.

What this collapses into one structure

#117 ref + #119 registry + #8 death-watch + #20-local passivation + #121-local id — one sharded-slab-backed layer. Local id = the slab key (Copy, liveness-bearing); global id = AID / key-expr (#121); a local AID → key map bridges. Net vs kameo: the hot path is unchanged (we don't regress kameo's decentralization); the win is a cheap Copy liveness-bearing key that doesn't pin the channel, a unified registry/liveness/graph structure, and a natural passivation reap.

Sources

kameo 0.21 (actor/id.rs, actor/actor_ref.rs, mailbox.rs, registry.rs, request/tell.rs) · tokio 1.52 mpsc (send→SendError on closed; is_closed/closed on receiver drop) · sharded-slab 0.1 · dashmap / flurry.

[joeldsouzax]

⚠️ REVERSED by the adversarial review (#122)

The sharded-slab generational-arena ref model is dropped. Adversarial finding: the arena's pitched unique benefit — a Copy, non-pinning liveness key — is false; std Weak / tokio WeakSender already give non-pinning liveness (upgrade()/is_closed()), and kameo already builds watch/link edges on downgraded weak senders. The arena's real gain (Copy vs atomic RMW + cache-locality) pays off only for a large, hot, re-cloned watcher set (>~1e4), not event-sourced aggregates — while it drags in a panic-safe Drop-guard reap, guard-across-await spin, 13-bit ABA in ~13.6 min on churny slots, a MAX_THREADS panic, loom-opacity, and no no_std (can't serve the M6 client).

New ref model — kameo-style Arc/Weak hybrid:

• ActorRef<A> = typed mpsc::Sender<Signal<A>> (decentralized, contention-free clone) + AbortHandle; is_alive() = !sender.is_closed().
• WeakActorRef<A> = WeakSender — non-pinning, for watch/link edges and registry entries.
• Death-detection = push (dying actor notifies links in on_stop) + pull is_closed() backup — NOT poll-staleness.
• No central slot → the panic-Drop-guard-reap bug (chore: fork kameo into bombay + workspace/CI setup #1), guard-spin (chore: delete behaviour.rs + replace swarm with a Zenoh Session #5), generation ABA (feat: bootstrap() opens a Zenoh session #6), insert-full (chore: keep & adapt _internal.rs linkme dispatch registry #7) all dissolve.
• A generational slab is benchmark-gated (add only if watcher fan-out × re-clone rate is measured as a bottleneck — rule feat: messaging over Zenoh query/reply #4). Behind the Registry/Store trait seam either way.