Mailbox
이 콘텐츠는 아직 번역되지 않았습니다.
Defined in: src/internal/Mailbox.ts:287
Per-actor message queue. System messages (create, terminate, failure, …) are kept on a separate priority queue and drained before any user message.
Both queues are RingBuffers rather than plain arrays, which is
invisible from the outside and load-bearing underneath: every removal used
to be an Array.prototype.shift(), and that reindexes the whole backlog.
Since #1148 made the unbounded mailbox the default again there is no
capacity capping how deep a backlog gets, so an actor that falls behind its
producers was paying a memmove of its entire queue for every message it
delivered (#408).
The fields stay private, so a subclass sees only the methods — which is
why swapping the backing store is not a breaking change even though
Mailbox is public and explicitly subclassable since #661 / #1002. The
seams a subclass touches are protected removeOldest and
removeNewest, and their signatures are unchanged.
Extended by
Section titled “Extended by”Type Parameters
Section titled “Type Parameters”T = unknown
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new Mailbox<
T>():Mailbox<T>
Returns
Section titled “Returns”Mailbox<T>
Accessors
Section titled “Accessors”Get Signature
Section titled “Get Signature”get size():
number
Defined in: src/internal/Mailbox.ts:573
Number of pending user messages.
Returns
Section titled “Returns”number
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
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
dequeueUser()
Section titled “dequeueUser()”dequeueUser():
Envelope<T> |undefined
Defined in: src/internal/Mailbox.ts:467
Returns
Section titled “Returns”Envelope<T> | undefined
drainSystem()
Section titled “drainSystem()”drainSystem():
Envelope<unknown>[]
Defined in: src/internal/Mailbox.ts:591
Returns
Section titled “Returns”Envelope<unknown>[]
drainUser()
Section titled “drainUser()”drainUser():
Envelope<T>[]
Defined in: src/internal/Mailbox.ts:587
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>[]
enqueue()
Section titled “enqueue()”enqueue(
env):void
Defined in: src/internal/Mailbox.ts:294
Parameters
Section titled “Parameters”Envelope<T>
Returns
Section titled “Returns”void
enqueueSignal()
Section titled “enqueueSignal()”enqueueSignal(
env):void
Defined in: src/internal/Mailbox.ts:342
Queue a framework lifecycle notification — see Envelope.undroppable — exempt from whatever bound this mailbox enforces, at the position this mailbox gives any other message: the tail of the user lane, here.
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 door decides undroppability, never position (#1431). Five call
sites reach it, all through ActorCell.postSignalEnvelope:
ActorCell._notifyWatcher, with the Terminated of a local death;
ActorCell.onWatchNotify, with the Terminated of a death another node
reported, one hop on the system queue after RemoteWatcher queued the
report (#918); ConnectionWiring.postAcceptCommand, with the
websocket-accept that hands an upgraded socket to its hub (#717);
WebsocketConnection.close, with the close a connection sends its own
actor (#985); and DistributedData.offerToSubscriber, with the
DistributedDataChanged a replicator posts to an actor subscribed to one
of its keys (#1468). Two of those depend on arriving late: death watch
promises that every tell already queued is handled before the
Terminated, and a reply queued before close() is written before the
socket shuts. So this default — like any FIFO mailbox — queues the
envelope at the tail, and an override must not move an envelope ahead
because it came through here. What the door adds is exemption from the
bound, and nothing else.
Overtaking is something a mailbox type offers, by classifying messages,
and a message gets the same answer whichever door it took.
ControlAwareMailbox is the type that offers it: its predicate classes a
signal like any other message, so a Terminated it leaves ordinary keeps
the death-watch order. A mailbox that reorders everything reorders
signals by its own rule too — PriorityMailbox ranks a Terminated with
priorityFor. What overtakes all user traffic is the system queue, and
none of the five envelopes belongs there; a close that must not wait is a
different method, WebsocketConnection.abort(), which queues nothing.
Parameters
Section titled “Parameters”Envelope<T>
Returns
Section titled “Returns”void
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
hasMessages()
Section titled “hasMessages()”hasMessages():
boolean
Defined in: src/internal/Mailbox.ts:566
Returns
Section titled “Returns”boolean
hasSystemMessages()
Section titled “hasSystemMessages()”hasSystemMessages():
boolean
Defined in: src/internal/Mailbox.ts:570
Returns
Section titled “Returns”boolean
hasUserMessages()
Section titled “hasUserMessages()”hasUserMessages():
boolean
Defined in: src/internal/Mailbox.ts:569
Returns
Section titled “Returns”boolean
prependUser()
Section titled “prependUser()”prependUser(
envs):void
Defined in: src/internal/Mailbox.ts:382
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: an ordinary replayed
message is subject to the bound like any other. 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). All three built-in bounds override it,
by different routes: BoundedMailbox sheds at the tail to make room at
the head, PriorityMailbox re-ranks so priorities are recomputed, and
ControlAwareMailbox puts each envelope back at the head of its own class
and bounds the ordinary half the way BoundedMailbox does (#1431).
An Envelope.undroppable envelope is exempt, on this path too.
This paragraph used to end “a signal is exempt from a bound, a replay is
not”, which was true when it was written and was made false by the fix for
#729 — a lifecycle notification that round-tripped through a stash came
back droppable, and two of the three overflow policies destroyed it. Every
override now admits an undroppable envelope past its bound, the exemption
it would have had arriving fresh: PriorityMailbox by handing it to
enqueueSignal, the other two by testing the marker before they
consult the capacity. An override that reads this as licence to bound
everything it is handed reintroduces exactly that defect, which is why the
sentence is corrected here rather than only at the call sites that already
got it right.
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
resume()
Section titled “resume()”resume():
void
Defined in: src/internal/Mailbox.ts:576
Returns
Section titled “Returns”void
suspend()
Section titled “suspend()”suspend():
void
Defined in: src/internal/Mailbox.ts:575
Returns
Section titled “Returns”void
