Nexus API Reference

ActorCell
in package
implements ActorContext

FinalYes
Tags
psalm-api

Internal engine of an actor. Manages behavior, state machine, children, stash, and supervision.

template

T of object

implements

ActorContext<T>

Table of Contents

Interfaces

ActorContext
Runtime context injected into every actor handler invocation.

Methods

__construct()  : mixed
actorState()  : ActorState
child()  : ActorRef<string|int, object>|null
Return the child actor with the given name, or null if it does not exist.
children()  : array<string, ActorRef<string|int, object>>
Return all live direct children keyed by name.
currentSpan()  : Span
The span for the message currently being handled (a no-op span outside a user-message handler). Use to add attributes/events to the active span.
initiateStop()  : void
isAlive()  : bool
log()  : LoggerInterface
Return the PSR-3 logger associated with this actor.
meter()  : Meter
Meter for recording custom metrics from within a handler. No-op when observability is disabled.
parent()  : ActorRef<string|int, object>|null
Return the supervising parent actor, or null if this is a root actor.
path()  : ActorPath
Return the actor's canonical path in the supervision tree.
processMessage()  : void
reply()  : void
Reply to the sender of the current message.
restart()  : void
Supervised restart: reset the actor to its pristine behavior and re-run startup, mirroring {@see self::start()}. Children are torn down, stash and timers are cleared, and lifecycle signals are delivered (PreRestart on the failed instance, PreStart on the fresh one — Akka semantics).
scheduleOnce()  : Cancellable
Deliver `$message` to this actor once after `$delay`.
scheduleRepeatedly()  : Cancellable
Deliver `$message` to this actor on a fixed interval.
self()  : ActorRef<string|int, T>
Return the type-safe reference to this actor itself.
sender()  : ActorRef<string|int, object>|null
Return the sender of the message currently being handled, if any.
setReceiveTimeout()  : void
Configure a receive-timeout for this actor.
spawn()  : ActorRef<string|int, C>
Spawn a named child actor under this actor in the supervision tree.
spawnTask()  : Cancellable
Spawn a background task bound to this actor's lifecycle.
start()  : void
stash()  : void
Stash the current message for later processing.
stop()  : void
Gracefully stop a direct child actor.
tracer()  : Tracer
Tracer for creating custom spans from within a handler; child of the current message span. No-op when observability is disabled.
unstashAll()  : void
Re-enqueue all stashed messages at the front of the mailbox.
unwatch()  : void
Cancel a previously registered death-watch subscription.
watch()  : void
Subscribe to termination notifications for `$target`.

Methods

__construct()

public __construct(Behavior<string|int, T> $behavior, ActorPath $actorPath, Mailbox<string|int, Envelope> $mailbox, Runtime $runtime, ActorRef<string|int, object>|null $parentRef, SupervisionStrategy $supervision, ClockInterface $clock, LoggerInterface $logger, DeadLetterRef $deadLetters, Observability $observability) : mixed
Parameters
$behavior : Behavior<string|int, T>
$actorPath : ActorPath
$mailbox : Mailbox<string|int, Envelope>
$runtime : Runtime
$parentRef : ActorRef<string|int, object>|null
$supervision : SupervisionStrategy
$clock : ClockInterface
$logger : LoggerInterface
$deadLetters : DeadLetterRef
$observability : Observability

child()

Return the child actor with the given name, or null if it does not exist.

public child(string $name) : ActorRef<string|int, object>|null
Parameters
$name : string

Child name as passed to spawn()

Return values
ActorRef<string|int, object>|null

children()

Return all live direct children keyed by name.

public children() : array<string, ActorRef<string|int, object>>
Return values
array<string, ActorRef<string|int, object>>

currentSpan()

The span for the message currently being handled (a no-op span outside a user-message handler). Use to add attributes/events to the active span.

public currentSpan() : Span
Return values
Span

initiateStop()

public initiateStop() : void

isAlive()

public isAlive() : bool
Return values
bool

log()

Return the PSR-3 logger associated with this actor.

public log() : LoggerInterface
Return values
LoggerInterface —

Logger pre-bound with this actor's path as context

meter()

Meter for recording custom metrics from within a handler. No-op when observability is disabled.

public meter() : Meter
Return values
Meter

parent()

Return the supervising parent actor, or null if this is a root actor.

public parent() : ActorRef<string|int, object>|null
Return values
ActorRef<string|int, object>|null

path()

Return the actor's canonical path in the supervision tree.

public path() : ActorPath
Return values
ActorPath —

Hierarchical path such as /user/orders/worker-1

processMessage()

public processMessage(Envelope $envelope) : void
Parameters
$envelope : Envelope

reply()

Reply to the sender of the current message.

public reply(object $message) : void

Only works for messages received via ask() — throws for regular tell().

Parameters
$message : object

Reply payload to deliver to the original sender

restart()

Supervised restart: reset the actor to its pristine behavior and re-run startup, mirroring {@see self::start()}. Children are torn down, stash and timers are cleared, and lifecycle signals are delivered (PreRestart on the failed instance, PreStart on the fresh one — Akka semantics).

public restart(Throwable $cause) : void
Parameters
$cause : Throwable

scheduleOnce()

Deliver `$message` to this actor once after `$delay`.

public scheduleOnce(Duration $delay, T $message) : Cancellable
Parameters
$delay : Duration

Wall-clock delay before the message is enqueued

$message : T
Return values
Cancellable —

Handle that aborts the pending delivery when cancelled

scheduleRepeatedly()

Deliver `$message` to this actor on a fixed interval.

public scheduleRepeatedly(Duration $initialDelay, Duration $interval, T $message) : Cancellable
Parameters
$initialDelay : Duration

Delay before the first delivery

$interval : Duration

Period between subsequent deliveries

$message : T
Return values
Cancellable —

Handle that stops further deliveries when cancelled

self()

Return the type-safe reference to this actor itself.

public self() : ActorRef<string|int, T>
Return values
ActorRef<string|int, T>

sender()

Return the sender of the message currently being handled, if any.

public sender() : ActorRef<string|int, object>|null
Return values
ActorRef<string|int, object>|null

setReceiveTimeout()

Configure a receive-timeout for this actor.

public setReceiveTimeout(Duration|null $timeout) : void

If no user message arrives within $timeout after the last user-message dispatch, the actor receives a Monadial\Nexus\Core\Lifecycle\ReceiveTimeout signal via onSignal(). System messages do not reset the timer. Call with null to cancel; re-calling with a new Duration replaces the current setting and takes effect on the first subsequent user message.

Parameters
$timeout : Duration|null

Inactivity window, or null to disable the timeout

spawn()

Spawn a named child actor under this actor in the supervision tree.

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

Child name, unique within this actor's live children

Tags
template

C of object

throws
ActorInitializationException
Return values
ActorRef<string|int, C>

stash()

Stash the current message for later processing.

public stash() : void

The message is held in an internal buffer and will be re-delivered to the actor's mailbox when unstashAll() is called.

stop()

Gracefully stop a direct child actor.

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

tracer()

Tracer for creating custom spans from within a handler; child of the current message span. No-op when observability is disabled.

public tracer() : Tracer
Return values
Tracer

unstashAll()

Re-enqueue all stashed messages at the front of the mailbox.

public unstashAll() : void

Messages are replayed in the order they were stashed.

unwatch()

Cancel a previously registered death-watch subscription.

public unwatch(ActorRef<string|int, object> $target) : void
Parameters
$target : ActorRef<string|int, object>

watch()

Subscribe to termination notifications for `$target`.

public watch(ActorRef<string|int, object> $target) : void
Parameters
$target : ActorRef<string|int, object> 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results