Struct RactorRuntime 

pub struct RactorRuntime { /* private fields */ }

A dactor v0.2 runtime backed by ractor.

Actors are spawned as real ractor actors via ractor::Actor::spawn. Messages are delivered through ractor’s mailbox as type-erased dispatch envelopes, supporting multiple Handler<M> impls per actor.

System Actors

The runtime spawns native ractor system actors on creation:

• SpawnManagerActor — handles remote spawn requests
• WatchManagerActor — handles remote watch/unwatch
• CancelManagerActor — handles remote cancellation
• NodeDirectoryActor — tracks peer connections

System actors are accessible via system_actor_refs() for transport routing.

Implementations

impl RactorRuntime

pub const ADAPTER_NAME: &'static str = "ractor"

The adapter name for this runtime, used in version handshakes.

pub fn new() -> Self

Create a new RactorRuntime.

System actors are not spawned until start_system_actors() is called. This allows the runtime to be constructed outside a tokio context.

pub fn with_node_id(node_id: NodeId) -> Self

Create a new RactorRuntime with a specific node ID.

pub fn with_app_version(self, version: impl Into<String>) -> Self

Set the application version for this node.

This is your application’s release version (e.g., “2.3.1”), not the dactor framework version. It is included in handshake requests for operational visibility during rolling upgrades.

pub fn app_version(&self) -> Option<&str>

Returns the configured application version, if any.

pub fn handshake_request(&self) -> HandshakeRequest

Build a HandshakeRequest from this runtime’s current configuration.

pub async fn start_system_actors(&mut self)

Spawn native ractor system actors for transport routing.

Must be called from within a tokio runtime context. After this call, system_actor_refs() returns the native actor references.

Factory registrations made via register_factory() before this call are forwarded to the native SpawnManagerActor.

Uses default configuration (unbounded mailboxes, no pooling). For custom configuration, use [start_system_actors_with_config()].

pub async fn start_system_actors_with_config( &mut self, config: SystemActorConfig, )

Spawn native ractor system actors with custom configuration.

Allows configuring mailbox capacity and SpawnManager pooling for high-throughput scenarios. See SystemActorConfig for details.

Example

use dactor::system_actors::SystemActorConfig;
use dactor::mailbox::{MailboxConfig, OverflowStrategy};

let config = SystemActorConfig::default()
    .with_spawn_manager_mailbox(
        MailboxConfig::bounded(10_000, OverflowStrategy::Block)
    )
    .with_spawn_manager_pool_size(4)
    .with_control_plane_mailbox(
        MailboxConfig::bounded(5_000, OverflowStrategy::Block)
    );

runtime.start_system_actors_with_config(config).await;

pub fn node_id(&self) -> &NodeId

Returns the node ID of this runtime.

pub fn system_actor_refs(&self) -> Option<&RactorSystemActorRefs>

Access the native system actor references for transport routing.

Returns None if start_system_actors() has not been called yet.

pub fn add_outbound_interceptor( &mut self, interceptor: Box<dyn OutboundInterceptor>, )

Add a global outbound interceptor.

Must be called before any actors are spawned. Panics if actors already hold references to the interceptor list (i.e., after spawn()).

pub fn set_drop_observer(&mut self, observer: Arc<dyn DropObserver>)

Set a global drop observer that is notified whenever an outbound interceptor returns Disposition::Drop.

pub fn set_dead_letter_handler(&mut self, handler: Arc<dyn DeadLetterHandler>)

Set a global dead letter handler. Called whenever a message cannot be delivered (actor stopped, mailbox full, dropped by inbound interceptor).

pub fn cluster_events_handle(&self) -> &RactorClusterEvents

Access the cluster events subsystem.

pub fn cluster_events(&self) -> &RactorClusterEvents

Access the cluster events subsystem.

pub async fn spawn<A>( &self, name: &str, args: A::Args, ) -> Result<RactorActorRef<A>, RuntimeError>

where A: Actor<Deps = ()> + 'static,

Spawn an actor with Deps = ().

pub async fn spawn_with_deps<A>( &self, name: &str, args: A::Args, deps: A::Deps, ) -> Result<RactorActorRef<A>, RuntimeError>

where A: Actor + 'static,

Spawn an actor with explicit dependencies.

pub async fn spawn_with_options<A>( &self, name: &str, args: A::Args, options: SpawnOptions, ) -> Result<RactorActorRef<A>, RuntimeError>

where A: Actor<Deps = ()> + 'static,

Spawn an actor with spawn options (including inbound interceptors and mailbox config).

pub fn watch<W>(&self, watcher: &RactorActorRef<W>, target_id: ActorId)

where W: Actor + Handler<ChildTerminated> + 'static,

Register actor watcher to be notified when target_id terminates.

The watcher must implement Handler<ChildTerminated>. When the target stops, the runtime delivers a ChildTerminated message to the watcher.

pub fn unwatch(&self, watcher_id: &ActorId, target_id: &ActorId)

Unregister watcher_id from notifications about target_id.

pub fn spawn_manager(&self) -> &SpawnManager

