Struct Proc 

pub struct Proc { /* private fields */ }

A proc instance is the runtime managing a single proc in Hyperactor. It is responsible for spawning actors in the proc, multiplexing messages to/within actors in the proc, and providing fallback routing to external procs.

Procs are also responsible for maintaining the local supervision hierarchy.

Implementations

impl Proc

pub fn configured(proc_id: ProcId, forwarder: BoxedMailboxSender) -> Self

Create a pre-configured proc with the given proc id and forwarder.

pub fn direct(addr: ChannelAddr, name: String) -> Result<Self, ChannelError>

Create a new direct-addressed proc.

pub fn set_supervision_coordinator( &self, port: PortHandle<ActorSupervisionEvent>, ) -> Result<(), Error>

Set the supervision coordinator’s port for this proc. Return Err if it is already set.

pub fn handle_unhandled_supervision_event( &self, cx: &impl Actor, event: ActorSupervisionEvent, )

Handle a supervision event received by the proc. Attempt to forward it to the supervision coordinator port if one is set, otherwise crash the process.

pub fn local() -> Self

Create a new local-only proc. This proc is not allowed to forward messages outside of the proc itself.

pub fn proc_id(&self) -> &ProcId

The proc’s ID.

pub fn forwarder(&self) -> &BoxedMailboxSender

Shared sender used by the proc to forward messages to remote destinations.

pub fn attach(&self, name: &str) -> Result<Mailbox, Error>

Attach a mailbox to the proc with the provided root name.

pub fn attach_child(&self, parent_id: &ActorId) -> Result<Mailbox, Error>

Attach a mailbox to the proc as a child actor.

pub fn attach_actor<R, M>( &self, name: &str, ) -> Result<(Instance<()>, ActorRef<R>, PortReceiver<M>), Error>

where M: RemoteMessage, R: Referable + RemoteHandles<M>,

Attach a mailbox to the proc with the provided root name, and bind an [ActorRef]. This is intended only for testing, and will be replaced by simpled utilities.

pub fn spawn<A: Actor>( &self, name: &str, actor: A, ) -> Result<ActorHandle<A>, Error>

Spawn a named (root) actor on this proc. The name of the actor must be unique.

pub fn instance( &self, name: &str, ) -> Result<(Instance<()>, ActorHandle<()>), Error>

Create a lightweight client instance (no actor loop, no introspect task). This is safe to call outside a Tokio runtime — unlike [actor_instance], it never calls tokio::spawn.

pub fn introspectable_instance( &self, name: &str, ) -> Result<(Instance<()>, ActorHandle<()>), Error>

Create a lightweight client instance that handles IntrospectMessage.

Like instance, this creates a client-mode instance with no actor message loop. Unlike instance, it spawns a dedicated introspect task, so the instance responds to IntrospectMessage::Query and is visible and navigable in admin tooling such as the mesh TUI.

See CI-1, CI-2 in module doc.

Requires an active Tokio runtime (calls tokio::spawn).

pub fn actor_instance<A: Actor>( &self, name: &str, ) -> Result<ActorInstance<A>, Error>

Create and return an actor instance, its handle, and its receivers. This allows actors to be “inverted”: the caller can use the returned Instance to send and receive messages, launch child actors, etc. The actor itself does not handle any messages unless driven by the caller.

pub fn traverse<F>(&self, f: &mut F)

where F: FnMut(&InstanceCell, usize),

Traverse all actor trees in this proc, starting from root actors (pid=0).

Caution: This holds DashMap shard read locks while doing Weak::upgrade() and recursively walking the actor tree per entry. Under rapid actor churn, this causes convoy starvation with concurrent insert/remove operations. Prefer all_instance_keys() with point lookups if you only need actor IDs. Currently unused in production code.

pub fn get_instance(&self, actor_id: &ActorId) -> Option<InstanceCell>

Look up an instance by ActorId.

pub fn root_actor_ids(&self) -> Vec<ActorId>

Returns the ActorIds of all root actors (pid=0) in this proc.

Caution: This iterates the full DashMap under shard read locks. The per-entry work is lightweight (key filter + clone), but under very rapid churn the iteration can still contend with concurrent writes. Prefer all_instance_keys() with a post-filter if this becomes a hot path. Currently unused in production code.

