Zum Inhalt springen
Deutsch

DroppingMailbox

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

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.

T = unknown

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.

DropReportingMailbox.deadLetterDrops


droppedCount: number = 0

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

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

get size(): number

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

Number of pending user messages.

number

Mailbox.size


get suspended(): boolean

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

boolean

Mailbox.suspended

dequeueSystem(): Envelope<unknown> | undefined

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

Envelope<unknown> | undefined

Mailbox.dequeueSystem


dequeueUser(): Envelope<T> | undefined

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

Envelope<T> | undefined

Mailbox.dequeueUser


drainSystem(): Envelope<unknown>[]

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

Envelope<unknown>[]

Mailbox.drainSystem


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.

Envelope<T>[]

Mailbox.drainUser


enqueue(env): void

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

Envelope<T>

void

Mailbox.enqueue


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.

Envelope<T>

void

Mailbox.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

Mailbox.enqueueSystem


hasMessages(): boolean

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

boolean

Mailbox.hasMessages


hasSystemMessages(): boolean

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

boolean

Mailbox.hasSystemMessages


hasUserMessages(): boolean

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

boolean

Mailbox.hasUserMessages


observeDrops(observer): void

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

See DropReportingMailbox.observeDrops — additive.

MailboxDropObserver<T>

void

DropReportingMailbox.observeDrops


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.

Envelope<T>[]

void

Mailbox.prependUser


resume(): void

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

void

Mailbox.resume


suspend(): void

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

void

Mailbox.suspend