Nexus API Reference

WorkerPool
in package

FinalYes
Tags
psalm-api

Fluent builder for a Swoole thread-based worker pool.

Usage:

WorkerPool::withThreads(8)
    ->withName('shop')
    ->actor('orders', OrderActor::class)
    ->behavior('pings', static fn (): Behavior => Behavior::receive(
        static fn (ActorContext $ctx, object $msg): Behavior => Behavior::same()
    ))
    ->run();

Thread safety: closures passed to behavior() and configure() MUST be static and capture only serializable values. Class-string actors (actor(), stateful()) are always thread-safe — only strings cross thread boundaries.

Table of Contents

Methods

actor()  : self
Register a class-based actor (implements ActorHandler).
behavior()  : self
Register a behavior-based actor via a factory closure.
configure()  : self
Full control: receive the WorkerNode directly to spawn actors, wire dependencies, etc. The closure MUST be static.
onStart()  : self
Register a main-thread callback to run after all workers are ready.
run()  : void
Boot the worker pool. Blocks until the pool exits.
stateful()  : self
Register a stateful class-based actor (implements StatefulActorHandler).
withCpuThreads()  : self
Create a pool with one thread per CPU core (swoole_cpu_num()).
withLogger()  : self
Inject a PSR-3 logger by class name. Each thread calls new $loggerClass().
withLoggerFactory()  : self
Inject a PSR-3 logger via factory closure. Each thread deserializes and calls the factory to create its own logger instance.
withName()  : self
Set the actor system name prefix. Each worker system is named "{prefix}-{workerId}".
withThreads()  : self
Create a pool with an explicit thread count.

Methods

actor()

Register a class-based actor (implements ActorHandler).

public actor(string $name, ActorHandler> $actorClass[, MailboxConfig|null $mailbox = null ]) : self

The class is instantiated fresh in each thread via Props::fromFactory.

Parameters
$name : string
$actorClass : ActorHandler>
$mailbox : MailboxConfig|null = null
Return values
self

behavior()

Register a behavior-based actor via a factory closure.

public behavior(string $name, callable(): Behavior<string|int, T> $factory[, MailboxConfig|null $mailbox = null ]) : self

The factory MUST be static. Example: ->behavior('pings', static fn (): Behavior => Behavior::receive( static fn (ActorContext $ctx, object $msg): Behavior => Behavior::same() ))

Parameters
$name : string
$factory : callable(): Behavior<string|int, T>
$mailbox : MailboxConfig|null = null
Tags
template

T of object

Return values
self

configure()

Full control: receive the WorkerNode directly to spawn actors, wire dependencies, etc. The closure MUST be static.

public configure(callable(WorkerNode): void $setup) : self
Parameters
$setup : callable(WorkerNode): void
Return values
self

onStart()

Register a main-thread callback to run after all workers are ready.

public onStart(callable(WorkerPoolHandle): void $callback) : self

The closure receives a WorkerPoolHandle for message injection and stopping.

IMPORTANT: This callback runs in the main thread (not serialized — no opis needed). The closure does NOT need to be static and can capture any values. Call $handle->stop() when done, or simply return (stop is called automatically).

Parameters
$callback : callable(WorkerPoolHandle): void
Return values
self

run()

Boot the worker pool. Blocks until the pool exits.

public run() : void

stateful()

Register a stateful class-based actor (implements StatefulActorHandler).

public stateful(string $name, StatefulActorHandler> $actorClass[, MailboxConfig|null $mailbox = null ]) : self
Parameters
$name : string
$actorClass : StatefulActorHandler>
$mailbox : MailboxConfig|null = null
Return values
self

withCpuThreads()

Create a pool with one thread per CPU core (swoole_cpu_num()).

public static withCpuThreads() : self
Return values
self

withLogger()

Inject a PSR-3 logger by class name. Each thread calls new $loggerClass().

public withLogger(LoggerInterface> $loggerClass) : self

The class must have a no-argument constructor.

Parameters
$loggerClass : LoggerInterface>
Return values
self

withLoggerFactory()

Inject a PSR-3 logger via factory closure. Each thread deserializes and calls the factory to create its own logger instance.

public withLoggerFactory(callable(): LoggerInterface $factory) : self

The closure MUST be static and capture only serializable values.

Parameters
$factory : callable(): LoggerInterface
Return values
self

withName()

Set the actor system name prefix. Each worker system is named "{prefix}-{workerId}".

public withName(string $name) : self

Default: "worker" → "worker-0", "worker-1", …

Parameters
$name : string
Return values
self

withThreads()

Create a pool with an explicit thread count.

public static withThreads(int $count) : self
Parameters
$count : int
Return values
self 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results