WorkerNode
in package
Per-worker coordinator within a local worker pool.
Each worker thread in a WorkerPoolApp owns exactly one WorkerNode. The node
holds the thread-local ActorSystem, consults the ConsistentHashRing
to decide which worker owns a given actor name, and routes cross-worker messages
via the WorkerTransport without serialization (Swoole's Thread\Queue
copies objects between threads internally).
Typical usage is indirect — you implement WorkerStartHandler and call
$node->spawn() inside onWorkerStart() to register the actors that live on
this worker. The framework then wires message routing automatically.
Example — registering actors in a worker start handler:
final class MyWorkerStart implements WorkerStartHandler
{
public function onWorkerStart(WorkerNode $node): void
{
$node->spawn(Props::fromBehavior($orderBehavior), 'orders');
$node->spawn(Props::fromBehavior($paymentBehavior), 'payments');
$node->start(); // begin listening for inbound transport envelopes
}
}
Tags
Table of Contents
Methods
- __construct() : mixed
- actorFor() : ActorRef<string|int, object>|null
- Look up an actor by path, returning a local or remote ref.
- askRemote() : Future<string|int, R>
- Send a request-response ask to an actor on a remote worker and return a Future.
- spawn() : ActorRef<string|int, T>
- Spawn an actor, routing to local or remote based on the hash ring.
- start() : void
- Start listening for incoming transport envelopes.
- system() : ActorSystem
- Returns the underlying ActorSystem.
- workerId() : int
- Returns this node's worker ID.
Methods
__construct()
public
__construct(int $workerId, ActorSystem $system, WorkerTransport $transport, ConsistentHashRing $ring, WorkerDirectory $directory) : mixed
Parameters
- $workerId : int
- $system : ActorSystem
- $transport : WorkerTransport
- $ring : ConsistentHashRing
- $directory : WorkerDirectory
actorFor()
Look up an actor by path, returning a local or remote ref.
public
actorFor(string $path) : ActorRef<string|int, object>|null
Returns null if the actor is not known to the directory.
Parameters
- $path : string
Return values
ActorRef<string|int, object>|nullaskRemote()
Send a request-response ask to an actor on a remote worker and return a Future.
public
askRemote(ActorPath $targetPath, int $targetWorker, object $message, Duration $timeout) : Future<string|int, R>
Transmits a WorkerAskRequest envelope to the target worker, registers a
timeout that rejects the future on expiry, and schedules automatic retries
(up to ASK_RETRY_MAX_ATTEMPTS) until the target worker acknowledges
receipt. The future resolves when the target actor replies; it fails with
AskTimeoutException if the timeout elapses before a reply arrives.
This method is called internally by WorkerActorRef::ask() and is exposed publicly so that custom transport adapters can invoke it directly.
Parameters
- $targetPath : ActorPath
-
Path of the actor to ask.
- $targetWorker : int
-
Worker ID that owns the target actor.
- $message : object
-
The request message to send (not serialized).
- $timeout : Duration
-
Maximum time to wait for a reply.
Tags
Return values
Future<string|int, R>spawn()
Spawn an actor, routing to local or remote based on the hash ring.
public
spawn(Props<string|int, T> $props, string $name) : ActorRef<string|int, T>
If the hash ring assigns the actor name to this worker, the actor is spawned locally via the ActorSystem. Otherwise, a WorkerActorRef is returned that routes messages via the transport.
Parameters
- $props : Props<string|int, T>
- $name : string
Tags
Return values
ActorRef<string|int, T>start()
Start listening for incoming transport envelopes.
public
start() : void
Incoming envelopes are delivered directly (no deserialization) to the target local actor's mailbox via enqueueEnvelope().
system()
Returns the underlying ActorSystem.
public
system() : ActorSystem
Return values
ActorSystemworkerId()
Returns this node's worker ID.
public
workerId() : int