Module registry 

Thread-local actor registry with lifetime-safe access guards.

Design

The actor registry stores actors in thread-local storage and provides access via ActorRef<T> guards. This design addresses several constraints:

• Use-after-free prevention: ActorRef holds an Rc clone, keeping the actor alive even if removed from the registry while the guard exists.
• Re-entrant callbacks: Message handlers frequently call back into the registry to access other actors. Unlike RefCell-style borrow tracking, multiple ActorRef guards can exist simultaneously without panicking.
• No 'static lifetime lie: Previous designs returned &'static mut T, which didn’t reflect actual validity. The guard-based approach ties the borrow to the guard’s lifetime.

Limitations

• Aliasing not prevented: Two guards can exist for the same actor simultaneously, allowing aliased mutable access. This is technically undefined behavior but is required by the re-entrant callback pattern. Higher-level discipline is required.
• Thread-local only: Guards must not be sent across threads.

Invariants

These contracts must hold regardless of how the registry is implemented internally. The first three are verified by tests in this module. The fourth is a usage discipline enforced by convention.

• Thread isolation: Each thread has its own registry instance. An actor registered on one thread is never visible from another.
• Guard survival: An ActorRef keeps its actor alive via reference counting. Removing or replacing an actor in the registry does not invalidate existing guards.
• Type safety: get_actor_unchecked and try_get_actor_unchecked verify the concrete type at runtime before casting. A type mismatch panics or returns None, respectively.
• Short-lived guards: Guards must be obtained, used, and dropped within a single synchronous scope. Never store an ActorRef in a struct or hold one across an .await point.

Structs

ActorRef

A guard providing mutable access to an actor.

ActorRegistry

Registry for storing actors.

Functions

actor_count

Returns the number of registered actors.

actor_exists

Checks if an actor with the id exists in the registry.

get_actor

get_actor_registry

get_actor_unchecked

Returns a guard providing mutable access to the registered actor of type T.

register_actor

Registers an actor.

try_get_actor_unchecked

Attempts to get a guard providing mutable access to the registered actor.