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 legacy_local_pseudo_singleton( addr: ChannelAddr, forwarder: BoxedMailboxSender, ) -> Self

Create the legacy host-local client proc pseudo-singleton.

pub fn legacy_service_pseudo_singleton( addr: ChannelAddr, forwarder: BoxedMailboxSender, ) -> Self

Create the legacy host system proc pseudo-singleton.

pub fn anonymous() -> Self

Create a proc with an anonymous instance id on the default gateway.

pub fn instance(label: impl AsRef<str>) -> Self

Create a proc with an instance id and display label on the default gateway.

pub fn singleton(name: impl AsRef<str>) -> Self

Create a proc with a singleton id on the default gateway.

pub fn isolated() -> Self

Create a proc with a random id on a fresh local-only gateway.

pub fn builder() -> Builder

Create a proc builder.

pub fn configured( proc_id: impl Into<ProcAddr>, 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.

The provided name is a display label. Direct procs are otherwise independent instances, so each one receives a unique proc id.

pub async fn attach_to_host(addr: ChannelAddr) -> Result<Self, Error>

Connect to a host’s duplex server and return a Proc whose identity is assigned by the host. Outbound messages are forwarded over the duplex channel; inbound messages are served into the proc’s muxer. Mirrors Proc::direct but the identity and routing are managed by the remote host.

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 supervision_coordinator_actor_addr(&self) -> Option<&ActorAddr>

The actor address of the supervision coordinator, if one is set and lives on this proc.

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 proc_id(&self) -> &ProcId

The proc’s runtime identity.

pub fn default_location(&self) -> Location

The proc’s default advertised location.

pub fn set_default_location(&self, location: Location)

Set the proc’s default advertised location.

pub fn proc_addr(&self) -> ProcAddr

The proc’s routeable address using its default advertised location.

pub fn gateway(&self) -> Gateway

The proc’s connectivity boundary.

pub fn forwarder(&self) -> &BoxedMailboxSender

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

pub fn muxer(&self) -> &MailboxMuxer

The proc’s mailbox muxer, which routes messages to actors registered on this proc.

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: &ActorAddr) -> 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 ActorAddr. 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 spawn_with_uid<A: Actor>( &self, uid: Uid, actor: A, ) -> Result<ActorHandle<A>, Error>

Spawn a root actor on this proc using an explicit uid.

The uid must be unique among root actors on this proc. Instance labels, if present, are descriptive only and do not affect uniqueness.

pub fn client( &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 client, this creates a client-mode instance with no actor message loop. Unlike client, 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.

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 queue_depth_total(&self) -> u64

Proc-wide running total of queued work items.

pub fn queue_depth_high_water_mark(&self) -> u64

Maximum proc-wide queue depth observed since startup (PD-6).

pub fn last_nonzero_queue_depth_age_ms(&self) -> Option<u64>

How long ago proc-wide queue depth was last non-zero (PD-7).

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

Look up an instance by ActorAddr.

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

Look up an instance by ActorId.

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

Returns the ActorAddrs of all root actors 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<ActorAddr>

Returns the ActorAddrs 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 ids from the DashMap without inspecting values. Each shard read lock is held only long enough to clone the id — 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 ids (e.g. by handling “not found” on subsequent per-actor lookups).

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

Look up a terminated actor’s snapshot by ID.

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

Return all terminated actor IDs currently retained.

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

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( &mut self, timeout: Duration, reason: &str, ) -> Result<(Vec<ActorAddr>, Vec<ActorAddr>), Error>

Stop the proc. Returns a pair of:

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

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.

pub async fn flush(&self) -> Result<(), Error>

Flush the gateway so that any buffered messages are wire-delivered before the proc’s networking is torn down.

pub async fn join_mailbox_server(&self)

Stop and join the mailbox server, flushing receive-side acks.

This stops the MailboxServer::serve loop and awaits its completion, which runs Rx::join() to flush any pending transport-level acks before the channel is torn down.

No-op if no mailbox server handle is stored (e.g. for Proc::configured or Proc::isolated procs that don’t serve).

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 flush<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Wait until all messages previously posted through this sender have been delivered (wire-acked) or confirmed undeliverable. The default implementation is a no-op, appropriate for senders whose post is synchronous (e.g. local in-process delivery).

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

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