Nexus API Reference

DeadLetterRef
in package
implements ActorRef

FinalYes
Tags
psalm-api

Null-object ActorRef that captures dead letters.

Every message sent via tell() increments a monotonic counter, is dispatched as a MessageDeadLettered event (when an EventDispatcher is configured), and is retained in a bounded ring buffer of the most recent samples for inspection. The buffer is capped at $maxSamples (default 1000): once full, the oldest sample is evicted so memory stays stable no matter how many messages are dead-lettered. The counter (see total()) keeps counting past the cap, so it is a truthful delivery-failure signal even though captured() only shows the recent tail.

ask() immediately throws AskTimeoutException. isAlive() always returns false.

implements

Table of Contents

Interfaces

ActorRef
Type-safe reference to an actor — the only handle user code holds.

Methods

__construct()  : mixed
ask()  : Future<string|int, R>
Send a message and get a Future for the reply.
captured()  : array<int, object>
The most recent dead-lettered messages, bounded by $maxSamples.
isAlive()  : bool
Return true if the actor is still running and able to receive messages.
path()  : ActorPath
Return the hierarchical path that uniquely identifies this actor in the system.
tell()  : void
Send a message to the actor without waiting for a reply (fire-and-forget).
total()  : int
Total number of messages ever dead-lettered — monotonic, never reset, and not bounded by $maxSamples. Use this as the delivery-failure metric; captured() is only a recent-sample window.

Methods

__construct()

public __construct([int $maxSamples = 1000 ][, EventDispatcherInterface|null $events = null ]) : mixed
Parameters
$maxSamples : int = 1000

maximum number of recent messages retained for inspection

$events : EventDispatcherInterface|null = null

captured()

The most recent dead-lettered messages, bounded by $maxSamples.

public captured() : array<int, object>
Return values
array<int, object>

isAlive()

Return true if the actor is still running and able to receive messages.

public isAlive() : bool

Returns false once the actor has stopped or its mailbox has been closed. Messages sent to a stopped actor are forwarded to dead letters.

Attributes
#[Override]
Return values
bool

path()

Return the hierarchical path that uniquely identifies this actor in the system.

public path() : ActorPath

Paths have the form /user/parent/child and are stable for the lifetime of the actor. They appear in log output and are used as routing keys in the worker pool and cluster layers.

Attributes
#[Override]
Return values
ActorPath

tell()

Send a message to the actor without waiting for a reply (fire-and-forget).

public tell(object $message) : void

The message is enqueued in the actor's mailbox and processed asynchronously. This method never blocks and always returns immediately.

System messages (PoisonPill, Watch, Unwatch, ...) are accepted by every actor in addition to its protocol T; the cell routes them to the control path before user messages.

Parameters
$message : object
Attributes
#[Override]

total()

Total number of messages ever dead-lettered — monotonic, never reset, and not bounded by $maxSamples. Use this as the delivery-failure metric; captured() is only a recent-sample window.

public total() : int
Return values
int
On this page

Search results