pub fn all_actor_ids(&self) -> Vec<ActorId>

Returns the ActorIds of all live actors in this proc, including dynamically spawned children.

An actor is considered live if its weak reference is upgradeable and its status is not terminal. This excludes actors whose InstanceCell has been dropped and actors that have stopped or failed but whose Arc is still held (e.g. by the introspect task during teardown).

pub fn all_instance_keys(&self) -> Vec<ActorId>

Snapshot all instance keys from the DashMap without inspecting values. Each shard read lock is held only long enough to clone the key — no Weak::upgrade(), no watch::borrow(), no is_terminal() check. This minimises shard lock hold time to avoid convoy starvation with concurrent insert/remove operations during rapid actor churn.

The returned list may include actors that are terminal or whose WeakInstanceCell no longer upgrades. Callers should tolerate stale entries (e.g. by handling “not found” on subsequent per-actor lookups).

pub fn terminated_snapshot( &self, actor_id: &ActorId, ) -> Option<IntrospectResult>

Look up a terminated actor’s snapshot by ID.

pub fn all_terminated_actor_ids(&self) -> Vec<ActorId>

Return all terminated actor IDs currently retained.

pub fn abort_root_actor( &self, root: &ActorId, this_handle: Option<&JoinHandle<()>>, ) -> Option<impl Future<Output = ActorId>>

Call abort on the JoinHandle associated with the given root actor. If successful return Some(root.clone()) else None.

pub fn stop_actor( &self, actor_id: &ActorId, reason: String, ) -> Option<Receiver<ActorStatus>>

Signals to a root actor to stop, returning a status observer if successful.

pub async fn destroy_and_wait<A: Actor>( &mut self, timeout: Duration, cx: Option<&Context<'_, A>>, reason: &str, ) -> Result<(Vec<ActorId>, Vec<ActorId>), Error>

Stop the proc. Returns a pair of:

• the actors observed to stop;
• the actors not observed to stop when timeout.

If cx is specified, it means this method was called from inside an actor in which case we shouldn’t wait for it to stop and need to delay aborting its task.

pub async fn destroy_and_wait_except_current<A: Actor>( &mut self, timeout: Duration, cx: Option<&Context<'_, A>>, except_current: bool, reason: &str, ) -> Result<(Vec<ActorId>, Vec<ActorId>), Error>

Stop the proc. Returns a pair of:

• the actors observed to stop;
• the actors not observed to stop when timeout.

If cx is specified, it means this method was called from inside an actor in which case we shouldn’t wait for it to stop and need to delay aborting its task. If except_current is true, don’t stop the actor represented by “cx” at all.

pub fn resolve_actor_ref<R: Actor + Referable>( &self, actor_ref: &ActorRef<R>, ) -> Option<ActorHandle<R>>

Resolve an actor reference to a live actor on this proc.

Returns None if:

• the actor was never spawned here,
• the actor’s InstanceCell has been dropped, or
• the actor’s status is terminal (stopped or failed).

The terminal-status check guards a race window: the introspect task (serve_introspect) holds a strong InstanceCell Arc and drops it only after observing terminal status. Between the actor reaching terminal and the introspect task reacting, upgrade() on the weak ref succeeds even though the actor is dead. The is_terminal() check closes that window. Once the introspect task exits, the Arc is dropped and upgrade() returns None on its own.

Bounds:

• R: Actor — must be a real actor that can live in this proc.
• R: Referable — required because the input is an ActorRef<R>.

pub fn downgrade(&self) -> WeakProc

Downgrade to a weak reference that doesn’t prevent the proc from being dropped.

Trait Implementations

impl Clone for Proc

fn clone(&self) -> Proc

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Proc

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl MailboxSender for Proc

fn post_unchecked( &self, envelope: MessageEnvelope, return_handle: PortHandle<Undeliverable<MessageEnvelope>>, )

Raw transport: no policy.

fn post( &self, envelope: MessageEnvelope, return_handle: PortHandle<Undeliverable<MessageEnvelope>>, )

Apply hop semantics (TTL decrement; undeliverable on 0), then delegate to transport.