kameo

Actor linking provides peer-to-peer monitoring between actors, independent of the parent-child supervision hierarchy. This is useful when actors need to monitor each other or when you need cross-node monitoring.

By default, if a linked actor dies, the linked peer will also stop. However, you can intercept this by implementing the on_link_died method in your Actor implementation. Returning ControlFlow::Continue(()) allows the actor to keep running, while ControlFlow::Break(reason) causes it to stop.

async fn on_link_died(
    &mut self,
    _actor_ref: WeakActorRef<Self>,
    id: ActorId,
    reason: ActorStopReason,
) -> Result<ControlFlow<ActorStopReason>, Self::Error> {
    tracing::warn!("linked actor {id} died: {reason:?}");
    Ok(ControlFlow::Continue(()))  // Keep running
}

Kameo uses a Kademlia DHT (Distributed Hash Table) to manage actor registration without a centralized server.

• Registration: When ActorRef::register is called, the actor's name is stored as a key in the DHT, and the value is a reference to the actor on its host node. This name is then propagated across the network.
• Lookup: When a node performs a lookup, the DHT retrieves the location of the actor from the network and returns the reference.

Each node in the swarm stores a portion of the DHT, ensuring efficient discovery across the entire network.

Kameo is built on the Actor model, where the primary building blocks are Actors. An Actor encapsulates its own state and behavior, acting as an independent, concurrent unit.

Key characteristics of Actors:

• State Isolation: Actors isolate state, preventing direct access from other parts of the system.
• Asynchronous Processing: Actors handle messages asynchronously.
• Fault Tolerance: Because actors are isolated, they can fail and recover without destabilizing the entire system.

Use bootstrap() or bootstrap_on() when:

• You are in development or testing phases.
• You are prototyping distributed actor logic.
• You are deploying on local networks where mDNS discovery is sufficient.
• You want a zero-config setup with sensible defaults.

Use Custom Swarm Configuration when:

• You need custom transports (e.g., WebSocket, memory).
• You require different discovery mechanisms (e.g., custom bootstrap peers instead of mDNS).
• You need to integrate with an existing libp2p application.
• You need custom security, authentication, or connection management policies.
• You are preparing for production deployments where mDNS limitations (local network only) are a factor.

Kameo leverages the Tokio runtime to manage actor execution:

• Async Nature: Actors are asynchronous, allowing many actors to run on a single thread efficiently, which is ideal for IO-bound tasks. Non-blocking network operations can proceed without stalling other actors.
• Parallelism: By enabling the rt-multi-thread feature in the Tokio runtime, Kameo can utilize multiple CPU cores to distribute actors and handle parallel workloads.
• Sequential Processing: Within a single actor, messages are processed sequentially. This ensures state changes occur in a well-defined order, maintaining consistency and correctness.

Supervision trees establish parent-child relationships where a supervisor actor automatically manages the lifecycle of its children. If a child actor fails (via panic, error, or exit), the supervisor uses a configured SupervisionStrategy to decide whether to restart the child, other siblings, or all children. This allows for building resilient, self-healing systems following the Erlang/OTP model.

impl Actor for MySupervisor {
    // ...
    fn supervision_strategy() -> SupervisionStrategy {
        SupervisionStrategy::OneForOne
    }
    // ...
}

Kameo is designed for distributed systems and uses libp2p for networking.

Key networking concepts:

• Actor Registration & Lookup: Uses Kademlia Distributed Hash Table (DHT).
• Routing: Messages are routed using multiaddresses, supporting protocols like TCP/IP and QUIC.
• Remote Communication: Actors communicate across nodes via RemoteActorRef. Unlike gRPC, Kameo does not require predefined schemas or code generation for cross-node communication, allowing for more dynamic interactions.