跳转到内容
简体中文

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.

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.

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.

T = unknown

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

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

PriorityMailboxOptions<T>

PriorityMailbox<T>

DroppingMailbox<T>.constructor

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.

DroppingMailbox.deadLetterDrops


droppedCount: number = 0

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

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

DroppingMailbox.droppedCount

get size(): number

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

Number of pending user messages.

number

DroppingMailbox.size


get suspended(): boolean

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

boolean

DroppingMailbox.suspended

dequeueSystem(): Envelope<unknown> | undefined

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

Envelope<unknown> | undefined

DroppingMailbox.dequeueSystem


dequeueUser(): Envelope<T> | undefined

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

Envelope<T> | undefined

DroppingMailbox.dequeueUser


drainSystem(): Envelope<unknown>[]

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

Envelope<unknown>[]

DroppingMailbox.drainSystem


drainUser(): Envelope<T>[]

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

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.

Envelope<T>[]

DroppingMailbox.drainUser


enqueue(envelope): void

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

Envelope<T>

void

DroppingMailbox.enqueue


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.

Envelope<T>

void

DroppingMailbox.enqueueSignal


enqueueSystem(env): void

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

Queue a framework SystemCommand on the lane that overtakes all user traffic.

This lane is deliberately uncapped, and no bound reaches it — including a subclass’s own. It writes straight to the private system ring rather than delegating, which is the deliberate opposite of enqueueSignal two methods up: a signal rides the user lane and therefore has to go through whatever store a subclass keeps, while a system command has no business in that store at all. So overriding enqueue to shed load bounds the user queue and leaves this one alone, and neither BoundedMailbox nor PriorityMailbox overrides this method. A capacity an operator tunes against measured heap is a user-queue capacity; say so when you document one.

The reason is the one Envelope.undroppable gives one layer up, at full strength: supervision and lifecycle must never be dropped. A discarded failure leaves an actor suspended with nobody coming to decide about it, a discarded childTerminated leaks a child registration forever, and a discarded terminate strands the cell — none of which the framework has a second copy to re-send, and all of which fail silently in the direction of a wedged actor rather than a lost message. Nor does the drain loop in ActorCell.run carry a per-turn budget, for the matching reason: a budget would interleave a supervision decision with user traffic that decision exists to gate, and reordering supervision is a worse trade than the user-message starvation an unbounded drain admits.

What bounds it instead is the producer, and that is the property to re-check before adding a system-message source. Every caller today is one envelope per event that already costs the node an actor: one create per cell and one terminate per stop, one childTerminated per child that finishes stopping, and per supervision decision one failure to the parent plus whatever it fans out over the failing subtree — suspend, then resume, recreate or terminate once the directive is known. One receiveTimeout per armed timer that expires, and one watchNotify per Terminated that a remote watch brings home (#918) — a watch this node’s own actor registered, answered once — complete the list.

watchNotify was for a long time the declared variant deliberately not on it, because nothing emitted one; putting it there as “one per watched death” was this JSDoc’s own first mistake. It still is not how a local death travels: ActorCell._notifyWatcher hands a local watcher its Terminated through postSignalEnvelope, which is the user lane — exempt from the bound (see Envelope.undroppable) and still behind everything already told to that watcher, because that ordering is what death watch documents. Watching a thousand local actors adds nothing to the depth here. What RemoteWatcher enqueues is the one case the arm was kept wired and exempt for (#729): a death this node did not witness, which it turns into the branded Terminated and re-posts on the user lane. The ratio holds for it too — a peer can produce at most one per watch this node opened, an unsolicited watch-terminated matches no entry and enqueues nothing, and the entry itself was paid for by the watcher’s registration.

That test is about volume, not about who can reach the method, which is why the sharding path does not change the answer even though it looks like it should. A remote peer addressing entities in a shard really does drive this queue: dispatchEnvelope only ever reaches a tell on the user lane, but the Shard actor handling that user message spawns and watches an entity, and every entity it spawns eventually lands a childTerminated here at passivation or handoff. “A cluster peer cannot invoke it” is therefore true of the call site and beside the point for a queue depth.

It needs no bound anyway because there is no amplification: each envelope is paid for by one entity cell — its own mailbox, watch registration and registry entry — that had to exist first and was admitted through the region’s routing bound on the way in. A peer that can queue N of these has already made the node hold N actor cells, so the lane is a strictly smaller copy of a cost accepted upstream; and the envelope is enqueued as the cell goes away, replacing something larger than itself, so the peak falls rather than rises at the moment the traffic appears.

A source that broke that ratio — one cheap remote action queueing many envelopes, or envelopes tied to no resource the node already gates — is what would need an answer, and the answer would be per-kind coalescing (collapse duplicate suspend / resume for the same child) rather than a cap. Dropping is the one thing this lane may not do.

Envelope<unknown>

void

DroppingMailbox.enqueueSystem


hasMessages(): boolean

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

boolean

DroppingMailbox.hasMessages


hasSystemMessages(): boolean

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

boolean

DroppingMailbox.hasSystemMessages


hasUserMessages(): boolean

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

boolean

DroppingMailbox.hasUserMessages


observeDrops(observer): void

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

See DropReportingMailbox.observeDrops — additive.

MailboxDropObserver<T>

void

DroppingMailbox.observeDrops


prependUser(envelopes): void

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

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.

Except an Envelope.undroppable one, which takes enqueueSignal instead — the same exempt door it would have taken arriving fresh, and the same rule BoundedMailbox.prependUser applies (#729). Re-entering enqueue was the whole bug: that capacity check never reads the marker, so a Terminated that round-tripped through a stash came back droppable and two of the three policies destroyed it — drop-new discarded it and counted it as an ordinary shed message, and reject threw MailboxFullError on the replaying actor’s own stack. drop-lowest-priority was already safe by accident, because it sheds through removeOldest, which does read the marker; relying on that accident would have left the guarantee holding for one policy out of three. Nothing is reported either way, because nothing is discarded.

enqueueSignal rather than insert directly, so a subclass that overrides the exempt lane keeps owning it on the replay path too. The position is identical — both re-rank — so a notification still comes back wherever priorityFor puts it, exempt from the bound but not from the order.

Envelope<T>[]

void

DroppingMailbox.prependUser


resume(): void

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

void

DroppingMailbox.resume


suspend(): void

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

void

DroppingMailbox.suspend