books: hyperactor-book: typed refs (#425)

Summary:
Pull Request resolved: #425

finish off references section with "typed references" sub-section

Reviewed By: mariusae

Differential Revision: D77744864

fbshipit-source-id: 0dc46aab71df39ebb3a7e0fe0b84064593e01d7c

Author: shayne-fletcher

books/hyperactor-book/src/SUMMARY.md

@@ -9,9 +9,7 @@
   - [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) -->
+  - [Typed References](references/typed_refs.md)
 - [Mailboxes and Routers](mailboxes/index.md)
   - [Ports](mailboxes/ports.md)
   - [MailboxSender](mailboxes/mailbox_sender.md)

books/hyperactor-book/src/actors/handler.md

@@ -7,7 +7,7 @@ Each message type that an actor can handle must be declared by implementing this
 ```rust
 #[async_trait]
 pub trait Handler<M>: Actor {
-    async fn handle(&mut self, this: &Context<Self>, message: M) -> Result<(), anyhow::Error>;
+    async fn handle(&mut self, cx: &Context<Self>, message: M) -> Result<(), anyhow::Error>;
 }
 ```
 
@@ -32,7 +32,7 @@ This is a marker implementation indicating that all actors can receive `Signal`.
 impl<A: Actor> Handler<Signal> for A {
     async fn handle(
         &mut self,
-        _this: &Context<Self>,
+        _cx: &Context<Self>,
         _message: Signal,
     ) -> Result<(), anyhow::Error> {
         unimplemented!("signal handler should not be called directly")
@@ -51,7 +51,7 @@ where
 {
     async fn handle(
         &mut self,
-        this: &Context<Self>,
+        cx: &Context<Self>,
         msg: IndexedErasedUnbound<M>,
     ) -> anyhow::Result<()> {
         let message = msg.downcast()?.bind()?;

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

@@ -21,6 +21,4 @@ In this section, we’ll cover:
   - [`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 -->
+  - [Typed references](typed_refs.md) used in APIs: `ActorRef<A>`, `PortRef<M>`, and `OncePortRef<M>`

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

@@ -1 +1,103 @@
 # Typed References
+
+Typed references are strongly typed wrappers over raw identifiers like `ActorId` and `PortId`. These types are used throughout hyperactor’s APIs; as parameters in messages, return values from `bind()` methods, and elements in routing decisions. They make distributed communication safe, expressive, and statically checked.
+
+## Overview
+
+There are three main typed reference types:
+
+- [`ActorRef<A>`](#actorrefa): A typed reference to an actor implementing the `RemoteActor` trait.
+- [`PortRef<M>`](#portrefm): A reference to a reusable mailbox port for messages of type `M`.
+- [`OncePortRef<M>`](#onceportrefm): A reference to a one-shot port for receiving a single response of type `M`.
+
+These types are used as parameters in messages, return values from bindings, and components of the routing system.
+
+---
+
+## `ActorRef<A>`
+
+`ActorRef<A>` is a typed reference to an actor of type `A`. It provides a way to identify and address remote actors that implement `RemoteActor`.
+
+```rust
+let actor_ref: ActorRef<MyActor> = ActorRef::attest(actor_id);
+```
+
+Unlike `ActorHandle<A>`, an `ActorRef` is just a reference — it doesn’t guarantee that the actor is currently running. It's primarily used for routing and type-safe messaging across `Proc`s.
+
+### Definition
+```rust
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+pub struct ActorRef<A: RemoteActor> {
+    actor_id: ActorId,
+    phantom: PhantomData<A>,
+}
+```
+This type is a thin wrapper around an `ActorId`, with a phantom type `A` to track which actor it refers to. It ensures you can only send messages supported by the actor's declared `RemoteHandles`.
+
+## `PortRef<M>`
+
+`PortRef<M>` refers to a mailbox port for messages of type `M`.
+```rust
+let (port, mut receiver) = actor.open_port::<MyMessage>();
+let port_ref: PortRef<MyMessage> = port.bind();
+```
+
+This allows the port to be sent across the network or passed into other messages. On the receiving end, `PortRef` can be used to deliver messages of the expected type.
+
+### Definition
+
+```rust
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+pub struct PortRef<M: Message> {
+    port_id: PortId,
+    phantom: PhantomData<M>,
+}
+```
+As with `ActorRef`, this is a typed wrapper around a raw identifier (`PortId`), carrying a phantom type for safety. It ensures that only messages of type `M` can be sent through this reference.
+
+## `OncePortRef<M>`
+
+A `OncePortRef<M>` is like a `PortRef`, but designed for exactly one response. Once used, it cannot be reused or cloned.
+```rust
+let (once_port, receiver) = actor.open_once_port::<MyMessage>();
+let once_ref = once_port.bind();
+```
+These are commonly used for request/response interactions, where a single reply is expected.
+
+### Definition
+
+```rust
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+pub struct OncePortRef<M: Message> {
+    port_id: PortId,
+    phantom: PhantomData<M>,
+}
+```
+Just like `PortRef`, this wraps a `PortId` with a phantom message type `M` for type safety. Internally, the system enforces one-time delivery semantics, ensuring the port is closed after receiving a single message.
+
+## `GangRef<A>`
+
+A `GangRef<A>` is a typed reference to a gang of actors, all of which implement the same `RemoteActor` type `A`.
+```rust
+let gang_ref: GangRef<MyActor> = GangId::new(...).into();
+```
+You can extract an `ActorRef<A>` for a specific rank in the gang:
+```rust
+let actor = gang_ref.rank(0); // ActorRef<MyActor>
+```
+This allows you to route messages to specific members of a replicated actor group, or to iterate over the gang for broadcasting, synchronization, or indexing.
+
+### Definition
+```rust
+#[derive(Debug, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Hash, Ord)]
+pub struct GangRef<A: RemoteActor> {
+    gang_id: GangId,
+    phantom: PhantomData<A>,
+}
+```
+
+#### Methods
+- `gang_ref.rank(rank: usize) -> ActorRef<A>`
+Returns a typed actor reference for the actor at the given rank in the gang. The method doesn’t validate the rank, so correctness is up to the caller.
+- `gang_ref.gang_id() -> &GangId`
+Returns the underlying, untyped gang identifier.