Struct CoerceRuntime 

pub struct CoerceRuntime { /* private fields */ }

A dactor v0.2 runtime backed by coerce-rs.

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

Note: CoerceRuntime::new() creates a coerce::actor::system::ActorSystem internally, which requires a tokio runtime context. All spawn() methods also require a tokio context.

System Actors

The runtime includes struct-based system actors for remote operations:

• SpawnManager — handles remote actor spawn requests
• WatchManager — handles remote watch/unwatch subscriptions
• CancelManager — handles remote cancellation requests
• NodeDirectory — tracks peer node connection state

Native coerce system actors are accessible via system_actor_refs() for transport routing after calling start_system_actors().

Implementations

impl CoerceRuntime

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

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

pub fn new() -> Self

Create a new CoerceRuntime.

Requires a tokio runtime context — ActorSystem::new() spawns the coerce scheduler as a tokio task.

pub fn with_node_id(node_id: NodeId) -> Self

Create a new CoerceRuntime with a specific node ID.

Requires a tokio runtime context.

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 fn node_id(&self) -> &NodeId

Returns the node ID of this runtime.

pub fn system(&self) -> &ActorSystem

Returns a reference to the underlying coerce ActorSystem.

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 the drop observer for outbound interceptor pipelines.

Must be called before any actors are spawned.

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) -> &CoerceClusterEvents

Access the cluster events subsystem.

pub fn cluster_events(&self) -> &CoerceClusterEvents

Access the cluster events subsystem.

pub fn start_system_actors(&mut self)

Spawn native coerce 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.

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

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

Spawn native coerce system actors with custom configuration.

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

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

Access the native system actor references for transport routing.

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

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

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

Spawn an actor with Deps = ().

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

where A: Actor + Send + Sync + 'static,

Spawn an actor with explicit dependencies.

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

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

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

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

where W: Actor + Handler<ChildTerminated> + Send + Sync + '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 coerce’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.

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 CoerceRuntime

fn default() -> Self

Returns the “default value” for a type.

impl SystemMessageRouter for CoerceRuntime

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.