Reference">

Reference

The Reference enum is a type-erased, unified representation of all addressable entities in hyperactor. It provides a common format for parsing, logging, routing, and transport.

#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, Hash, Named)]
pub enum Reference {
    World(WorldId),
    Proc(ProcId),
    Actor(ActorId),
    Port(PortId),
    Gang(GangId),
}

Each variant wraps one of the concrete identifier types:

• WorldId

• ProcId

• ActorId

• PortId

• GangId

Use Cases

• Used to represent references in a uniform way (e.g., CLI args, config, logs).

• Returned by .parse::<Reference>() when parsing from string.

• Enables prefix-based comparisons for routing or scoping.

• Can be converted to/from the concrete types via From.

Construction

From concrete types:

use hyperactor::reference::{Reference, ActorId};

let actor_id = ...;
let reference: Reference = actor_id.into();

From a string:

let reference: Reference = "training[0].logger[1][42]".parse().unwrap();

You can match on the reference to access the underlying type:

match reference {
    Reference::Actor(actor_id) => { /* ... */ }
    Reference::Port(port_id) => { /* ... */ }
    _ => {}
}

Methods

impl Reference {
    pub fn is_prefix_of(&self, other: &Reference) -> bool;
    pub fn world_id(&self) -> &WorldId;
    pub fn proc_id(&self) -> Option<&ProcId>;
    pub fn actor_id(&self) -> Option<&ActorId>;
    pub fn actor_name(&self) -> Option<&str>;
    pub fn pid(&self) -> Option<usize>;
    pub fn port(&self) -> Option<u64>;
}

• .is_prefix_of(other) checks whether one reference is a prefix of another (e.g., WorldId -> ProcId -> ActorId).

• .world_id() returns the reference’s associated world.

• .proc_id() and .actor_id() return their corresponding IDs if applicable.

• .actor_name(), .pid(), and .port() expose reference components across variants.

Ordering

Reference implements a total order across all variants. Ordering is defined lexicographically:

(world_id, rank, actor_name, pid, port)

This allows references to be used in sorted maps or for prefix-based routing schemes.

Traits

Reference implements:

• Display — formats to the same syntax accepted by FromStr

• FromStr — parses strings like "world[1].actor[2][port]"

• Ord, Eq, Hash — useful in sorted/routed contexts

• Named — used for port assignment, reflection, and runtime dispatch