Struct EngineHandle 

pub struct EngineHandle<R: Reactor = TokioReactor, N: Network = TokioNetwork, F: FileSystem = TokioFileSystem> { /* private fields */ }

Handle for interacting with the engine from external (test) code.

Implementations

impl<R: Reactor, N: Network, F: FileSystem> EngineHandle<R, N, F>

pub fn type_registry(&self) -> TypeRegistry

pub fn send_to<M: Message>( &self, target: AddrHash, msg: M, ) -> Result<(), SendError>

Send a message to an actor by its AddrHash.

Fast path: after the first send to a local actor, the MailboxSender is cached in send_cache, bypassing the TransportRegistry DashMap on subsequent sends. Stale entries are evicted on ActorStopped.

pub fn send_many<M: Message + Clone>( &self, target: AddrHash, msg: M, n: usize, ) -> Result<usize, SendError>

Send up to n messages to one target using a producer-side batch fast path.

For local destinations this uses MailboxSender::try_send_batch_owned, reducing wake/schedule overhead vs repeated send_to calls.

Returns the number of messages successfully enqueued. On local mailbox backpressure this may be less than n without returning an error.

pub fn addr_for<M: Message>(&self, target: AddrHash) -> Addr<M>

where R: Send + Sync,

Create an Addr<M> that sends to target via this engine’s transport.

pub fn remote_addr<M: RemoteMessage>(&self, target: AddrHash) -> Addr<M>

Create a remote Addr<M> that always serializes payloads before routing.

This is intended for explicit remote sends; it rejects local destinations to avoid accidental local delivery of serialized payloads.

pub fn remote_addr_for<M: RemoteMessage>(&self, target: AddrHash) -> Addr<M>

where M::Response: Serialize + for<'de> Deserialize<'de> + Send + 'static, R: Clone + Send + Sync,

Create a typed remote Addr<M> that supports both send() and ask().

Both request and response payloads are serialized for transport delivery. Local destinations are rejected with AskError::Send(PolicyViolation).

Before calling, register the message type on both engines:

handle.type_registry().register_remote_ask::<MyMsg>();

The first ask() on the returned address lazily starts the engine’s response pump task (a lightweight background task that routes incoming serialized response frames into the local response registry).

pub fn transport(&self) -> &Arc<InProcessTransport>

pub fn transport_registry(&self) -> &Arc<TransportRegistry>

pub async fn attach_quic_transport( &self, config: QuicTransportConfig, peers: HashMap<EngineId, SocketAddr>, ) -> Result<Arc<QuicTransport<R, N>>, TransportError>

where R: Clone, N: Clone,

pub async fn attach_tcp_transport( &self, config: TcpTransportConfig, peers: HashMap<EngineId, SocketAddr>, ) -> Result<Arc<TcpTransport<R, N>>, TransportError>

where R: Clone, N: Clone,

pub async fn attach_bounded_cluster( &self, config: BoundedClusterConfig, ) -> Result<BoundedClusterHandle<R, N, F>, ClusterError>

where R: Clone, N: Clone,

pub fn remote_addr_for_path<M: RemoteMessage>( &self, path: &ActorPath, ) -> Addr<M>

where M::Response: Serialize + for<'de> Deserialize<'de> + Send + 'static, R: Clone + Send + Sync,

Create a typed remote Addr<M> from a canonical actor path.

The cross-engine routing key is AddrHash::new(path, 0), which is the canonical distributed identity for a logical actor path.

pub fn remote_stable_addr_for_path<M: RemoteMessage>( &self, path: &ActorPath, ) -> StableAddr<M>

where M::Response: Serialize + for<'de> Deserialize<'de> + Send + 'static, R: Clone + Send + Sync,

Create a stable typed remote handle from a canonical actor path.

This v1 API makes the logical remote identity stable by path. It does not provide remote restart notifications or continuous liveness tracking. During remote absence or re-advertisement windows, callers may still observe the same transient failures as remote_addr_for_path(), such as Unroutable, ConnectionFailed, or Timeout.

pub fn actor_list(&self, query: ActorQuery) -> Vec<ActorInfo>

List actors, optionally filtered by query.

pub fn actor_info(&self, path: &ActorPath) -> Option<ActorInfo>

Get info for a single actor by path.

pub fn snapshot(&self) -> EngineSnapshot

System-level snapshot: all actors + uptime.

pub fn lookup_path(&self, path: &ActorPath) -> Option<AddrHash>

Lookup an actor’s address by its path.

pub fn resolve_path(&self, path: &ActorPath) -> Result<AddrHash, SendError>

Resolve an actor’s address by path with routing errors.

pub fn stop_actor(&self, path: &ActorPath) -> bool

Send a hard-stop signal to an actor by path.

Returns true if the actor was found and the signal was sent. The actor may still be running until the signal is processed by the reactor. Used by FaultInjector::crash_actor.

pub fn fill_mailbox(&self, path: &ActorPath) -> usize

Fill an actor’s mailbox to capacity by sending dummy messages.

Returns the number of messages that were successfully enqueued. Subsequent sends to the same actor will return SendError::MailboxFull until the actor drains messages. Used by FaultInjector::fill_mailbox.

pub fn spawn_user_actor(&self, spec: ChildSpec<R>)

Dynamically spawn a user actor by sending a signal to the root /user supervisor.

pub fn spawn_worker_pool<M, G>( &self, config: &PoolConfig, factory: G, ) -> WorkerPool<M>

where M: Message, R: Clone + Send + Sync + 'static, G: Fn() -> Box<dyn Actor<R>> + Send + Sync + Clone + 'static,

Spawn a pool of N identical worker actors under the /user supervisor and return a WorkerPool<M> routing handle.

Each worker gets a StableAddr<M> backed by an [AddrRefresher] so that the pool transparently routes to new incarnations after restarts.

Ordering

Spawn requests are sent asynchronously to the /user supervisor. The returned pool’s StableAddrs are initially None; they are populated once the supervisor task processes each SpawnChild signal. Yield at least once (e.g. tokio::task::yield_now().await) before sending messages through the pool.

Panics

Panics if config.size is 0 (no workers requested).

Trait Implementations

impl<R: Clone + Reactor, N: Clone + Network, F: Clone + FileSystem> Clone for EngineHandle<R, N, F>

fn clone(&self) -> EngineHandle<R, N, F>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.