Access the spawn manager.

pub fn spawn_manager_mut(&mut self) -> &mut SpawnManager

Access the spawn manager mutably (for registering actor factories).

pub fn register_factory( &mut self, type_name: impl Into<String>, factory: impl Fn(&[u8]) -> Result<Box<dyn Any + Send>, SerializationError> + Send + Sync + 'static, )

Register an actor type for remote spawning on this node.

Registers the factory in both the struct-based SpawnManager and the native SpawnManagerActor (if started via start_system_actors()).

pub fn handle_spawn_request( &mut self, request: &SpawnRequest, ) -> Result<(ActorId, Box<dyn Any + Send>), SpawnResponse>

Process a remote spawn request.

Looks up the actor type in the registry, deserializes Args from bytes, and returns the constructed actor along with its assigned ActorId.

The returned ActorId is pre-assigned for the remote spawn flow where the runtime controls ID assignment. The caller must use this ID when registering the spawned actor (not via the regular spawn() path, which assigns its own IDs).

Note: Currently uses the simple factory API (TypeRegistry::create_actor). For actors with non-trivial Deps, use spawn_manager_mut() to access TypeRegistry::create_actor_with_deps() directly.

Returns Ok((actor_id, actor)) on success, or Err(SpawnResponse::Failure) if the type is not found or deserialization fails.

pub fn watch_manager(&self) -> &WatchManager

Access the watch manager (for remote watch subscriptions).

pub fn watch_manager_mut(&mut self) -> &mut WatchManager

Access the watch manager mutably.

pub fn remote_watch(&mut self, target: ActorId, watcher: ActorId)

Register a remote watch: a remote watcher wants to know when a local actor terminates.

pub fn remote_unwatch(&mut self, target: &ActorId, watcher: &ActorId)

Remove a remote watch subscription.

pub fn notify_terminated( &mut self, terminated: &ActorId, ) -> Vec<WatchNotification>

Called when a local actor terminates. Returns notifications for all remote watchers that should be sent to their respective nodes.

Note: This must be called explicitly by the integration layer. It is not yet automatically wired into ractor’s actor stop lifecycle.

pub fn cancel_manager(&self) -> &CancelManager

Access the cancel manager.

pub fn cancel_manager_mut(&mut self) -> &mut CancelManager

Access the cancel manager mutably.

pub fn register_cancel(&mut self, request_id: String, token: CancellationToken)

Register a cancellation token for a request (for remote cancel support).

pub fn cancel_request(&mut self, request_id: &str) -> CancelResponse

Process a remote cancellation request.

pub fn complete_request(&mut self, request_id: &str)

Clean up a cancellation token after its request completes normally.

Should be called when a remote ask/stream/feed completes successfully to prevent stale tokens from accumulating.

pub fn node_directory(&self) -> &NodeDirectory

Access the node directory.

pub fn node_directory_mut(&mut self) -> &mut NodeDirectory

Access the node directory mutably.

pub fn connect_peer(&mut self, peer_id: NodeId, address: Option<String>)

Register a peer node as connected in the directory.

Post-validation only: this method assumes the peer has already passed the version handshake. Callers should validate compatibility (via handshake_request + validate_handshake + verify_peer_identity) before calling this method. Direct calls bypass compatibility checks.

If the peer already exists, updates its status to Connected and preserves the existing address when address is None. Emits a ClusterEvent::NodeJoined if the peer was not previously connected.

pub fn disconnect_peer(&mut self, peer_id: &NodeId)

Mark a peer as disconnected.

Emits a ClusterEvent::NodeLeft if the peer was previously connected.

pub fn is_peer_connected(&self, peer_id: &NodeId) -> bool

Check if a peer node is connected.

pub async fn await_stop(&self, actor_id: &ActorId) -> Result<(), String>

Wait for an actor to stop.

Returns Ok(()) when the actor finishes cleanly, or Err if the actor panicked in on_stop. The stop receiver is consumed and removed from the map.

Returns Ok(()) immediately if no stop receiver is stored for this ID (e.g., actor was already awaited or was not spawned by this runtime).

pub async fn await_all(&self) -> Result<(), String>

Wait for all spawned actors to stop.

Drains all stored stop receivers and awaits them all. Returns the first error encountered, but always waits for every actor to finish.

pub fn cleanup_finished(&self)

Remove completed stop receivers from the map.

Call periodically to prevent stale entries from accumulating for actors that stopped without being awaited.

pub fn active_handle_count(&self) -> usize

Number of actors with stored stop receivers.

Note: includes receivers for actors that have already stopped but haven’t been awaited or cleaned up. Call cleanup_finished() first for an accurate count of running actors.

Trait Implementations

impl Default for RactorRuntime

fn default() -> Self

Returns the “default value” for a type.

impl SystemMessageRouter for RactorRuntime

fn route_system_envelope<'life0, 'async_trait>( &'life0 self, envelope: WireEnvelope, ) -> Pin<Box<dyn Future<Output = Result<RoutingOutcome, RoutingError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Route a system message envelope to the appropriate system actor.