Nexus API Reference
MailboxConfig
in package
Immutable value object configuring the capacity and overflow behaviour of an actor mailbox.
Pass a MailboxConfig to Props::withMailbox() to tune how messages are queued for a
specific actor. The default (unbounded) is suitable for most actors; use bounded mailboxes
to apply back-pressure or drop policies on high-throughput pipelines.
Example:
// Drop the newest message when the mailbox is full (circuit-breaker pattern)
$props = Props::fromBehavior($behavior)
->withMailbox(MailboxConfig::bounded(100, OverflowStrategy::DropNewest));
// Unbounded queue — messages are never dropped (default)
$props = Props::fromBehavior($behavior)
->withMailbox(MailboxConfig::unbounded());
Tags
Table of Contents
Properties
- $bounded : bool
- $capacity : int
- $strategy : OverflowStrategy
Methods
- bounded() : self
- Create a bounded mailbox that enforces a maximum queue depth.
- unbounded() : self
- Create an unbounded mailbox with no capacity limit.
- withCapacity() : self
- Return a new config with the given capacity, preserving all other settings.
- withStrategy() : self
- Return a new config with the given overflow strategy, preserving all other settings.
Properties
$bounded
public
bool
$bounded
$capacity
public
int
$capacity
$strategy
public
OverflowStrategy
$strategy
Methods
bounded()
Create a bounded mailbox that enforces a maximum queue depth.
public
static bounded(int $capacity[, OverflowStrategy $strategy = OverflowStrategy::ThrowException ]) : self
When the mailbox reaches $capacity, $strategy determines what happens to
incoming messages (throw, drop newest, drop oldest, or back-pressure the sender).
Parameters
- $capacity : int
- $strategy : OverflowStrategy = OverflowStrategy::ThrowException
Return values
selfunbounded()
Create an unbounded mailbox with no capacity limit.
public
static unbounded() : self
The queue grows without bound; only use this when message producers are naturally rate-limited or when unbounded memory growth is acceptable.
Return values
selfwithCapacity()
Return a new config with the given capacity, preserving all other settings.
public
withCapacity(int $capacity) : self
Parameters
- $capacity : int
Return values
selfwithStrategy()
Return a new config with the given overflow strategy, preserving all other settings.
public
withStrategy(OverflowStrategy $strategy) : self
Parameters
- $strategy : OverflowStrategy