Circular dependency problem with bidirectional actor communication

[ElFantasma]

Problem

When two actors need to collaborate bidirectionally (each sending messages to the other), Spawned's strongly-typed ActorRef<T> creates a circular module dependency that Rust rejects.

// actors/actor_a.rs
use crate::actors::actor_b::ActorB;  // ⚠️ imports actor_b

struct ActorA;

enum MsgA {
    SetPeer(ActorRef<ActorB>),  // Needs ActorB type
    FromB(String),
}

impl Actor for ActorA { type Message = MsgA; ... }

// actors/actor_b.rs  
use crate::actors::actor_a::ActorA;  // ⚠️ imports actor_a - CIRCULAR!

struct ActorB;

enum MsgB {
    SetPeer(ActorRef<ActorA>),  // Needs ActorA type
    FromA(String),
}

impl Actor for ActorB { type Message = MsgB; ... }

Rust will reject this - circular module dependencies are not allowed.

Current Workarounds

1. Shared Message Type (what ping_pong example does)

// messages.rs - shared by both
enum Message {
    Ping { from: Sender<Message> },
    Pong,
}

// Both actors use the same Message type
impl Actor for ActorA { type Message = Message; ... }
impl Actor for ActorB { type Message = Message; ... }

Problem: Loses type safety - ActorA can receive messages meant for ActorB.

2. Pass Raw Sender Instead of ActorRef

enum MsgA {
    SetPeer(mpsc::Sender<MsgB>),  // Raw sender, not ActorRef
}

Problem: Loses ActorRef conveniences (cancellation token, join, etc.)

3. Put Both Actors in Same Module

Works but doesn't scale for large systems.

Proposed Solutions (Framework Changes)

Option A: Type-Erased Actor Handle

// A trait object that any ActorRef can become
trait AnyActor: Send {
    fn send_boxed(&self, msg: Box<dyn Any + Send>) -> Result<(), Error>;
}

enum MsgA {
    SetPeer(Arc<dyn AnyActor>),  // No concrete type needed
}

Option B: Generic Sender Trait (like Actix's Recipient)

trait MessageSender<M>: Send + Clone {
    fn send(&self, msg: M) -> Result<(), Error>;
}

// ActorRef<T> implements MessageSender<T::Message>
// Now messages can hold Arc<dyn MessageSender<SomeMsg>>

enum MsgA {
    SetPeer(Arc<dyn MessageSender<SharedMessage>>),
}

This is similar to Actix's Recipient<M> pattern - a type-erased handle that can send a specific message type M to any actor that handles M.

Option C: PID-like Addressing (Erlang style)

// Global registry with string/id-based addressing
enum MsgA {
    SetPeer(Pid),  // Just an ID, resolved at runtime
}

// Sending:
registry.send(pid, message)?;

This aligns with Phase 3 of the roadmap (Process Primitives with Registry).

Option D: Shared Protocol Trait

// Define a shared protocol both actors understand
trait PeerProtocol {
    fn notify(&self, msg: String) -> Result<(), Error>;
}

// Both ActorRef<A> and ActorRef<B> implement PeerProtocol
enum MsgA {
    SetPeer(Arc<dyn PeerProtocol + Send + Sync>),
}

Comparison with Other Frameworks

Framework	How It Solves This
Erlang	PIDs are untyped, messages are untyped - no compile-time deps
Akka	ActorRef[Any] or typed protocols with shared message traits
Actix	Addr<A> + Recipient<M> (type-erased for specific message)
Orleans	Interface-based grains, no circular deps by design

Actix's Recipient Pattern (Worth Studying)

// Actix allows type-erasing an Addr to just the message it can receive
let recipient: Recipient<MyMessage> = addr.recipient();

// Any actor handling MyMessage can be stored as Recipient<MyMessage>
struct MsgA {
    peer: Recipient<SharedMessage>,  // Works for any actor handling SharedMessage
}

Decision Criteria

• Preserve type safety where possible
• Minimize runtime overhead
• Keep API ergonomic
• Align with Erlang philosophy (or consciously diverge)

Related

• Phase 3 roadmap: Process Primitives (Pid, Registry) - v0.5 Roadmap Tracking Issue #138
• Type safety for request/reply - Improve type safety for request/reply message handling #144

[ElFantasma]

Decision: Actix-style Receiver trait (object-safe by design)

After analysis in PR #147, we identified that the original Receiver<M> trait design used RPITIT (-> impl Future<...>) for request(), which makes the trait not object-safe — meaning Arc<dyn Receiver<M>> (i.e. Recipient<M>) would not compile.

Chosen approach: Actix pattern

The Receiver trait only does synchronous channel plumbing. Async waiting happens outside the trait boundary via oneshot channels:

pub trait Receiver<M: Message>: Send + Sync {
    /// Fire-and-forget
    fn send(&self, msg: M) -> Result<(), ActorError>;

    /// Enqueue message, return oneshot receiver for the reply (synchronous)
    fn request(&self, msg: M) -> Result<oneshot::Receiver<M::Result>, ActorError>;
}

/// Object-safe because Receiver is
pub type Recipient<M> = Arc<dyn Receiver<M>>;

/// Async convenience wrapper on the concrete type (not on the trait)
impl<M: Message> Recipient<M> {
    pub async fn send_request(&self, msg: M) -> Result<M::Result, ActorError> {
        let rx = Receiver::request(&**self, msg)?;
        rx.await.map_err(|_| ActorError::ActorStopped)
    }
}

Why this works

• All Receiver methods return concrete types → trait is object-safe → dyn Receiver<M> compiles
• No async_trait dependency needed
• No heap-allocated boxed futures
• The exposed request() returning a raw oneshot::Receiver is useful for select!, timeouts, etc.
• send_request() provides the ergonomic .await path for the common case

Internals: Envelope pattern

On the actor side, ActorRef uses an envelope pattern (like Actix) so the single mailbox channel can carry any message type:

trait Envelope<A: Actor>: Send {
    fn handle(self: Box<Self>, actor: &mut A, ctx: &Context<A>);
}

pub struct ActorRef<A: Actor> {
    sender: mpsc::Sender<Box<dyn Envelope<A> + Send>>,
    ...
}

Updated in the API redesign plan: PR #147.