RFC 016 Chunk 1: runtime introspection read primitive

snapshot() / actor_info() return owned ActorInfo over the slab: pid,
names, fine-grained scheduling state, parent edge, trap flag, mailbox
depth, and monitor/link/joiner counts. Pure reads, no hot-path change.

- ActorState maps the packed slot word (no new storage); introspect.rs.
- D1: RuntimeSnapshot carries SNAPSHOT_FORMAT_VERSION from day one.
- D2: per-slot tearing (ps semantics); actor_info coherent per actor.
- D3: mailbox depth included. Registry channels now stored behind an
  ErasedSender trait (downcast for clone_sender + type-erased
  queued_len); depth summed over published channels under the registry
  Leaf (Leaf -> Channel), kept out of the cold-lock pass so no two
  Leaves are ever held at once. Depth covers published channels only.
- Done slots surface as root-less tombstones.
This commit is contained in:
smarm-agent
2026-06-19 06:31:10 +00:00
parent fc014c4e54
commit c66691943d
6 changed files with 460 additions and 1 deletions
+76 -1
View File
@@ -148,11 +148,30 @@ impl<M> std::fmt::Display for SendError<M> {
impl<M> std::error::Error for SendError<M> {}
/// A registry-stored channel, type-erased over its message type. The stored
/// object must serve two readers: `clone_sender` (downcast back to the concrete
/// `Sender<M>`) and the RFC 016 snapshot (queued length without knowing `M`).
/// A bare `Box<dyn Any>` gives the first but not the second, so we erase behind
/// this small trait instead.
trait ErasedSender: Send {
fn as_any(&self) -> &dyn Any;
fn queued_len(&self) -> usize;
}
impl<M: Send + 'static> ErasedSender for Sender<M> {
fn as_any(&self) -> &dyn Any {
self
}
fn queued_len(&self) -> usize {
Sender::queued_len(self)
}
}
/// One typed channel of an actor, type-erased. Concretely a `Sender<M>` filed
/// under `TypeId::of::<M>()`; `msg_type` is `type_name::<M>()`, kept for
/// observers (RFC 014 §4.5) and as the debug cross-check on the downcast.
struct Channel {
sender: Box<dyn Any + Send>,
sender: Box<dyn ErasedSender>,
msg_type: &'static str,
}
@@ -176,6 +195,7 @@ impl Mailbox {
let ch = self.channels.get(&TypeId::of::<M>())?;
let tx = ch
.sender
.as_any()
.downcast_ref::<Sender<M>>()
.expect("channel keyed by TypeId but downcast to its own type failed — smarm bug");
debug_assert_eq!(ch.msg_type, type_name::<M>(), "msg_type / TypeId disagree");
@@ -183,6 +203,18 @@ impl Mailbox {
}
}
/// Per-actor registry view handed to RFC 016 introspection: registered names
/// and summed mailbox depth, tagged with the mailbox's `pid` so a stale
/// incarnation can be filtered against the slab. Covers only *published*
/// channels (`register` / `install` / `spawn_addr` / gen_server start); an
/// actor that holds only a private `channel()` receiver is invisible here and
/// reports depth 0.
pub(crate) struct MailboxInfo {
pub(crate) pid: Pid,
pub(crate) names: Vec<&'static str>,
pub(crate) depth: u32,
}
/// The directory. Invariant (held under the registry lock): every value in
/// `by_name` is the index of a [`Mailbox`] present in `by_index`, and that
/// mailbox's `pid.index()` equals the key. Stale entries (dead actors) violate
@@ -204,6 +236,49 @@ impl Registry {
self.by_index.remove(&index);
self.by_name.retain(|_, idx| *idx != index);
}
/// RFC 016 snapshot input: per-slot-index registry view — the actor's
/// registered names (inverted from `by_name`) and its mailbox depth (queued
/// messages summed across every published typed channel). Built in one pass
/// under the registry Leaf; the per-channel `queued_len` takes a Channel
/// lock, legal under the Leaf (Leaf → Channel). Carries each mailbox's full
/// `pid` so the caller can discard a stale incarnation's entry against the
/// slab's live generation. Names that dangle (point at no mailbox) are
/// dropped — they violate no invariant and get pruned on next contact.
pub(crate) fn introspect_map(&self) -> HashMap<u32, MailboxInfo> {
let mut names: HashMap<u32, Vec<&'static str>> = HashMap::new();
for (&name, &idx) in &self.by_name {
names.entry(idx).or_default().push(name);
}
let mut out: HashMap<u32, MailboxInfo> = HashMap::with_capacity(self.by_index.len());
for (&idx, mb) in &self.by_index {
let depth: usize = mb.channels.values().map(|c| c.sender.queued_len()).sum();
out.insert(
idx,
MailboxInfo {
pid: mb.pid,
names: names.remove(&idx).unwrap_or_default(),
depth: depth.min(u32::MAX as usize) as u32,
},
);
}
out
}
/// Single-actor form of [`introspect_map`](Self::introspect_map): the
/// registry view for one slot index, or `None` if no mailbox is published
/// there. Used by `actor_info` so its cost stays proportional to the one
/// actor rather than locking every channel in the runtime.
pub(crate) fn introspect_one(&self, idx: u32) -> Option<MailboxInfo> {
let mb = self.by_index.get(&idx)?;
let depth: usize = mb.channels.values().map(|c| c.sender.queued_len()).sum();
let names = self
.by_name
.iter()
.filter_map(|(&n, &i)| (i == idx).then_some(n))
.collect();
Some(MailboxInfo { pid: mb.pid, names, depth: depth.min(u32::MAX as usize) as u32 })
}
}
/// Is `pid` a live actor right now? Atomic slot-word read; no lock.