Nexus API Reference

ActorSystem
in package

FinalYes

Top-level container and entry point for spawning actors and driving the event loop.

An ActorSystem owns the root of the actor supervision tree (the "/user" guardian), holds the chosen Runtime implementation, and coordinates startup, message dispatch, and graceful shutdown. Each system is stamped with a unique Ulid writer id consumed by the persistence layer to enforce the single-writer principle. Typically one ActorSystem is created per process; multiple may coexist in tests with the deterministic StepRuntime.

Invariants:

Tags
example 
$system = ActorSystem::create('my-app', new FiberRuntime());
$ref    = $system->spawn(Props::fromBehavior($greeter), 'greeter');
$ref->tell(new Greet('world'));
$system->runtime()->scheduleOnce(Duration::seconds(1), fn () => $system->shutdown(Duration::seconds(2)));
$system->run();
see
Props

for spawn configuration (behavior, mailbox, supervision)

see
Runtime

for runtime backend selection (Fiber, Swoole, Step)

see
Behavior

for actor behavior definitions

see
ActorRef

for typed actor references

psalm-api

Table of Contents

Methods

clock()  : ClockInterface
create()  : self
Create a new ActorSystem with the given name and runtime.
deadLetters()  : DeadLetterRef
eventDispatcher()  : EventDispatcherInterface
isRunning()  : bool
liveActorCount()  : int
Number of alive root actors currently registered under the system.
name()  : string
run()  : void
Start the runtime event loop and block until the system shuts down.
runtime()  : Runtime
shutdown()  : void
Gracefully shut down the system within the given timeout.
spawn()  : ActorRef<string|int, T>
Spawn a named actor under the /user guardian and return its reference.
spawnAnonymous()  : ActorRef<string|int, T>
Spawn an anonymous actor with an auto-generated name under the /user guardian.
stop()  : void
Gracefully stop an actor by sending it a PoisonPill.
writerId()  : Ulid
Unique writer ULID for this actor system instance.

Methods

clock()

public clock() : ClockInterface
Return values
ClockInterface —

PSR-20 clock used for scheduler timestamps and persistence metadata.

create()

Create a new ActorSystem with the given name and runtime.

public static create(string $name, Runtime $runtime[, ClockInterface|null $clock = null ][, LoggerInterface|null $logger = null ][, EventDispatcherInterface|null $eventDispatcher = null ][, Observability|null $observability = null ]) : self

The system name is used as a namespace prefix in actor paths (e.g. /user/greeter). Optional dependencies default to a wall-clock, a NullLogger, and a no-op dispatcher.

Parameters
$name : string

A short identifier for this system; appears in actor paths and logs.

$runtime : Runtime

The concurrency backend (FiberRuntime, SwooleRuntime, StepRuntime).

$clock : ClockInterface|null = null

PSR-20 clock; defaults to wall-clock DateTimeImmutable.

$logger : LoggerInterface|null = null

PSR-3 logger; defaults to NullLogger.

$eventDispatcher : EventDispatcherInterface|null = null

PSR-14 dispatcher; defaults to no-op.

$observability : Observability|null = null
Return values
self —

A fresh system with a generated writer id and empty child registry.

eventDispatcher()

public eventDispatcher() : EventDispatcherInterface
Return values
EventDispatcherInterface —

PSR-14 dispatcher used to broadcast system-level events.

isRunning()

public isRunning() : bool
Return values
bool —

True while the underlying runtime's event loop is active.

liveActorCount()

Number of alive root actors currently registered under the system.

public liveActorCount() : int
Return values
int —

Count of root children whose actor is still alive.

run()

Start the runtime event loop and block until the system shuts down.

public run() : void

This is the main blocking call that drives actor message processing. Use scheduleOnce() or a root actor to trigger shutdown() when the application has finished its work.

runtime()

public runtime() : Runtime
Return values
Runtime —

The concurrency backend driving message dispatch and timers.

shutdown()

Gracefully shut down the system within the given timeout.

public shutdown(Duration $timeout) : void
  1. Marks the system as stopping (idempotent on repeated calls).
  2. Sends PoisonPill to all top-level actors so cooperative actors stop cleanly.
  3. Yields cooperatively until all children are stopped or the deadline expires.
  4. Force-stops any survivors by calling initiateStop() directly, which closes their mailbox (unblocking dequeueBlocking) and delivers PostStop.
  5. Signals the runtime to shut down.
Parameters
$timeout : Duration

Wall-clock budget for graceful drain before force-stop runs.

spawn()

Spawn a named actor under the /user guardian and return its reference.

public spawn(Props<string|int, T> $props, string $name) : ActorRef<string|int, T>

The actor is started immediately; its PreStart signal fires before this method returns. If an actor with the same name already exists and is still alive, ActorNameExistsException is thrown. A previously stopped actor with the same name is silently replaced.

Parameters
$props : Props<string|int, T>

Spawn configuration (behavior, mailbox, supervision).

$name : string

Unique name within the /user guardian; used in the actor path.

Tags
template

T of object

throws
ActorInitializationException

if the behavior's setup phase throws.

throws
ActorNameExistsException

if a live actor with this name already exists.

Return values
ActorRef<string|int, T> —

Live, started reference whose path is /user/{name}.

spawnAnonymous()

Spawn an anonymous actor with an auto-generated name under the /user guardian.

public spawnAnonymous(Props<string|int, T> $props) : ActorRef<string|int, T>

The generated name has the form auto-N where N is a monotonically increasing counter. Use this when the actor's logical identity does not matter (e.g. a fire-and-forget worker). Prefer spawn() when you need to look up the actor later via a stable name.

Parameters
$props : Props<string|int, T>

Spawn configuration (behavior, mailbox, supervision).

Tags
template

T of object

throws
ActorInitializationException

if the behavior's setup phase throws.

Return values
ActorRef<string|int, T> —

Live, started reference whose path is /user/auto-N.

stop()

Gracefully stop an actor by sending it a PoisonPill.

public stop(ActorRef<string|int, object> $ref) : void

The actor processes all messages already in its mailbox before honouring the PoisonPill, then delivers PostStop and stops its children. This method returns immediately; the stop happens asynchronously.

Parameters
$ref : ActorRef<string|int, object>

The actor to stop.

writerId()

Unique writer ULID for this actor system instance.

public writerId() : Ulid

Stamped on every persisted envelope so stores can enforce the single-writer principle and ReplayFilter can detect interleaved writers during event recovery.

Return values
Ulid —

Stable for the lifetime of this instance; regenerated on each ActorSystem::create() call.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results