ControlAwareMailbox
Esta página aún no está disponible en tu idioma.
Defined in: src/mailbox/ControlAwareMailbox.ts:68
A mailbox that lets control messages overtake queued bulk traffic: two FIFO classes, every control message dequeued before every ordinary one, arrival order kept inside each class (#1431).
Opt-in, and a mailbox type rather than a lane in every mailbox. The framework’s own rule is the opposite one — an envelope that comes through the exempt door is undroppable, not early (see Mailbox.enqueueSignal) — and only a handful of messages could use a third lane without breaking an ordering someone relies on. So the capability lives where an actor that wants it asks for it, and every other actor’s queue and drain loop stay as they are. The predicate decides the class; the framework’s own envelopes are classified like any other message.
Where each class lives
Section titled “Where each class lives”The ordinary class is the base user queue, and that is load-bearing
rather than a convenience. The protected eviction seams
Mailbox.removeOldest and Mailbox.removeNewest scan that
queue, so inheriting them means they keep answering — for the ordinary
class, the only one a bound may shed from — instead of returning
undefined forever over a store they never read, which is the trap
PriorityMailbox documents (#407) and a decorator around an inner mailbox
cannot avoid: it can delegate the public methods, but not a protected one.
The control class is a RingBuffer of its own, for the same
reason the base queue is one: a deep backlog must not make each delivery
cost a reindex.
The bound
Section titled “The bound”A capacity counts ordinary messages only, and every overflow policy acts on
the ordinary class only. A control message is admitted at any depth, never
evicted, never reported as a drop, and never makes reject throw: the
flood a bound sheds is the traffic the control message was overtaking, and
shedding the one message the mailbox was chosen for would invert it. So
the bound is a ceiling on the ordinary class, and the control class is
bounded by whatever produces it — size it, and choose the predicate,
accordingly.
The predicate
Section titled “The predicate”Runs at every door — enqueue, enqueueSignal and prependUser — on the
caller’s stack, and is contained there: a throw, or any answer but true,
classes the message ordinary and nothing escapes into the tell. The same
argument as PriorityMailbox.priorityOf (#733): a sender is a bystander to
the receiver’s mailbox configuration, and PoisonPill / Kill reach the
predicate as user messages with no fields. Ordinary is also the right
fallback rather than merely the safe one — it is the class the message
would have had on any other mailbox. Contained is not silent, though: a
throw goes to onControlError, which by default logs the first one.
A replay re-runs it, so a stashed message rejoins whichever class the predicate puts it in now; for a predicate that only reads the message’s shape, that is the class it left.
Extends
Section titled “Extends”Type Parameters
Section titled “Type Parameters”T = unknown
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new ControlAwareMailbox<
T>(options):ControlAwareMailbox<T>
Defined in: src/mailbox/ControlAwareMailbox.ts:77
Parameters
Section titled “Parameters”options
Section titled “options”Returns
Section titled “Returns”ControlAwareMailbox<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/ControlAwareMailbox.ts:247
Both classes. The cell reads this for the high-water warning and the depth metrics, and a backlog of control messages is a backlog. The bound reads the ordinary class alone, through the base getter.
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:292
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:562
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/ControlAwareMailbox.ts:237
Control first — the whole point — then the ordinary class, FIFO inside each.
Returns
Section titled “Returns”Envelope<T> | undefined
Overrides
Section titled “Overrides”drainSystem()
Section titled “drainSystem()”drainSystem():
Envelope<unknown>[]
Defined in: src/internal/Mailbox.ts:591
Returns
Section titled “Returns”Envelope<unknown>[]
Inherited from
Section titled “Inherited from”drainUser()
Section titled “drainUser()”drainUser():
Envelope<T>[]
Defined in: src/mailbox/ControlAwareMailbox.ts:256
Control, then ordinary — the order they would have been delivered in.
Returns
Section titled “Returns”Envelope<T>[]
Overrides
Section titled “Overrides”enqueue()
Section titled “enqueue()”enqueue(
envelope):void
Defined in: src/mailbox/ControlAwareMailbox.ts:101
Control to the control class, whatever the bound says; ordinary to the ordinary class, under it.
A switch with an exhaustive never rather than a match, for the
reason BoundedMailbox.enqueue gives: the policy is configuration fixed
at construction, not an incoming message, and this branch runs once per
shed message — at the moment the system is least able to afford a
matcher and a closure per arm (#974).
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/ControlAwareMailbox.ts:144
The exempt door classifies too — see Mailbox.enqueueSignal.
An undroppable ordinary envelope — a Terminated this predicate
leaves ordinary, a WebSocket close — is admitted past the bound at the
tail of the ordinary class, which is exactly the position the framework’s
rule gives it on every other mailbox: death watch keeps its order here
unless the predicate says otherwise. An undroppable control envelope
joins the control class, which no bound sheds anyway.
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: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.
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/ControlAwareMailbox.ts:251
Returns
Section titled “Returns”boolean
Overrides
Section titled “Overrides”hasSystemMessages()
Section titled “hasSystemMessages()”hasSystemMessages():
boolean
Defined in: src/internal/Mailbox.ts:570
Returns
Section titled “Returns”boolean
Inherited from
Section titled “Inherited from”DroppingMailbox.hasSystemMessages
hasUserMessages()
Section titled “hasUserMessages()”hasUserMessages():
boolean
Defined in: src/mailbox/ControlAwareMailbox.ts:249
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/ControlAwareMailbox.ts:163
A replay goes back to the head of each envelope’s own class — a stash’s
unstashAll(), and the cell’s throttle re-park, which hands back the
envelope it just dequeued. Back at the head of the ordinary class, a
re-parked control message would be overtaken by the very traffic it had
overtaken.
The ordinary half meets the bound under BoundedMailbox.prependUser’s
rules (#772), restated in admitOrdinaryReplay. The control half
is never bounded. Under reject the decision is taken before anything is
admitted, the control half included: ActorCell.unstashAll puts a refused
batch back into the stash, and a control envelope admitted on the way to
the throw would then be queued and stashed at once — delivered twice.
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:576
Returns
Section titled “Returns”void
Inherited from
Section titled “Inherited from”suspend()
Section titled “suspend()”suspend():
void
Defined in: src/internal/Mailbox.ts:575
Returns
Section titled “Returns”void
