PriorityMailbox

Defined in: src/mailbox/PriorityMailbox.ts:96

User messages are dequeued in priority order (ascending priority value, then FIFO). System messages still take strict precedence over any user message. Internally backed by an ordered array — suitable for moderate mailbox sizes; swap for a heap if throughput becomes a concern.

Bounding one, and what drop means here

A capacity is optional and unset by default (#647). When one is set, the overflow policy decides what a full mailbox does — and the interesting policy is drop-lowest-priority, which is where this diverges from BoundedMailbox.

drop-head is not offered, deliberately. On a FIFO queue it means “discard the stalest”, which is coherent because arrival order is the only order there is. Here the head is the message the priority function said matters most; discarding it would defeat the entire reason for choosing this mailbox. The two other readings were considered and rejected: “oldest by arrival” is an O(n) scan on the enqueue path (the array is ordered by priority, not by arrival) and still destroys a message the caller called important, while dropping the head is indefensible. So the bound sheds along the axis the queue is ordered by — the tail, which is both the least important message and an O(1) pop.

A shed message is reported as drop-head on the metric, because MailboxDropReason is a closed two-value set (a metric label, and an open one is a cardinality vector — #745) whose distinction is “a queued message” versus “the arriving one”. When the arriving message is itself the least important, it is the one shed, and then the reason really is drop-new — the eviction compares identities rather than guessing.

When the priority function cannot answer

priorityFor is user code on the sender’s stack, and the framework itself hands it messages no application wrote: ActorRef.stop() and ActorRef.kill() send PoisonPill / Kill as user messages, and both serialise as {}. So “it threw” and “it returned something that is not a number” are ordinary states rather than programmer error, and both are contained — the message keeps its place in the queue at UNRANKABLE_PRIORITY (#733). priorityOf carries the reasoning.

Extends

• DroppingMailbox<T>

Type Parameters

T

T = unknown

Constructors

Constructor

new PriorityMailbox<T>(options): PriorityMailbox<T>

Defined in: src/mailbox/PriorityMailbox.ts:105

Parameters

options

PriorityMailboxOptions<T>

Returns

PriorityMailbox<T>

Overrides

DroppingMailbox<T>.constructor

Properties

deadLetterDrops

readonly deadLetterDrops: boolean

Defined in: src/mailbox/DroppingMailbox.ts:71

See DropReportingMailbox.deadLetterDrops. Fixed at construction because the cell reads it once, when it registers its observer: a switch a running mailbox could flip would mean re-reading it per dropped message, on the path this class exists to keep cheap.

Inherited from

DroppingMailbox.deadLetterDrops

---

droppedCount

droppedCount: number = 0

Defined in: src/mailbox/DroppingMailbox.ts:63

Number of messages dropped by the overflow policy — useful for metrics.

Inherited from

DroppingMailbox.droppedCount

Accessors

size

Get Signature

get size(): number

Defined in: src/mailbox/PriorityMailbox.ts:284

Number of pending user messages.

Returns

number

Overrides

DroppingMailbox.size

---

suspended

Get Signature

get suspended(): boolean

Defined in: src/internal/Mailbox.ts:237

Returns

boolean

Inherited from

DroppingMailbox.suspended

Methods

dequeueSystem()

dequeueSystem(): Envelope<unknown> | undefined

Defined in: src/internal/Mailbox.ts:395

Returns

Envelope<unknown> | undefined

Inherited from

DroppingMailbox.dequeueSystem

---

dequeueUser()

dequeueUser(): Envelope<T> | undefined

Defined in: src/mailbox/PriorityMailbox.ts:247

Returns

Envelope<T> | undefined

Overrides

DroppingMailbox.dequeueUser

---

drainSystem()

drainSystem(): Envelope<unknown>[]

Defined in: src/internal/Mailbox.ts:424

Returns

Envelope<unknown>[]

Inherited from

DroppingMailbox.drainSystem

---

drainUser()

drainUser(): Envelope<T>[]

Defined in: src/mailbox/PriorityMailbox.ts:288

Drain all user messages; returns them so the caller can forward to dead letters.

Materialises a fresh array rather than handing out the backing store — a ring is not a dense array, so there is nothing to hand out. The allocation is real but it is on the termination path, where the caller (ActorCell) only iterates the result once.

Returns

Envelope<T>[]

Overrides

DroppingMailbox.drainUser

---

enqueue()

enqueue(envelope): void

Defined in: src/mailbox/PriorityMailbox.ts:121

Parameters

envelope

Envelope<T>

Returns

void

Overrides

DroppingMailbox.enqueue

---

enqueueSignal()

enqueueSignal(envelope): void

Defined in: src/mailbox/PriorityMailbox.ts:148

A death notification is queued whatever the capacity says — see Mailbox.enqueueSignal.

Straight to insert, past the capacity check. Overriding here is not optional for this class: its messages live in ordered rather than in the base user queue, so the inherited default — which delegates to enqueue — would hand the notification to the very overflow logic that sheds it (#729). The notification takes its place in priority order like any other message, which means a priorityFor that ranks a Terminated last still delivers it last; what it can no longer do is delete it.

Parameters

envelope

Envelope<T>

Returns

void

Overrides

DroppingMailbox.enqueueSignal

---

enqueueSystem()

enqueueSystem(env): void

Defined in: src/internal/Mailbox.ts:296

Parameters

env

Envelope<unknown>

Returns

void

Inherited from

DroppingMailbox.enqueueSystem

---

hasMessages()

hasMessages(): boolean

Defined in: src/mailbox/PriorityMailbox.ts:329

Returns

boolean

Overrides

DroppingMailbox.hasMessages

---

hasSystemMessages()

hasSystemMessages(): boolean

Defined in: src/internal/Mailbox.ts:403

Returns

boolean

Inherited from

DroppingMailbox.hasSystemMessages

---

hasUserMessages()

hasUserMessages(): boolean

Defined in: src/mailbox/PriorityMailbox.ts:286

Returns

boolean

Overrides

DroppingMailbox.hasUserMessages

---

observeDrops()

observeDrops(observer): void

Defined in: src/mailbox/DroppingMailbox.ts:84

See DropReportingMailbox.observeDrops — additive.

Parameters

observer

MailboxDropObserver<T>

Returns

void

Inherited from

DroppingMailbox.observeDrops

---

prependUser()

prependUser(envelopes): void

Defined in: src/mailbox/PriorityMailbox.ts:306

Reinsert via enqueue — priority is re-computed, which is the correct behaviour (unstashed messages rejoin their priority tier).

Going back through enqueue also means the capacity applies to the unstash path. Since #772 BoundedMailbox bounds its replay too, by the route its own geometry calls for — it sheds at the tail to make room at the head, where this class has only one shedding axis and re-ranking is the answer to both questions at once. The consequence is the same on either mailbox and is worth knowing: on a bounded one, unstashAll() can drop messages, or throw under reject.

Parameters

envelopes

Envelope<T>[]

Returns

void

Overrides

DroppingMailbox.prependUser

---

resume()

resume(): void

Defined in: src/internal/Mailbox.ts:409

Returns

void

Inherited from

DroppingMailbox.resume

---

suspend()

suspend(): void

Defined in: src/internal/Mailbox.ts:408

Returns

void

Inherited from

DroppingMailbox.suspend