books: hyperactor-book: actor traits (#418)

Summary:
Pull Request resolved: #418

new section: actor traits.

Reviewed By: mariusae

Differential Revision: D77690728

fbshipit-source-id: 46c46730ab493e4a4a0ea40d8d5c73e2d63d70ff

Author: shayne-fletcher

books/hyperactor-book/src/SUMMARY.md

@@ -1,13 +1,6 @@
 # Summary
 
 - [Introduction](./introduction.md)
-- [Macros](macros/index.md)
-  - [`#[derive(Handler)]`](macros/handler.md)
-  - [`#[derive(HandleClient)]`](macros/handle_client.md)
-  - [`#[derive(RefClient)]`](macros/ref_client.md)
-  - [`#[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)
@@ -29,3 +22,18 @@
   - [Delivery Semantics](mailboxes/delivery.md)
   - [Multiplexers](mailboxes/multiplexer.md)
   - [Routers](mailboxes/routers.md)
+- [Actors](actors/index.md)
+  - [Actor](actors/actor.md)
+  - [Handler](actors/handler.md)
+  - [RemoteableActor](actors/remotable_actor.md)
+  - [Checkpointable](actors/checkpointable.md)
+  - [RemoteActor](actors/remote_actor.md)
+  - [Binds](actors/binds.md)
+  - [RemoteHandles](actors/remote_handles.md)
+- [Macros](macros/index.md)
+  - [`#[derive(Handler)]`](macros/handler.md)
+  - [`#[derive(HandleClient)]`](macros/handle_client.md)
+  - [`#[derive(RefClient)]`](macros/ref_client.md)
+  - [`#[derive(Named)]`](macros/named.md)
+  - [`#[export]`](macros/export.md)
+  - [`#[forward]`](macros/forward.md)

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

@@ -0,0 +1,169 @@
+# The `Actor` Trait
+
+The `Actor` trait defines the core behavior of all actors in the hyperactor runtime.
+
+Every actor type must implement this trait to participate in the system. It defines how an actor is constructed, initialized, and supervised.
+
+```rust
+#[async_trait]
+pub trait Actor: Sized + Send + Debug + 'static {
+    type Params: Send + 'static;
+
+    async fn new(params: Self::Params) -> Result<Self, anyhow::Error>;
+
+    async fn init(&mut self, _this: &Instance<Self>) -> Result<(), anyhow::Error> {
+        Ok(())
+    }
+
+    async fn spawn(
+        cap: &impl cap::CanSpawn,
+        params: Self::Params,
+    ) -> anyhow::Result<ActorHandle<Self>> {
+        cap.spawn(params).await
+    }
+
+    async fn spawn_detached(params: Self::Params) -> Result<ActorHandle<Self>, anyhow::Error> {
+        Proc::local().spawn("anon", params).await
+    }
+
+    fn spawn_server_task<F>(future: F) -> JoinHandle<F::Output>
+    where
+        F: Future + Send + 'static,
+        F::Output: Send + 'static,
+    {
+        tokio::spawn(future)
+    }
+
+    async fn handle_supervision_event(
+        &mut self,
+        _this: &Instance<Self>,
+        _event: &ActorSupervisionEvent,
+    ) -> Result<bool, anyhow::Error> {
+        Ok(false)
+    }
+
+    async fn handle_undeliverable_message(
+        &mut self,
+        this: &Instance<Self>,
+        Undeliverable(envelope): Undeliverable<MessageEnvelope>,
+    ) -> Result<(), anyhow::Error> {
+        assert_eq!(envelope.sender(), this.self_id());
+
+        anyhow::bail!(UndeliverableMessageError::delivery_failure(&envelope));
+    }
+}
+```
+
+## Construction: `Params` and `new`
+
+Each actor must define a `Params` type:
+
+```rust
+type Params: Send + 'static;
+```
+
+This associated type defines the data required to instantiate the actor.
+
+The actor is constructed by the runtime using:
+```rust
+async fn new(params: Self::Params) -> Result<Self, anyhow::Error>;
+```
+
+This method returns the actor's internal state. At this point, the actor has not yet been connected to the runtime; it has no mailbox and cannot yet send or receive messages. `new` is typically used to construct the actor's fields from its input parameters.
+
+## Initialization: `init`
+
+```rust
+async fn init(&mut self, this: &Instance<Self>) -> Result<(), anyhow::Error>
+```
+
+The `init` method is called after the actor has been constructed with `new` and registered with the runtime. It is passed a reference to the actor's `Instance`, allowing access to runtime services such as:
+- The actor’s ID and status
+- The mailbox and port system
+- Capabilities for spawning or sending messages
+
+The default implementation does nothing and returns `Ok(())`.
+
+If `init` returns an error, the actor is considered failed and will not proceed to handle any messages.
+
+Use `init` to perform startup logic that depends on the actor being fully integrated into the system.
+
+## Spawning: `spawn`
+
+The `spawn` method provides a default implementation for creating a new actor from an existing one:
+
+```rust
+async fn spawn(
+    cap: &impl cap::CanSpawn,
+    params: Self::Params,
+) -> anyhow::Result<ActorHandle<Self>> {
+    cap.spawn(params).await
+}
+```
+
+In practice, `CanSpawn` is only implemented for `Instance<A>`, which represents a running actor. As a result, `Actor::spawn(...)` always constructs a child actor: the new actor receives a child ID and is linked to its parent through the runtime.
+
+## Detached Spawning: `spawn_detached`
+
+```rust
+async fn spawn_detached(params: Self::Params) -> Result<ActorHandle<Self>, anyhow::Error> {
+    Proc::local().spawn("anon", params).await
+}
+```
+This method creates a root actor on a fresh, isolated proc.
+- The proc is local-only and cannot forward messages externally.
+- The actor receives a unique root `ActorId` with no parent.
+- No supervision or linkage is established.
+- The actor is named `"anon"`.
+
+## Background Tasks: `spawn_server_task`
+
+```rust
+fn spawn_server_task<F>(future: F) -> JoinHandle<F::Output>
+where
+    F: Future + Send + 'static,
+    F::Output: Send + 'static,
+{
+    tokio::spawn(future)
+}
+```
+
+This method provides a hook point for customizing how the runtime spawns background tasks.
+
+By default, it simply calls `tokio::spawn(...)` to run the given future on the Tokio executor.
+
+# Supervision Events: `handle_supervision_event`
+
+```rust
+async fn handle_supervision_event(
+    &mut self,
+    _this: &Instance<Self>,
+    _event: &ActorSupervisionEvent,
+) -> Result<bool, anyhow::Error> {
+    Ok(false)
+}
+```
+This method is invoked when the runtime delivers an `ActorSupervisionEvent` to the actor — for example, when a child crashes or exits.
+
+By default, it returns `Ok(false)`, which indicates that the event was not handled by the actor. This allows the runtime to fall back on default behavior (e.g., escalation).
+
+Actors may override this to implement custom supervision logic.
+
+## Undeliverables: `handle_undeliverable_message`
+
+```rust
+async fn handle_undeliverable_message(
+    &mut self,
+    this: &Instance<Self>,
+    Undeliverable(envelope): Undeliverable<MessageEnvelope>,
+) -> Result<(), anyhow::Error> {
+    assert_eq!(envelope.sender(), this.self_id());
+
+    anyhow::bail!(UndeliverableMessageError::delivery_failure(&envelope));
+}
+```
+This method is called when a message sent by this actor fails to be delivered.
+- It asserts that the message was indeed sent by this actor.
+- Then it returns an error: `Err(UndeliverableMessageError::DeliveryFailure(...))`
+
+This signals that the actor considers this delivery failure to be a fatal error. You may override this method to suppress the failure or to implement custom fallback behavior.

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

@@ -0,0 +1,31 @@
+# Binds
+
+The `Binds` trait defines how an actor's ports are associated with the message types it can receive remotely.
+```rust
+pub trait Binds<A: Actor>: RemoteActor {
+    fn bind(ports: &Ports<A>);
+}
+```
+Implementing `Binds<A>` allows the system to determine which messages can be routed to an actor instance of type `A`.
+
+## Code Generation
+
+In most cases, you do not implement this trait manually. Instead, the `#[export]` macro generates the appropriate `Binds<A>` implementation by registering the actor's supported message types.
+
+For example:
+```rust
+#[hyperactor::export(
+    spawn = true,
+    handlers = [ShoppingList],
+)]
+struct ShoppingListActor;
+```
+Expands to:
+```rust
+impl Binds<ShoppingListActor> for ShoppingListActor {
+    fn bind(ports: &Ports<Self>) {
+        ports.bind::<ShoppingList>();
+    }
+}
+```
+This ensures that the actor is correctly wired to handle messages of type `ShoppingList` when used in a remote messaging context.

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

@@ -0,0 +1,58 @@
+# Checkpointable
+
+The `Checkpointable` trait enables an actor to define how its internal state can be saved and restored. This allows actors to participate in checkpointing and recovery mechanisms when supported by the surrounding system.
+
+## Trait definition
+```rust
+#[async_trait]
+pub trait Checkpointable: Send + Sync + Sized {
+    type State: RemoteMessage;
+
+    async fn save(&self) -> Result<Self::State, CheckpointError>;
+    async fn load(state: Self::State) -> Result<Self, CheckpointError>;
+}
+```
+
+## Associated Type
+
+- `type State`: A serializable type representing the object's saved state. This must implement `RemoteMessage` so it can serialized and transmitted.
+
+## `save`
+
+Persists the current state of the component. Returns the Returns a `Self::State` value. If the operation fails, returns `CheckpointError::Save`.
+
+## `load`
+
+Reconstructs a new instance from a previously saved `Self::State`. If deserialization or reconstruction fails, returns `CheckpointError::Load`.
+
+## `CheckpointError`
+
+Errors returned by save and load operations:
+```rust
+pub enum CheckpointError {
+    Save(anyhow::Error),
+    Load(SeqId, anyhow::Error),
+}
+```
+
+## Blanket Implementation
+
+Any type `T` that implements `RemoteMessage` and `Clone` automatically satisfies `Checkpointable`:
+```rust
+#[async_trait]
+impl<T> Checkpointable for T
+where
+    T: RemoteMessage + Clone,
+{
+    type State = T;
+
+    async fn save(&self) -> Result<Self::State, CheckpointError> {
+        Ok(self.clone())
+    }
+
+    async fn load(state: Self::State) -> Result<Self, CheckpointError> {
+        Ok(state)
+    }
+}
+```
+This implementation uses `clone()` to produce a checkpoint and simply returns the cloned state in load.

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

@@ -0,0 +1,70 @@
+# The `Handler` Trait
+
+The `Handler` trait defines how an actor receives and responds to messages of a specific type.
+
+Each message type that an actor can handle must be declared by implementing this trait. The runtime invokes the `handle` method when such a message is delivered.
+
+```rust
+#[async_trait]
+pub trait Handler<M>: Actor {
+    async fn handle(&mut self, this: &Context<Self>, message: M) -> Result<(), anyhow::Error>;
+}
+```
+
+## Message Dispatch: `handle`
+
+The `handle` method is invoked by the runtime whenever a message of type `M` arrives at a matching port on the actor.
+- message is the received payload.
+- this gives access to the actor's runtime context, including its identity, mailbox, and and any capabilities exposed by the `Instance` type (such as spawning or reference resolution).
+- The return value indicates whether the message was handled successfully.
+
+An actor may implement `Handler<M>` multiple times — once for each message type `M` it supports.
+
+## Built-in Handlers
+
+The runtime provides implementations of `Handler<M>` for a few internal message types:
+
+### `Handler<Signal>`
+
+This is a marker implementation indicating that all actors can receive `Signal`. The handler is not expected to be invoked directly — its real behavior is implemented inside the runtime.
+```rust
+#[async_trait]
+impl<A: Actor> Handler<Signal> for A {
+    async fn handle(
+        &mut self,
+        _this: &Context<Self>,
+        _message: Signal,
+    ) -> Result<(), anyhow::Error> {
+        unimplemented!("signal handler should not be called directly")
+    }
+}
+```
+
+### `Handler<Undeliverable<MessageEnvelope>>`
+
+```rust
+#[async_trait]
+impl<A, M> Handler<IndexedErasedUnbound<M>> for A
+where
+    A: Handler<M>,
+    M: Castable,
+{
+    async fn handle(
+        &mut self,
+        this: &Context<Self>,
+        msg: IndexedErasedUnbound<M>,
+    ) -> anyhow::Result<()> {
+        let message = msg.downcast()?.bind()?;
+        Handler::handle(self, this, message).await
+    }
+}
+```
+This implementation allows an actor to transparently handle erased, rebound messages of type `M`, provided it already implements `Handler<M>`.
+
+This construct is used in the implementation of **accumulation**, a communication pattern where a message is multicast to multiple recipients and their replies are gathered—possibly through intermediate actors—before being sent back to the original sender.
+
+To enable this, messages are unbound at the sender: reply ports (`PortRef`s) are extracted into a `Bindings` object, allowing intermediate nodes to rewrite those ports to point back to themselves. This ensures that replies from downstream actors are routed through the intermediate, enabling reply collection and reduction.
+
+Once a message reaches its destination, it is rebound by merging the updated bindings back into the message. The `Handler<IndexedErasedUnbound<M>>` implementation automates this by recovering the typed message `M` and dispatching it to the actor's existing `Handler<M>` implementation.
+
+This allows actors to remain unaware of accumulation mechanics—they can just implement `Handler<M>` as usual.

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

@@ -0,0 +1,17 @@
+# Actors
+
+Hyperactor programs are structured around actors: isolated state machines that process messages asynchronously.
+
+Each actor runs in isolation, and maintains private internal state. Actors interact with the outside world through typed message ports and follow strict lifecycle semantics managed by the runtime.
+
+This chapter introduces the actor system in hyperactor. We'll cover:
+
+- The [`Actor`](./actor.md) trait and its lifecycle hooks
+- The [`Handler`](./handler.md) trait for defining message-handling behavior
+- The [`RemotableActor`](./remotable_actor.md) trait for enabling remote spawning
+- The [`Checkpointable`](./checkpointable.md) trait for supporting actor persistence and recovery
+- The [`RemoteActor`](./remote_actor.md) marker trait for remotely referencable types
+- The [`Binds`](./binds.md) trait for wiring exported ports to reference types
+- The [`RemoteHandles`](./remote_handles.md) trait for associating message types with a reference
+
+Actors are always instantiated with parameters and bound to a mailbox, enabling them to participate in reliable message-passing systems. Supervision, checkpointing, and references all build upon this core abstraction.