Struct WorkerPool 

pub struct WorkerPool<M: Message> { /* private fields */ }

A supervision-aware, round-robin routing handle for a pool of identical worker actors.

Created by [EngineHandle::spawn_worker_pool]. Workers are spawned and supervised by the /user supervisor; this struct is a thin routing facade over N StableAddr<M>s that remain valid across individual worker restarts.

Routing semantics

• Round-robin: each call to send or ask selects the next worker in rotation.
• Shared counter across clones: all clones share the rotation counter (Arc<AtomicUsize>), so concurrent senders interleave rather than duplicate.
• Backpressure: SendError::MailboxFull is returned immediately when the selected worker’s mailbox is at capacity.
• Restart window: SendError::Unroutable is returned during the brief interval between a worker crash and the supervisor refreshing its StableAddr. The window is transient; callers should yield and retry.

In-flight message loss

Messages that were already in a crashed worker’s mailbox at crash time are lost (best-effort semantics). Full at-least-once delivery requires application-level acknowledgement — outside the scope of this primitive.

Implementations

impl<M: Message> WorkerPool<M>

pub fn new(workers: Vec<StableAddr<M>>) -> Self

Create a pool handle from a pre-built list of StableAddr<M>.

Called by the runtime builder; not intended for direct use in application code.

Panics

Panics if workers is empty.

pub fn send(&self, msg: M) -> Result<(), SendError>

Round-robin fire-and-forget send to one worker.

Advances the rotation counter and calls StableAddr::send on the selected worker. Does not retry on Unroutable; callers that need retry-on-crash semantics should yield and call send again.

Errors

• SendError::MailboxFull — the selected worker’s mailbox is full.
• SendError::Unroutable — the worker is between crash and restart.

pub async fn ask(&self, msg: M) -> Result<M::Response, AskError>

Round-robin request/response.

Selects one worker and awaits its reply. AskError::Send(Unroutable) may be returned during a crash window; callers decide retry.

pub fn size(&self) -> usize

Number of worker slots in the pool.

pub fn workers_ready_count(&self) -> usize

Number of workers whose StableAddr has been populated by the supervisor (i.e., the worker has been spawned at least once).

Useful in tests and health checks to wait until all workers are live before sending messages.

pub fn worker_addr(&self, index: usize) -> Option<AddrHash>

Current AddrHash of the worker at index, or None if the worker has not yet been spawned or is in the crash/restart window.

Index is stable (slot 0 always refers to {prefix}-0); the hash changes on each restart as a new generation is assigned.

Trait Implementations

impl<M: Message> Clone for WorkerPool<M>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.