books: hyperactor-book: references (#398)

Summary:
Pull Request resolved: #398

new section detailing the hyperactor reference types

Reviewed By: mariusae

Differential Revision: D77613398

fbshipit-source-id: 97cfbff249dd6bc814b9efb196073dbfb7f0775d

Author: shayne-fletcher

books/hyperactor-book/src/SUMMARY.md

@@ -8,6 +8,17 @@
   - [`#[derive(Named)]`](macros/named.md)
   - [`#[export]`](macros/export.md)
   - [`#[forward]`](macros/forward.md)
+- [References](references/index.md)
+  - [Syntax](references/syntax.md)
+  - [WorldId](references/world_id.md)
+  - [ProcId](references/proc_id.md)
+  - [ActorId](references/actor_id.md)
+  - [PortId](references/port_id.md)
+  - [GangId](references/gang_id.md)
+  - [Reference](references/reference.md)
+  <!-- - [Typed References](references/typed_refs.md) -->
+  <!-- - [Gangs](references/gangs.md) -->
+  <!-- - [Bindings](references/bindings.md) -->
 - [Mailboxes and Routers](mailboxes/index.md)
   - [Ports](mailboxes/ports.md)
   - [MailboxSender](mailboxes/mailbox_sender.md)

books/hyperactor-book/src/references/actor_id.md

@@ -0,0 +1,87 @@
+# `ActorId`
+
+An `ActorId` uniquely identifies an actor within a proc. It combines the proc the actor lives on, a string name, and a numeric pid (process-local instance index).
+
+```rust
+#[derive(
+    Debug,
+    Serialize,
+    Deserialize,
+    Clone,
+    PartialEq,
+    Eq,
+    PartialOrd,
+    Hash,
+    Ord,
+    Named
+)]
+pub struct ActorId(pub ProcId, pub String, pub usize);
+```
+- The first field is the actor's `ProcId`.
+- The second is the actor's name (used for grouping and logging).
+- The third is the pid, which distinguishes multiple instances with the same name.
+
+### Construction
+
+Construct an actor ID directly:
+```rust
+use hyperactor::reference::{ActorId, ProcId, WorldId};
+
+let proc = ProcId(WorldId("training".into()), 0);
+let actor = ActorId(proc, "worker".into(), 1);
+```
+
+Or with the `id!` macro:
+```rust
+use hyperactor::id;
+
+let actor = id!(training[0].worker[1]);
+// Equivalent to ActorId(ProcId(WorldId("training".into()), 0), "worker".into(), 1)
+```
+To refer to the root actor (the canonical instance), use:
+```rust
+let root = ActorId::root(proc, "worker".into());
+// Equivalent to ActorId(proc, "worker".into(), 0)
+```
+
+### Methods
+
+```rust
+impl ActorId {
+    pub fn proc_id(&self) -> &ProcId;
+    pub fn name(&self) -> &str;
+    pub fn pid(&self) -> usize;
+    pub fn world_name(&self) -> &str;
+    pub fn rank(&self) -> usize;
+    pub fn child_id(&self, pid: usize) -> Self;
+    pub fn port_id(&self, port: u64) -> PortId;
+    pub fn root(proc: ProcId, name: String) -> Self;
+}
+```
+
+- `.proc_id()` returns the ProcId that owns this actor.
+- `.name()` returns the logical name of the actor (e.g., "worker").
+- `.pid()` returns the actor's instance ID.
+- `.world_name()` returns the name of the actor’s world.
+- `.rank()` returns the proc rank (i.e., index) this actor runs on.
+- `.child_id(pid)` creates a new `ActorId` with the same name and proc but a different pid.
+- `.port_id(port)` returns a `PortId` representing a port on this actor.
+- `.root(proc, name)` constructs a new root actor (`pid = 0`) in the given proc.
+
+### Traits
+
+`ActorId` implements:
+
+- `Display` — formats as `world[rank].name[pid]`
+- `FromStr` — parses strings like `"training[0].logger[1]"`
+- `Clone`, `Eq`, `Ord`, `Hash` — useful in maps, sets, and registries
+- `Named` — enables type-based routing, port lookup, and reflection
+
+## Semantics
+
+- The `name` groups actors logically within a proc (e.g., `"worker"`, `"trainer"`).
+- The `pid` distinguishes physical instances:
+  - `pid = 0` represents the **root** actor instance.
+  - `pid > 0` typically corresponds to **child actors** spawned by the root.
+- Most routing and API surfaces operate on root actors by default.
+- Port creation is always rooted in an `ActorId`, via `.port_id(...)`.

books/hyperactor-book/src/references/bindings.md

@@ -0,0 +1 @@
+# Bindings

books/hyperactor-book/src/references/gang_id.md

@@ -0,0 +1,67 @@
+# `GangId`
+
+A `GangId` identifies a logical group of actors with the same name across all procs in a world. It serves as a convenient shorthand for referring to all root instances of a given actor name.
+```rust
+#[derive(
+    Debug,
+    Serialize,
+    Deserialize,
+    Clone,
+    PartialEq,
+    Eq,
+    PartialOrd,
+    Hash,
+    Ord,
+    Named
+)]
+pub struct GangId(pub WorldId, pub String);
+```
+- The first field is the WorldId.
+- The second field is the shared actor name.
+
+A `GangId` is conceptually like saying: “the actor named X on every proc in world W.”
+
+## Construction
+
+```rust
+use hyperactor::reference::{GangId, WorldId};
+
+let gang = GangId(WorldId("training".into()), "logger".into());
+```
+
+Or using the id! macro:
+```rust
+use hyperactor::id;
+
+let gang = id!(training.logger);
+// Equivalent to GangId(WorldId("training".into()), "logger".into())
+```
+
+## Methods
+
+```rust
+impl GangId {
+    pub fn world_id(&self) -> &WorldId;
+    pub fn name(&self) -> &str;
+    pub fn actor_id(&self, rank: usize) -> ActorId;
+    pub fn expand(&self, world_size: usize) -> impl Iterator<Item = ActorId> + '_;
+}
+```
+- `.world_id()` returns the world this gang is defined in.
+- `.name()` returns the shared actor name (e.g., "logger").
+- `.actor_id(rank)` returns the root actor on that proc.
+- `.expand(world_size)` yields all root ActorIds from rank `0..world_size`.
+
+## Semantics
+
+- Gangs are always composed of root actors (`pid = 0`) with a common name.
+- Gang references are useful for broadcasting, coordination, or actor discovery.
+- They are lightweight and purely name-based; no state is attached to a `GangId`.
+
+## Traits
+
+`GangId` implements:
+- `Display` — formatted as world.actor
+- `FromStr` — parses from strings like "training.logger"
+- `Ord`, `Eq`, `Hash` — usable in maps, registries, and routing
+- `Named` — enables type registration and metadata lookup

books/hyperactor-book/src/references/gangs.md

@@ -0,0 +1 @@
+# Gangs

books/hyperactor-book/src/references/index.md

@@ -0,0 +1,26 @@
+# References
+
+This section documents the reference system used throughout hyperactor to identify and communicate with distributed entities.
+
+References are lightweight, serializable identifiers for **worlds**, **procs**, **actors** **ports**, and **gangs**. They are the backbone of addressing and routing in the runtime. Whether you're sending a message, spawning an actor, or broadcasting to a group, references are how you name things.
+
+The reference system is:
+
+- **Uniform**: All references follow a shared syntax and structure.
+- **Parsable**: References can be round-tripped from strings and manipulated programmatically.
+- **Typed**: While the `Reference` enum is typeless and dynamic, typed references like `ActorRef<A>` and `PortRef<M>` allow safe interaction in APIs.
+- **Orderable**: References implement a total order, enabling prefix-based routing and sorted maps.
+
+In this section, we’ll cover:
+
+- The [syntax](syntax.md) and string format of references
+- The core reference types:
+  - [`WorldId`](world_id.md)
+  - [`ProcId`](proc_id.md)
+  - [`ActorId`](actor_id.md)
+  - [`PortId`](port_id.md)
+  - [`GangId`](gang_id.md)
+- The [Reference](reference.md), which unifies all reference variants
+<!-- - [Typed references](typed_refs.md) used in APIs: `ActorRef<A>`, `PortRef<M>`, and `OncePortRef<M>` -->
+<!-- - The semantics of [gangs](gangs.md), which represent replicated actors across ranks -->
+<!-- - How references participate in [bindings](bindings.md) and serialization -->

books/hyperactor-book/src/references/port_id.md

@@ -0,0 +1,61 @@
+# `PortId`
+
+A `PortId` identifies a specific port on a particular actor. Ports are the entry points through which messages are delivered to an actor, and each `PortId` is globally unique.
+
+```rust
+#[derive(
+    Debug,
+    Serialize,
+    Deserialize,
+    Clone,
+    PartialEq,
+    Eq,
+    PartialOrd,
+    Hash,
+    Ord,
+    Named
+)]
+pub struct PortId(pub ActorId, pub u64);
+```
+- The first field is the owning `ActorId`.
+- The second field is the port number (`u64`), typically derived from the message type’s registered port.
+
+## Construction
+
+```rust
+use hyperactor::reference::{PortId, ActorId};
+
+let port = PortId(actor, 42);
+```
+Or via the `id!` macro:
+```rust
+use hyperactor::id;
+
+let port = id!(training[0].logger[1][42]);
+// Equivalent to PortId(ActorId(...), 42)
+```
+You can also construct a PortId from an `ActorId` using `.port_id(...)`:
+```rust
+let port = actor.port_id(42);
+```
+
+## Methods
+
+```rust
+impl PortId {
+    pub fn actor_id(&self) -> &ActorId;
+    pub fn index(&self) -> u64;
+    pub fn into_actor_id(self) -> ActorId;
+}
+```
+- `.actor_id()` returns the owning actor.
+- `.index()` returns the port number.
+- `.into_actor_id()` discards the port index and yields the owning actor ID.
+
+## Traits
+
+`PortId` implements:
+- `Display` — formatted as `world[rank].actor[pid][port]`
+- `FromStr` — parses from strings like `"training[0].logger[1][42]"`
+- `Ord`, `Eq`, `Hash` — usable as map keys or for dispatch
+- `Named` — supports reflection and typed messaging

books/hyperactor-book/src/references/proc_id.md

@@ -0,0 +1,59 @@
+# `ProcId`
+
+A `ProcId` identifies a single runtime instance within a world. All actors exist within a proc, and message routing between actors is scoped by the proc’s identity.
+```rust
+#[derive(
+    Debug,
+    Serialize,
+    Deserialize,
+    Clone,
+    PartialEq,
+    Eq,
+    PartialOrd,
+    Hash,
+    Ord,
+    Named
+)]
+pub struct ProcId(pub WorldId, pub usize);
+```
+
+## Construction
+
+You can construct a `ProcId` directly:
+```rust
+use hyperactor::reference::{WorldId, ProcId};
+
+let proc = ProcId(WorldId("training".into()), 0);
+```
+Or statically using the `id!` macro:
+```rust
+use hyperactor::id;
+
+let proc = id!(training[0]); // Equivalent to ProcId(WorldId("training".into()), 0)
+```
+
+## Methods
+
+```rust
+impl ProcId {
+    pub fn world_id(&self) -> &WorldId;
+    pub fn world_name(&self) -> &str;
+    pub fn rank(&self) -> usize;
+    pub fn actor_id(&self, name: impl Into<String>, pid: usize) -> ActorId;
+}
+```
+- `.world_id()` gives the `WorldId` this proc belongs to.
+- `.rank()` returns the proc’s index.
+- `.actor_id(name, pid)` constructs an `ActorId` for an actor hosted on this proc.
+
+# Notes
+
+Ranks greater than or equal to `1 << (usize::BITS - 1)` are considered user-space procs. These are typically created with `WorldId::random_user_proc()` and are not assigned by the system.
+
+## Traits
+
+ProcId implements:
+- `Display` — formatted as `world[rank]`
+- `FromStr` — parses from strings like "training[0]"
+- `Ord`, `Eq`, `Hash` — usable in maps and sorted structures
+- `Named` — enables port lookup and type reflection