DroppingMailbox
Este conteúdo não está disponível em sua língua ainda.
Defined in: src/mailbox/DroppingMailbox.ts:53
Base for a mailbox that discards messages and accounts for it.
The bookkeeping — the counter, the caller’s hook, the framework’s observers
— is identical for every bound and got written once, inside BoundedMailbox
(#1149). PriorityMailbox grew a capacity of its own in #647 and cannot
reuse BoundedMailbox: it keeps its messages in a priority-ordered array
rather than in the base user queue, so it shares the accounting but not
the queue. Duplicating the accounting is how the second copy comes to
lack the observer the first one has, which is the exact shape of #1149.
Subclasses call reportDrop once per message actually discarded — “actually” being load-bearing, since #407 was a counter that ran on a removal that had not happened.
A caller-supplied onDrop is registered as the first observer rather than
held in a separate slot, so ordering is fixed and obvious: the counter
first, then the hook the caller wired at construction, then whatever the
framework registered afterwards.
Implementing DropReportingMailbox here is what puts a subclass into
actor_mailbox_dropped_total: the cell probes structurally for
observeDrops, so it never needs to know which mailbox it was handed.
Extends
Section titled “Extends”Mailbox<T>
Extended by
Section titled “Extended by”Type Parameters
Section titled “Type Parameters”T = unknown
Implements
Section titled “Implements”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.
Implementation of
Section titled “Implementation of”DropReportingMailbox.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.
Accessors
Section titled “Accessors”Get Signature
Section titled “Get Signature”get size():
number
Defined in: src/internal/Mailbox.ts:406
Number of pending user messages.
Returns
Section titled “Returns”number
Inherited from
Section titled “Inherited from”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/internal/Mailbox.ts:300
Returns
Section titled “Returns”Envelope<T> | undefined
Inherited from
Section titled “Inherited from”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/internal/Mailbox.ts:420
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>[]
Inherited from
Section titled “Inherited from”enqueue()
Section titled “enqueue()”enqueue(
env):void
Defined in: src/internal/Mailbox.ts:239
Parameters
Section titled “Parameters”Envelope<T>
Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”enqueueSignal()
Section titled “enqueueSignal()”enqueueSignal(
env):void
Defined in: src/internal/Mailbox.ts:266
Queue a framework lifecycle notification — see Envelope.undroppable — at the tail of the user lane, exempt from whatever bound this mailbox enforces.
Override this whenever you override enqueue to shed load. The
default here delegates, which is right for a queue that never discards
anything and wrong for one that does: a subclass that drops on a full
queue would drop this too, and the framework has no second copy to send.
Delegating rather than pushing straight onto the base queue is deliberate
— a subclass may keep its messages somewhere else entirely (PriorityMailbox
keeps a priority-ordered array), and an envelope smuggled into a store that
subclass never reads is worse than one it dropped: invisible to its
dequeueUser, its size and its drainUser, so not even a dead letter
comes out of it.
The envelope still arrives at the tail, which is what keeps the
documented death-watch ordering intact: every tell already queued is
handled first, then the notification. It is not a priority lane and must
not become one — the system queue is where the framework puts messages
that overtake user traffic, and a Terminated deliberately is not one of
those.
Parameters
Section titled “Parameters”Envelope<T>
Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”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/internal/Mailbox.ts:399
Returns
Section titled “Returns”boolean
Inherited from
Section titled “Inherited from”hasSystemMessages()
Section titled “hasSystemMessages()”hasSystemMessages():
boolean
Defined in: src/internal/Mailbox.ts:403
Returns
Section titled “Returns”boolean
Inherited from
Section titled “Inherited from”hasUserMessages()
Section titled “hasUserMessages()”hasUserMessages():
boolean
Defined in: src/internal/Mailbox.ts:402
Returns
Section titled “Returns”boolean
Inherited from
Section titled “Inherited from”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
Implementation of
Section titled “Implementation of”DropReportingMailbox.observeDrops
prependUser()
Section titled “prependUser()”prependUser(
envs):void
Defined in: src/internal/Mailbox.ts:292
Put envelopes at the FRONT of the user queue, preserving their order.
One bulk move, not a spread: unstashAll replays up to
DEFAULT_STASH_CAPACITY envelopes in a single call, and
unshift(...envs) would both reindex the backlog once per envelope and
push the whole batch onto the call stack as arguments.
Override this whenever you override enqueue to shed load, for
the same reason enqueueSignal says so and the opposite conclusion:
a signal is exempt from a bound, a replay is not. Leaving the default in
place is what made a bounded mailbox unbounded on the stash path — a
batch the size of the stash arrived past the capacity check, the overflow
policy and the drop accounting, so the ceiling an operator tuned against
measured heap was not one (#772). BoundedMailbox and PriorityMailbox
both override it, by different routes: the former sheds at the tail to
make room at the head, the latter re-enters enqueue so priorities are
recomputed.
The base is right to be unconditional here — it never discards anything, so there is nothing to consult.
Parameters
Section titled “Parameters”Envelope<T>[]
Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”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