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
Section titled “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
Section titled “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
Section titled “Extends”Type Parameters
Section titled “Type Parameters”T = unknown
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new PriorityMailbox<
T>(options):PriorityMailbox<T>
Defined in: src/mailbox/PriorityMailbox.ts:105
Parameters
Section titled “Parameters”options
Section titled “options”Returns
Section titled “Returns”PriorityMailbox<T>
Overrides
Section titled “Overrides”DroppingMailbox<T>.constructor
Properties
Section titled “Properties”deadLetterDrops
Section titled “deadLetterDrops”
readonlydeadLetterDrops: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
Section titled “Inherited from”DroppingMailbox.deadLetterDrops
droppedCount
Section titled “droppedCount”droppedCount:
number=0
Defined in: src/mailbox/DroppingMailbox.ts:63
Number of messages dropped by the overflow policy — useful for metrics.
Inherited from
Section titled “Inherited from”Accessors
Section titled “Accessors”Get Signature
Section titled “Get Signature”get size():
number
Defined in: src/mailbox/PriorityMailbox.ts:284
Number of pending user messages.
Returns
Section titled “Returns”number
Overrides
Section titled “Overrides”suspended
Section titled “suspended”Get Signature
Section titled “Get Signature”get suspended():
boolean
Defined in: src/internal/Mailbox.ts:237
Returns
Section titled “Returns”boolean
Inherited from
Section titled “Inherited from”Methods
Section titled “Methods”dequeueSystem()
Section titled “dequeueSystem()”dequeueSystem():
Envelope<unknown> |undefined
Defined in: src/internal/Mailbox.ts:395
Returns
Section titled “Returns”Envelope<unknown> | undefined
Inherited from
Section titled “Inherited from”dequeueUser()
Section titled “dequeueUser()”dequeueUser():
Envelope<T> |undefined
Defined in: src/mailbox/PriorityMailbox.ts:247
Returns
Section titled “Returns”Envelope<T> | undefined
Overrides
Section titled “Overrides”drainSystem()
Section titled “drainSystem()”drainSystem():
Envelope<unknown>[]
Defined in: src/internal/Mailbox.ts:424
Returns
Section titled “Returns”Envelope<unknown>[]
Inherited from
Section titled “Inherited from”drainUser()
Section titled “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
Section titled “Returns”Envelope<T>[]
Overrides
Section titled “Overrides”enqueue()
Section titled “enqueue()”enqueue(
envelope):void
Defined in: src/mailbox/PriorityMailbox.ts:121
Parameters
Section titled “Parameters”envelope
Section titled “envelope”Envelope<T>
Returns
Section titled “Returns”void
Overrides
Section titled “Overrides”enqueueSignal()
Section titled “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
Section titled “Parameters”envelope
Section titled “envelope”Envelope<T>
Returns
Section titled “Returns”void
Overrides
Section titled “Overrides”enqueueSystem()
Section titled “enqueueSystem()”enqueueSystem(
env):void
Defined in: src/internal/Mailbox.ts:296
Parameters
Section titled “Parameters”Envelope<unknown>
Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”hasMessages()
Section titled “hasMessages()”hasMessages():
boolean
Defined in: src/mailbox/PriorityMailbox.ts:329
Returns
Section titled “Returns”boolean
Overrides
Section titled “Overrides”hasSystemMessages()
Section titled “hasSystemMessages()”hasSystemMessages():
boolean
Defined in: src/internal/Mailbox.ts:403
Returns
Section titled “Returns”boolean
Inherited from
Section titled “Inherited from”DroppingMailbox.hasSystemMessages
hasUserMessages()
Section titled “hasUserMessages()”hasUserMessages():
boolean
Defined in: src/mailbox/PriorityMailbox.ts:286
Returns
Section titled “Returns”boolean
Overrides
Section titled “Overrides”DroppingMailbox.hasUserMessages
observeDrops()
Section titled “observeDrops()”observeDrops(
observer):void
Defined in: src/mailbox/DroppingMailbox.ts:84
See DropReportingMailbox.observeDrops — additive.
Parameters
Section titled “Parameters”observer
Section titled “observer”Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”prependUser()
Section titled “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
Section titled “Parameters”envelopes
Section titled “envelopes”Envelope<T>[]
Returns
Section titled “Returns”void
Overrides
Section titled “Overrides”resume()
Section titled “resume()”resume():
void
Defined in: src/internal/Mailbox.ts:409
Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”suspend()
Section titled “suspend()”suspend():
void
Defined in: src/internal/Mailbox.ts:408
Returns
Section titled “Returns”void