Nexus API Reference

ActorContext
in

Runtime context injected into every actor handler invocation.

ActorContext<T> is the primary API surface an actor uses during message processing. It exposes the actor's own reference, its position in the supervision tree, child management, death-watch subscriptions, message stashing, timer scheduling, background task spawning, and PSR-3 logging. A fresh context is passed on every handler call — never cache or store it.

Example:

$behavior = Behavior::setup(static function (ActorContext $ctx): Behavior {
    $child = $ctx->spawn(Props::fromBehavior($childBehavior), 'worker');
    $ctx->watch($child);

    return Behavior::receive(static function (ActorContext $ctx, object $msg) use ($child): Behavior {
        if ($msg instanceof DoWork) {
            $child->tell($msg);
        }
        return Behavior::same();
    })->onSignal(static function (ActorContext $ctx, Signal $signal): Behavior {
        if ($signal instanceof Terminated) {
            $ctx->log()->warning('Worker terminated');
            return Behavior::stopped();
        }
        return Behavior::same();
    });
});
Tags
see
ActorRef

for the type-safe reference returned by spawn()

see
Props

for actor configuration passed to spawn()

see
Behavior

for the return type of handler closures

psalm-api
template

T of object

Table of Contents

Methods

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.
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.
reply()  : void
Reply to the sender of the current message.
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.
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

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 —

Child reference, or null if no live child has that name

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>> —

Map of child name to actor reference

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

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 —

Parent reference, or null for root-level actors

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

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

Tags
throws
NoSenderException

If no sender on current message

scheduleOnce()

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

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

Returns a Cancellable that can be used to abort the timer before it fires.

Parameters
$delay : Duration

Wall-clock delay before the message is enqueued

$message : T

Message to deliver to this actor's own mailbox

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

The first delivery is after $initialDelay; subsequent deliveries repeat every $interval. Returns a Cancellable to stop the timer.

Parameters
$initialDelay : Duration

Delay before the first delivery

$interval : Duration

Period between subsequent deliveries

$message : T

Message to deliver to this actor's own mailbox on each tick

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>

Use this to hand out a back-reference to other actors (e.g. as a replyTo field on outgoing messages) so they can send messages back to this actor.

Return values
ActorRef<string|int, T> —

Reference typed to this actor's message protocol

sender()

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

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

Populated for messages received via ask(); null for plain tell() dispatches that did not include a reply-to.

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

Sender reference, or null when none was attached

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>

The child runs concurrently and is supervised by this actor according to the supervision strategy configured on its Props. Names must be unique among live children — a dead child with the same name is pruned and replaced transparently.

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

Immutable spawn configuration (behavior, mailbox, supervision)

$name : string

Child name, unique within this actor's live children

Tags
template

C of object

throws
ActorInitializationException

When the child fails to start

throws
ActorNameExistsException

When a live child with $name already exists

Return values
ActorRef<string|int, C> —

Reference to the newly spawned child

spawnTask()

Spawn a background task bound to this actor's lifecycle.

public spawnTask(callable(TaskContext): void $task) : Cancellable

The task closure receives a TaskContext for cooperative cancellation and sending messages back to the parent actor. All spawned tasks are automatically cancelled when the actor stops.

Parameters
$task : callable(TaskContext): void

Task body invoked with a per-task cancellation/reply context

Return values
Cancellable —

Handle that cancels the task when invoked

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

The child finishes processing its current message, then receives a PostStop signal before being removed from the supervision tree.

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

Reference to the child actor to stop

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>

Previously-watched reference to stop watching

watch()

Subscribe to termination notifications for `$target`.

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

When $target stops, this actor receives a Terminated signal via its onSignal() handler.

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

Actor reference to watch for termination


        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results