Mailboxes
Jeder Actor hat genau eine Mailbox — eine FIFO-Queue von
Envelopes, die auf Verarbeitung warten. Wenn du ref.tell(message)
aufrufst, wickelt das Framework message in ein Envelope (mit Sender,
Log-Kontext und optionalem Trace-Kontext) und reiht es in die Mailbox
des Empfängers ein. Der Dispatcher zieht das nächste Envelope,
übergibt es dem onReceive des Actors und wartet, bis das fertig
ist, bevor er das nächste zieht.
Das gibt jedem Actor die “eine Nachricht nach der anderen”-Garantie — und die Mailbox ist das, was das physikalisch wahr macht.
Die Default-Mailbox
Abschnitt betitelt „Die Default-Mailbox“Wenn du nichts konfigurierst, bekommt der Actor eine unbounded FIFO-Mailbox. Auf dem Weg hinein wird nie etwas verworfen; die Queue wächst, bis der Actor sie abarbeitet, und der Heap ist die einzige Decke.
Warum unbounded? Weil die Alternative auf eine leicht zu übersehende
Weise schlechter ist. Zwischen v0.10 und v0.15 war der Default bounded
— 10 000 Nachrichten, drop-head — und das Framework verwarf still die
älteste wartende Nachricht, sobald ein Actor zurückfiel. Der Handel
sollte lauten “ein paar Nachrichten verlieren, dafür eine
Speicherdecke gewinnen”, und er ging nicht auf:
-
Die Decke gab es nie. Nur die User-Queue war begrenzt. System-Nachrichten — Lifecycle, Supervision, Watch — waren nie gedeckelt, ein Node konnte den Heap also trotzdem ausschöpfen.
-
Eine Mailbox weiß nicht, was sie verwirft.
drop-headpasst zu Telemetrie, wo nur der frischeste Messwert zählt. Zu einer Delivery-Bestätigung oder einem WebSocket-closepasst es nicht — und die liefen durch dieselbe Queue. Aus jedem dieser Fälle wurde ein gemeldeter Defekt.Drei Nachrichten sind inzwischen für jede Policy unerreichbar: das
Terminatedder Death Watch, das Kommando, das den Actor einer WebSocket-Verbindung spawnt, und dascloseeben dieser Verbindung. Alle drei nehmen eine Spur, die keine Schranke abwerfen kann (siehe Death Watch und Eine eigene Mailbox weiter unten). Der Test, den sie bestehen: jede wird genau einmal gesendet, und nichts hält mehr, was zum erneuten Senden nötig wäre — und wer eine davon verliert, verliert keine Nachricht, sondern einen Zustand außerhalb der Mailbox, den nichts mehr korrigiert: einen Watcher, der einen toten Actor für lebendig hält, einen aufgewerteten Socket, an dem niemand hängt, einen Peer, den du trennen wolltest und nicht getrennt hast. Der Rest ist Anwendungsverkehr, und nur du weißt, welcher davon verzichtbar ist.
Der Verlust ist jetzt also etwas, das du anforderst — pro Actor an der
Spawn-Stelle, pro Pfad aus der Konfiguration über einen
actor-ts.deployment-Eintrag, oder einmal für ein ganzes Deployment über
actor-ts.mailbox.default.capacity, das jeden Actor begrenzt, den deine
Anwendung geschrieben hat — Sharded Entities und Cluster Singletons
eingeschlossen, obwohl das Framework diese spawnt — und die eigenen
Actors des Frameworks in Ruhe lässt.
Dieser Key wird als 0 ausgeliefert, also aus, und ihn einzuschalten
ist dieselbe Entscheidung wie das Begrenzen eines Actors, nur für alle
auf einmal: siehe
Mailbox-Dimensionierung dafür,
was er erreicht und was nicht.
Das Wachstum wiederum ist etwas, von dem du erfährst: ein Actor, dessen Queue 10 000
Nachrichten erreicht, loggt eine Warnung — und erneut bei jeder
Verdopplung. Mit aktivierten Metriken meldet actor_mailbox_size die
Tiefe pro Actor oberhalb dieser Marke, und actor_mailbox_depth die
gesamte Verteilung darunter — ein Ausschlag, der die Warnschwelle nie
erreicht, bleibt damit trotzdem sichtbar.
Eine Queue ohne Decke muss billig bleiben, wenn sie tief wird — deshalb
liegt beiden Queues einer Mailbox ein
RingBuffer zugrunde und kein einfaches
Array: die nächste Nachricht zu entnehmen rückt einen Index vor, statt
alles dahinter neu zu indizieren. Die Kosten, eine Nachricht
auszuliefern, wachsen also nicht mit dem Backlog, der dahinter wartet.
Von außen ist das unsichtbar — auch für eine eigene Mailbox-Subklasse,
die nur die Methoden sieht.
Wann eine Mailbox begrenzen
Abschnitt betitelt „Wann eine Mailbox begrenzen“Greif zu einem Bound, wenn Last abwerfen besser ist als Last aufnehmen, und du sagen kannst, welche Nachrichten verzichtbar sind:
- Eine Telemetrie- oder Sensor-Senke, bei der nur der neueste
Messwert zählt.
drop-headhält die Queue frisch. - Ein Admission-Punkt vor einer teuren Pipeline, wo du Arbeit
lieber ablehnst als einreihst.
drop-newbehält, was du schon angenommen hast,rejectsagt dem Sender, er soll zurückstecken. - Jeder Actor, der einem Producer ausgesetzt ist, den du nicht kontrollierst — dort ist eine unbegrenzte Queue eine Denial-of-Service-Fläche. Lies den dritten Punkt mit den ersten beiden: er sagt, wo ein Bound eine Überlegung wert ist, nicht dass der Verkehr dort verzichtbar wäre. Ein WebSocket-Hub ist der deutlichste Fall von beidem zugleich — siehe Die Mailbox des Hubs begrenzen dazu, was ein Bound dort kostet und was nicht.
import { ActorOptions } from 'actor-ts';
const sensorOptions = ActorOptions.create() .withMailboxCapacity(10_000) .withMailboxOverflow('drop-head');
system.spawn(SensorSink, 'sensors', sensorOptions);Die Kapazität ist das, was den Bound erzeugt; withMailboxOverflow
entscheidet, welche Nachricht verloren geht, und steht per Default auf
drop-head. Eine Policy ohne Kapazität wird abgelehnt statt still
ignoriert — eine unbounded Mailbox läuft nie über, hätte also nichts
zu tun. Diese Ablehnung gilt auch dort, wo die Konfiguration eine
Schranke liefert — actor-ts.mailbox.default.capacity oder ein
Deployment-Eintrag: der Validator läuft am Spawn-Aufruf und weiß nichts
über das System, in das der Actor gespawnt wird — nenne die Kapazität also
mit, wenn du eine konfigurierte Schranke für einen einzelnen Actor umformen
willst.
Unter beiden Feldern liegen zwei Config-Ebenen: der
actor-ts.deployment-Eintrag,
der zum Pfad des Actors passt, mit seinem mailbox-capacity und
mailbox-overflow, und darunter actor-ts.mailbox.default.capacity und
.overflow. Die Spawn-Stelle gewinnt immer; der Eintrag entscheidet für
die Pfade, die er nennt, und der Block für jeden anderen Actor, der nichts
gesagt hat.
Die drei Policies und wie du zwischen ihnen wählst, stehen unten unter
BoundedMailbox — inklusive der Frage, warum
reject den Sender scheitern lässt und nicht den langsamen Actor.
Drops aus einer Kapazität, die du gesetzt hast, zählt
actor_mailbox_dropped_total, gelabelt mit Klasse und der Policy, die
gegriffen hat. Pro Klasse, nicht pro Actor: Abwerfen ist das, wofür
eine beschränkte Mailbox da ist — ein Label pro Actor würde also für
jeden Actor, der sich exakt wie vorgesehen verhält, eine dauerhafte
Metrik-Serie erzeugen. Um zu sehen, welche Instanz abwirft, ergänze ein
eigenes onDrop; es läuft neben dem Stock-Counter statt an seiner
Stelle — und es bekommt den verworfenen Envelope, kann also sagen, was
verloren ging, und nicht nur, dass etwas verloren ging.
Um diesen Envelope zu behalten statt ihn nur im Vorbeigehen anzusehen,
baue die Mailbox mit deadLetterDrops: true: Jede verworfene Nachricht
wird dann zu einem Dead Letter, mit
erhaltenem Sender. Der Schalter ist standardmäßig aus und nur von einer
selbst konstruierten Mailbox aus erreichbar — der Drop läuft auf dem Stack
des Senders, jeden abgeworfenen Envelope zu leiten ist also Arbeit, die
genau dem Burst berechnet wird, den die Schranke billig abfedern sollte.
Siehe Mailbox-Sizing.
Eine eigene Mailbox mitbringen
Abschnitt betitelt „Eine eigene Mailbox mitbringen“withMailbox ersetzt die Queue vollständig — für eine
PriorityMailbox, eine ControlAwareMailbox, eine BoundedMailbox
jenseits dessen, was die zwei Optionen oben ausdrücken, oder für eine
eigene Subklasse:
import { ActorOptions, PriorityMailbox } from 'actor-ts';
const triageOptions = ActorOptions.create() .withMailbox(() => new PriorityMailbox({ priorityFor: (m) => m.urgency }));
system.spawn(Triage, 'triage', triageOptions);Die Mailbox gehört dir, ihre Drops werden trotzdem gezählt: die Cell
registriert einen Observer auf dem, was du zurückgibst — sofern es
DropReportingMailbox implementiert. BoundedMailbox tut das, und eine
eigene Mailbox-Subklasse kann es mit einer Methode:
import { Mailbox, type Envelope, type MailboxDropObserver } from 'actor-ts';
class SheddingMailbox<T> extends Mailbox<T> { private readonly observers: Array<MailboxDropObserver<T>> = []; readonly deadLetterDrops = true;
observeDrops(observer: MailboxDropObserver<T>): void { this.observers.push(observer); }
override enqueue(envelope: Envelope<T>): void { if (this.shouldShed()) { for (const observer of this.observers) observer('drop-new', envelope); return; } super.enqueue(envelope); }}Eine Meldung trägt neben dem Grund auch den Envelope, und
deadLetterDrops sagt, ob die Cell daraus jeweils einen
Dead Letter machen soll. Übergib den
Envelope, den du wirklich verworfen hast — unter einer Policy in
drop-head-Form ist das der herausgeworfene, nicht der angekommene, sonst
benennt jeder Letter eine Nachricht, die noch in der Queue liegt. Beides
ist optional: Lässt du das Feld weg, wird der Drop gezählt und sonst
nichts — genau das, was BoundedMailbox tut, solange du nichts anderes
verlangst.
Das Registrieren ist additiv, ein eigenes BoundedMailboxOptions.onDrop
feuert also weiter neben dem Standard-Counter. Was nicht geht, ist
withMailbox mit withMailboxCapacity zu kombinieren — das ist ein
Konfigurationsfehler, keine stille Vorrangregel.
Eine Pflicht: enqueueSignal
Abschnitt betitelt „Eine Pflicht: enqueueSignal“Eine Queue, die abwirft, hat eine kurze Liste von Dingen, die sie nicht
abwerfen darf: die vier Envelopes, die das Framework genau einmal
schickt, ohne dass irgendwo noch etwas läge, aus dem es sie erneut
schicken könnte. Ein Terminated der Death Watch — siehe
Death Watch — kommt bei einem lokalen
Tod direkt vom sterbenden Actor und bei einem Tod, den ein anderer Node
gemeldet hat, nach einem Hop über die System-Queue; ein WebSocket-Hub
bekommt das Kommando, das den Actor einer Verbindung spawnt; der Actor
einer Verbindung bekommt sein eigenes close; und ein Actor, der einen
Key von DistributedData subscribed
hat, bekommt das DistributedDataChanged, das ihm den neuesten Wert des
Keys mitteilt. Alle kommen über enqueueSignal statt über enqueue,
und der Vertrag lautet: reihe es ein, was deine Schranke auch sagt:
class SheddingMailbox<T> extends Mailbox<T> { // ...wie oben...
/** Absichtlich an der Schranke vorbei: dieses eine ist nicht erneut sendbar. */ override enqueueSignal(envelope: Envelope<T>): void { super.enqueue(envelope); }}Die Basisimplementierung delegiert an dein enqueue, was für eine Queue
richtig ist, die nichts verwirft, und für eine, die es tut, falsch —
also überschreibe sie immer dann, wenn du enqueue zum Abwerfen
überschreibst. BoundedMailbox, PriorityMailbox und
ControlAwareMailbox tun das schon.
Dass die Basis delegiert statt direkt in die Basis-Queue zu schreiben,
ist Absicht: eine Subklasse kann ihre Nachrichten ganz woanders halten,
und ein Envelope, das in einem Speicher versteckt liegt, den dein
dequeueUser nie liest, ist schlimmer als eines, das du verworfen hast.
Das Envelope trägt außerdem undroppable: true, was removeOldest
liest — eine Schranke in drop-head-Form, die auf dieser Nahtstelle
aufsetzt, überspringt es damit gratis und muss nicht wissen, warum.
Wirft dein enqueue stattdessen, macht das Framework aus der
Verweigerung ein Dead Letter und der
Abbau des sterbenden Actors läuft weiter; was es nicht kann, ist eine
zweite Kopie der Benachrichtigung erfinden. Ein abgelehntes
DistributedDataChanged loggt stattdessen der Replicator, und die
nächste Änderung am Key versucht es erneut.
Das DistributedDataChanged ist das neueste der vier, und es steht aus
demselben Grund auf der Liste wie die anderen, nicht wegen seines
Inhalts. Der Replicator hält pro Subscriber und Key höchstens eine
Benachrichtigung in der Schwebe: Solange eine in deiner Queue wartet,
überschreiben spätere Änderungen ihren Wert an Ort und Stelle, und die
nächste wird erst gepostet, wenn dein Actor sie übergeben bekommen hat.
Wirfst du sie ab, wird sie nie übergeben — der Replicator wartet weiter,
jede spätere Änderung landet in einer Nachricht, die niemand liest, und
der Actor erfährt nie wieder etwas über diesen Key. Das kostet deine
Schranke höchstens ein Envelope pro subscribtem Key, und die
Benachrichtigung behält ihren Platz am Ende, während ihr Wert
überschrieben wird.
Nicht verwerfbar heißt nicht vordrängeln. Die Tür entscheidet, dass
ein Signal deine Schranke übersteht, nie, wo es landet: reihe es dort
ein, wo du jede andere Nachricht einreihen würdest, auf einer FIFO-Queue
also am Ende. Zwei der vier verlassen sich darauf — die Death Watch
verspricht, dass alles, was dem Watcher bereits gesagt wurde, vor dem
Terminated behandelt wird, und eine Antwort, die vor einem
WebSocket-close() eingereiht wurde, wird geschrieben, bevor der Socket
schließt. Eine Queue, die Nachrichten nach ihrer eigenen Regel ordnet,
ordnet Signale nach derselben Regel: PriorityMailbox rangiert ein
Terminated mit deinem priorityFor. Und eine Queue, die manche
Nachrichten den Rest überholen lassen soll, sagt das, indem sie sie
klassifiziert, so wie es ControlAwareMailbox
tut — nie, indem sie alles nach vorne zieht, was durch diese Tür kam.
System-Nachrichten kommen immer zuerst
Abschnitt betitelt „System-Nachrichten kommen immer zuerst“In jeder Mailbox leben zwei Queues nebeneinander: User-Nachrichten
(deine tells) und System-Nachrichten (Lifecycle-Signale —
Create, Terminate, Failure, Watch, …). System-Nachrichten haben
absoluten Vorrang: selbst wenn 10.000 User-Nachrichten in der
Queue stehen, wird das nächste stop-Signal oder die
Supervisor-failure vor allen verarbeitet.
Das ist wichtig, weil:
ref.stop()aufzurufen springt nicht in der Queue vor — unter der Haube ist es eine User-Nachricht (PoisonPill), der Actor drained also erst die User-Nachrichten, die bereits davor in der Queue stehen, und stoppt dann (ein sauberes Drain-dann-Stop). Nur vom Framework emittierte System-Nachrichten bekommen den absoluten Vorrang von oben.- Die Supervisor-Entscheidung eines fehlschlagenden Actors (Restart / Resume / Stop) tritt sofort in Kraft, nicht erst nachdem die Queue leer ist.
- Ein
Terminatedder Death Watch ist ebenfalls eine User-Nachricht, aus demselben Grund wiePoisonPill: es muss nach allem ankommen, was dem Watcher bereits gesagt wurde, damit ein Handler, der auf einen Tod reagiert, die Arbeit davor gesehen hat. Nicht verwerfbar heißt nicht vordrängeln — es behält seinen Platz in der Reihe und kann nur nicht mehr daraus entfernt werden. Das gilt für jedes Signal, das das Framework auf diesem Weg schickt, nicht nur für dieses: eine Nachricht überholt die User-Queue nur auf einer Mailbox, die Nachrichten klassifiziert, wieControlAwareMailbox, und nur, wenn ihr Prädikat es sagt — deins, oder auf einem WebSocket-Hub das des Frameworks.
Eine Mailbox-Kapazität begrenzt nur die User-Queue. Die
System-Queue wird nie gedeckelt — weder von BoundedMailbox noch von
einer eigenen Mailbox —, weil Supervision- und Lifecycle-Signale niemals
verworfen werden dürfen. Ihre Tiefe begrenzt stattdessen das, was sie
erzeugt: ein create pro Actor und ein terminate pro Stopp, ein
childTerminated pro Kind, das fertig gestoppt hat, ein failure pro
Supervisor-Entscheidung plus das suspend / resume / recreate, das
diese Entscheidung über den betroffenen Teilbaum verteilt, ein
receiveTimeout pro abgelaufenem Timer und ein watchNotify pro
Terminated, das von einem anderen Node eintrifft — für einen
Remote-Actor, den die eigenen Actors dieses Nodes beobachtet haben, oder
für einen Node, in den sie Watches hielten und der den Cluster verlassen
hat. Für jedes davon musste vorher ein Actor existieren, der es bezahlt
hat, oder ein Watch, den einer von ihnen registriert hat.
Eine lokale Death-Watch-Benachrichtigung steht nicht auf dieser
Liste. Das Terminated eines lokal beobachteten Actors landet in der
User-Queue seines Watchers — an der Schranke vorbei, wie oben, aber
weiterhin hinter allem, was diesem Watcher schon gesagt wurde. Tausend
lokal beobachtete Actors erhöhen die System-Queue also um gar nichts.
Ein Terminated, das ein anderer Node meldet, nimmt einen Hop über die
System-Queue, um zu genau diesem User-Queue-Signal zu werden; ein Peer
kann höchstens eines pro Watch schicken, den dieser Node eröffnet hat,
und ein unaufgefordertes trifft auf nichts.
Du siehst diese Unterscheidung normalerweise nicht — System-Nachrichten werden vom Framework emittiert, nicht von deinem Code. Aber sie zu verstehen, erklärt, warum “Supervision sofort reagiert.”
BoundedMailbox
Abschnitt betitelt „BoundedMailbox“import { ActorOptions, Actor, ActorSystem, BoundedMailbox } from 'actor-ts';
class SlowConsumer extends Actor<{ kind: 'work'; n: number }> { override async onReceive(message: { kind: 'work'; n: number }): Promise<void> { await new Promise(r => setTimeout(r, 100)); // langsame Arbeit simulieren this.log.info(`processed ${message.n}`); }}
const system = ActorSystem.create('demo');
const consumerOptions = ActorOptions.create() .withMailbox(() => new BoundedMailbox({ capacity: 1_000, overflow: 'drop-head' }));
const consumer = system.spawn( SlowConsumer, 'consumer', consumerOptions,);Die Mailbox hier hält bis zu 1.000 User-Nachrichten. Wenn eine 1.001-te Nachricht ankommt, entscheidet die Overflow-Policy, was passiert.
Drei Policies:
| Policy | Was bei Overflow passiert |
|---|---|
'drop-head' | Dequeue die älteste Nachricht in der Queue, verwirf sie, reihe die neue ein. Neueste Nachrichten kommen immer rein. |
'drop-new' | Verwirf die eingehende Nachricht. Die alte Queue bleibt unverändert. |
'reject' | Wirf MailboxFullError an der tell-Stelle. Der Aufrufer trägt den Backpressure. |
Welche du bekommst, wenn du keine nennst, hängt davon ab, durch welche
Tür du gekommen bist — und der Unterschied ist Absicht: eine
BoundedMailbox selbst zu konstruieren steht per Default auf
reject, weil du einen Bound gebaut hast und sonst nichts darüber
angenommen werden kann, was verzichtbar ist. withMailboxOverflow
steht per Default auf drop-head, der Policy, die zu den Workloads
passt, für die man tatsächlich zu einem Bound greift. Nennst du die
Policy, stellt sich die Frage gar nicht.
Die Optionen werden bei der Konstruktion validiert: eine fehlende oder
nicht-positive capacity und eine unbekannte Overflow-Policy werfen
OptionsError.
capacity begrenzt die Nachrichten, die die Mailbox verwerfen darf —
in einer Mailbox, die nur noch nicht zugestellte Todesmeldungen enthält,
liegt die Queue also darüber, statt eine davon zu verlieren. Der
Überschuss ist durch die Zahl der beobachteten Actors begrenzt — und
durch die Zahl der DistributedData-Keys, die der Actor subscribed hat,
eine Benachrichtigung je Key — und ist der Preis der Ausnahme, die
Death Watch beschreibt: bemiss eine
Kapazität an deinem Verkehr, nicht aufs Byte.
Die Wahl zwischen ihnen ist ein Backpressure-vs-Verlust-Trade-off:
drop-head= “Frisch gewinnt.” Richtig für Telemetrie, Sensor-Daten, Status-Pings — wo veraltete Nachrichten wertlos sind und nur der letzte Snapshot zählt.drop-new= “Erst gewinnt.” Richtig für Command-Streams, bei denen Umordnung inakzeptabel ist und das Verwerfen einer späten Ankunft okay ist.reject= “Lass den Sender damit umgehen.” Richtig, wenn der Sender eine sinnvolle Backoff-Antwort hat (Retry, an einen anderen Actor routen, 503 aus einem HTTP-Handler zurückgeben).
droppedCount auf der Mailbox-Instanz verfolgt, wie viele
Nachrichten verworfen wurden — nützlich, um es in eine Metrik-Gauge
zu verdrahten, damit du es bemerkst, wenn das Limit getroffen wird.
PriorityMailbox
Abschnitt betitelt „PriorityMailbox“import { ActorOptions, Actor, ActorSystem, PriorityMailbox } from 'actor-ts';
type Message = | { readonly kind: 'urgent'; readonly text: string } | { readonly kind: 'normal'; readonly text: string } | { readonly kind: 'bulk'; readonly text: string };
class Worker extends Actor<Message> { override onReceive(message: Message): void { this.log.info(`[${message.kind}] ${message.text}`); }}
const workerOptions = ActorOptions.create<Message>() .withMailbox(() => new PriorityMailbox<Message>({ priorityFor: (message) => message.kind === 'urgent' ? 0 : message.kind === 'normal' ? 5 : 10, }));
const worker = system.spawn( Worker, 'worker', workerOptions,);
worker.tell({ kind: 'bulk', text: 'batch import row 1' });worker.tell({ kind: 'normal', text: 'user login' });worker.tell({ kind: 'urgent', text: 'page-out: disk full' });// → Verarbeitungs-Reihenfolge: urgent → normal → bulkDer priorityFor-Callback läuft zur Enqueue-Zeit und berechnet
eine numerische Priorität pro Nachricht. Niedrigere Zahlen gehen
zuerst (Priorität 0 ist am höchsten), und Gleichstände werden nach
FIFO-Insertion-Reihenfolge gebrochen — zwei 'normal'-Nachrichten
bleiben also in Sende-Reihenfolge zueinander.
Häufige Formen für priorityFor:
- Per-
kind-Konstantentabelle — wie das Beispiel oben. Einfach zu lesen, einfach zu evolvieren. - Feld-abgeleitet —
priorityFor: (m) => m.deadlineMslässt Nachrichten mit frühesten Deadlines zuerst laufen. Funktioniert, weil beide Achsen “niedriger = früher” sind. - Caller-getagged — der Sender inkludiert
priority: numberin der Nachricht, undpriorityForliest es einfach. Manchmal der richtige Anruf; meist ein Smell, dass der Empfänger die Priorität stattdessen aus dem Nachrichteninhalt ableiten sollte.
Wenn priorityFor nicht antworten kann
Abschnitt betitelt „Wenn priorityFor nicht antworten kann“Dein Callback muss nicht total sein. Wenn er wirft oder mit etwas
antwortet, das keine brauchbare Zahl ist — undefined, NaN, ein Wert
eines anderen Typs — landet die Nachricht mit der niedrigsten
Priorität in der Queue, und mehr passiert nicht. Sie wird nicht
verworfen, und der Fehlschlag taucht nicht an der tell-Stelle auf.
Beide Hälften sind wichtig:
- Niedrigste, nicht höchste. Eine Priorität, die nicht bestimmbar war, darf keine überholen, die angegeben wurde. Gleichstände brechen weiterhin nach FIFO, unrangierbare Nachrichten bleiben also zueinander in Sende-Reihenfolge.
- Eingefangen, nicht geworfen.
priorityForläuft synchron innerhalb destelldes Senders. Der Sender ist ein Unbeteiligter der Mailbox-Konfiguration des Empfängers: er kann gegen ein defektespriorityFornichts tun und kann es nicht von einem eigenen Fehler unterscheiden. Ein entkommender Throw landete imonReceivedes Senders und ließ den Sender neu starten — dieselbe Verwirrung, die diereject-Warnung oben beschreibt, für einen Bug, der mit dem Sender überhaupt nichts zu tun hat.
±Infinity ist eine Rangfolge, kein Fehlschlag: -Infinity bedeutet
“vor allem anderen”, +Infinity bedeutet “hinter allem anderen”, und
beide werden so geordnet, wie sie geschrieben sind. Nur NaN und
Nicht-Zahlen gelten als unbestimmbar.
Um einen eingefangenen Fehlschlag zu sehen und nicht nur seine Folgen,
übergib onPriorityError. Nichts anderes im System meldet einen — die
Nachricht kommt weiterhin an, nur zuletzt:
import { PriorityMailbox, PriorityMailboxOptions } from 'actor-ts';
const triageOptions = PriorityMailboxOptions.create<Message>() .withPriorityFor((message) => message.kind === 'urgent' ? 0 : 10) .withOnPriorityError((cause, message) => { log.warn(`priorityFor could not rank ${JSON.stringify(message)}: ${String(cause)}`); });
const mailbox = new PriorityMailbox<Message>(triageOptions);cause ist, was priorityFor geworfen hat, oder ein TypeError, der
den zurückgegebenen Wert beschreibt. Aufzeichnen und zurückkehren
im Hook: er läuft ebenfalls auf dem Stack des Senders, ein Throw aus ihm
heraus setzt das Entkommen also wieder ein — und kostet die Nachricht
ihren Platz in der Queue.
Die aktuelle Implementierung verwendet ein sorted-insertion-Array — O(log n) Locate + O(n) Splice bei jedem Enqueue. In Ordnung für Mailboxes, die in den niedrigen Tausenden bleiben; wenn du einen nachhaltigen 10.000-Nachrichten-Backlog hast, bei dem Priority-Insertion in Profilen auftaucht, ist die Mailbox offen für einen Heap-backed-Swap (siehe den Source).
Eine Priority-Mailbox begrenzen
Abschnitt betitelt „Eine Priority-Mailbox begrenzen“Eine Priority-Mailbox ist unbounded, solange du ihr keine capacity
gibst — genau wie jede andere Mailbox. Der Bound liegt auf den Options
der Mailbox selbst und nicht auf ActorOptions, weil withMailbox und
withMailboxCapacity sich nicht kombinieren lassen: eine übergebene
Mailbox bringt ihren eigenen Bound mit:
import { ActorOptions, PriorityMailbox, PriorityMailboxOptions } from 'actor-ts';
const triageOptions = PriorityMailboxOptions.create<Message>() .withPriorityFor((message) => message.kind === 'urgent' ? 0 : 10) .withCapacity(10_000) .withOverflow('drop-lowest-priority');
const workerOptions = ActorOptions.create<Message>() .withMailbox(() => new PriorityMailbox<Message>(triageOptions));Die Policies sind 'drop-lowest-priority', 'drop-new' und 'reject',
und reject bekommst du, wenn du eine Capacity ohne Policy nennst — eine
Capacity zu nennen sagt, wie viel du hältst, nicht was du bereit bist zu
verlieren.
| Policy | Was bei Overflow passiert |
|---|---|
'drop-lowest-priority' | Verwirft die Nachricht, die am weitesten von der Auslieferung entfernt ist — die mit der niedrigsten Priorität, unter Gleichen die zuletzt angekommene. Die eingehende Nachricht tritt zu denselben Bedingungen an: eine, die unter dem gesamten Backlog rangiert, ist selbst die, die geht. |
'drop-new' | Verwirft die eingehende Nachricht, egal welche Priorität sie bekommen hat. |
'reject' | Wirft MailboxFullError an der tell-Stelle. |
drop-head gibt es hier bewusst nicht. Auf einer FIFO-Queue heißt
es “verwirf die abgestandenste”, und das trägt, weil Ankunftsreihenfolge
dort die einzige Ordnung ist. Auf einer Priority-Queue ist der Kopf die
Nachricht, die dein priorityFor als wichtigste bezeichnet hat — sie zu
verwerfen würde den Grund zunichtemachen, aus dem du diese Mailbox
gewählt hast. Drops werden weiterhin als drop-head an
actor_mailbox_dropped_total gemeldet (dieses Label hat ein
geschlossenes Zwei-Werte-Vokabular), außer wenn die verworfene Nachricht
die eingehende war — dann lautet der Grund drop-new.
Die Options werden bei der Konstruktion validiert: ein fehlendes oder
nicht aufrufbares priorityFor, eine nicht-positive capacity, eine
unbekannte Policy oder eine Policy ohne Capacity werfen alle
OptionsError. Was der Callback zurückgibt, ist eine Laufzeitfrage
und wird stattdessen beim Enqueue behandelt — siehe
Wenn priorityFor nicht antworten kann.
Auf einer begrenzten Mailbox treffen sich beide: eine unrangierbare
Nachricht ist das Unwichtigste in der Queue, unter
drop-lowest-priority wird also die Ankunft abgeworfen und als
drop-new gemeldet.
ControlAwareMailbox
Abschnitt betitelt „ControlAwareMailbox“import { Actor, ActorOptions, ActorSystem, ControlAwareMailbox, ControlAwareMailboxOptions } from 'actor-ts';
type PauseCommand = { readonly kind: 'pause' };type ResumeCommand = { readonly kind: 'resume' };type ReadingCommand = { readonly kind: 'reading'; readonly value: number };type IngestCommand = PauseCommand | ResumeCommand | ReadingCommand;
class Ingest extends Actor<IngestCommand> { override onReceive(command: IngestCommand): void { this.log.info(`handled ${command.kind}`); }}
// Name the control kinds rather than excluding the rest — see the cautions below.const isControl = (command: IngestCommand): boolean => command.kind === 'pause' || command.kind === 'resume';
const ingestMailboxOptions = ControlAwareMailboxOptions.create<IngestCommand>() .withIsControl(isControl) .withCapacity(10_000) .withOverflow('drop-head');
const newIngestMailbox = () => new ControlAwareMailbox<IngestCommand>(ingestMailboxOptions);const ingestOptions = ActorOptions.create<IngestCommand>().withMailbox(newIngestMailbox);
const system = ActorSystem.create('demo');const ingest = system.spawn(Ingest, 'ingest', ingestOptions);
ingest.tell({ kind: 'reading', value: 1 });ingest.tell({ kind: 'reading', value: 2 });ingest.tell({ kind: 'pause' });// → handled order: pause → reading → readingEine ControlAwareMailbox hält zwei FIFO-Queues und gibt dem Actor jede
Control-Nachricht vor jeder gewöhnlichen, innerhalb jeder Klasse in
Ankunftsreihenfolge. Welche welche ist, entscheidet das Prädikat, das du
als isControl übergibst — einmal pro Nachricht, beim Eintreffen. Sonst
ändert sich nichts: System-Nachrichten kommen weiterhin zuerst, und von
sich aus stuft das Framework Nachrichten nur bei einem einzigen Actor als
Control ein — beim WebSocket-Hub, siehe unten.
Greif zu ihr, wenn einige wenige Sorten von Nachrichten nicht hinter einem
Backlog des Rests warten dürfen — ein Pause- oder
Rekonfigurations-Kommando vor einer Flut von Messwerten, ein
administratives Kommando vor einem Datenstrom. Wo du eine vollständige
Ordnung nach Wichtigkeit willst statt zweier Klassen, ist eine
PriorityMailbox das Werkzeug; wo alles in der gesendeten Reihenfolge
bleiben muss, keine von beiden.
Der WebSocket-Hub hat standardmäßig eine
Abschnitt betitelt „Der WebSocket-Hub hat standardmäßig eine“Ein WebsocketServerActor
bekommt eine ControlAwareMailbox, ohne dass man ihn darum bitten muss —
es sei denn, er wird mit einer eigenen Mailbox gespawnt. Seine
Control-Nachrichten sind das Kommando, das ihm einen aufgewerteten Socket
übergibt, und das Signal onClientConnected, das die neue Verbindung
meldet; Frames, Disconnects und deine eigenen Nachrichten an den Hub
bleiben gewöhnlich. Eine neue Verbindung wird also vor dem Rückstau jeder
anderen Verbindung aufgebaut und von keiner Grenze verworfen, während die
Reihenfolge pro Verbindung — connected, Nachrichten, disconnected — bleibt,
wie sie war. Eine Kapazität, die der Hub sonst gehabt hätte, aus
withMailboxCapacity(), einem actor-ts.deployment-Eintrag für seinen Pfad
oder actor-ts.mailbox.default.capacity, wird zur Kapazität der
gewöhnlichen Klasse. withMailbox(...) ersetzt die Queue
und die Control-Spur gleich mit.
Eine Control-Aware-Mailbox begrenzen
Abschnitt betitelt „Eine Control-Aware-Mailbox begrenzen“Eine capacity begrenzt nur die gewöhnliche Klasse, und die drei
BoundedMailbox-Policies — 'drop-head', 'drop-new', 'reject' —
wirken allein auf sie. Eine Control-Nachricht wird nie abgeworfen, nie
abgelehnt, nie als Drop gezählt und lässt reject nie werfen: die Flut,
die eine Schranke abwirft, ist genau der Traffic, den die
Control-Nachricht überholen soll. Die Capacity ist also eine Obergrenze
für die gewöhnliche Klasse, und die Control-Klasse begrenzt, was sie
schickt — ein Grund mehr, das Prädikat auf die wenigen Sorten zu
beschränken, die überholen müssen. Ohne Policy angegeben bedeutet eine
Capacity reject, wie bei jeder Mailbox, die du selbst konstruierst.
unstashAll() setzt jede Nachricht an den Kopf ihrer eigenen Klasse
zurück, und die gewöhnliche Hälfte trifft auf die Schranke wie das
Replay einer BoundedMailbox. Drops erreichen
actor_mailbox_dropped_total und dein onDrop, und
deadLetterDrops: true macht aus jedem einen
Dead Letter.
Die Options werden bei der Konstruktion validiert: ein fehlendes oder
nicht aufrufbares isControl, eine nicht-positive capacity, eine
unbekannte Policy sowie eine Policy oder deadLetterDrops ohne Capacity
werfen alle OptionsError.
Wenn isControl nicht antworten kann
Abschnitt betitelt „Wenn isControl nicht antworten kann“isControl läuft im tell des Senders und wird deshalb genauso
eingehegt wie priorityFor: wirft es oder antwortet es irgendetwas
anderes als true, ist die Nachricht gewöhnlich, und das tell geht
durch. Gewöhnlich ist dabei nicht nur die sichere Antwort, sondern die
richtige — es ist die Klasse, die die Nachricht auf jeder anderen Mailbox
gehabt hätte.
Eingehegt heißt nicht stumm. Ein Prädikat, das bei jeder Nachricht wirft —
meist eine Methode, die ohne ihre Instanz übergeben wurde —, macht aus der
Mailbox eine schlichte FIFO-Queue, während jede Nachricht weiter ankommt;
deshalb loggt die Mailbox den ersten Wurf auf warn. Einmal pro Mailbox,
weil das Prädikat bei jedem tell läuft; und nur mit Klassennamen — der
Klasse der Nachricht, bei der es geworfen hat, und der dessen, was es
geworfen hat, nie mit der Nachricht oder dem Text des Fehlers, denn der
Fehler eines erschöpfenden Matchers zitiert den Wert, den er nicht zuordnen
konnte. Um jeden Wurf zu sehen oder ihn an deinen eigenen Logger zu geben,
übergib onControlError:
const ingestMailboxOptions = ControlAwareMailboxOptions.create<IngestCommand>() .withIsControl(isControl) .withOnControlError((cause) => { log.warn(`isControl threw: ${String(cause)}`); });cause ist, was das Prädikat geworfen hat. Ein Hook, den du übergibst,
ersetzt die Log-Zeile, und es gilt dieselbe Regel wie bei
onPriorityError: Aufzeichnen und zurückkehren — er läuft auf dem Stack
des Senders. Eine Antwort, die nicht true ist, ist kein Fehler und
erreicht den Hook nie; sie macht die Nachricht gewöhnlich, wie oben.
Per-Actor-Mailbox via ActorOptions
Abschnitt betitelt „Per-Actor-Mailbox via ActorOptions“Drei Knöpfe auf ActorOptions:
import { ActorOptions, PriorityMailbox } from 'actor-ts';
// Begrenze das Default-FIFO und sag, was eine volle Mailbox verwirft.const cappedOptions = ActorOptions.create() .withMailboxCapacity(500) .withMailboxOverflow('drop-new');
// Volle eigene Factory — wähle den Typ und konfiguriere ihn.const customOptions = ActorOptions.create() .withMailbox(() => new PriorityMailbox({ priorityFor: (m) => m.urgency }));withMailboxCapacity(n) macht aus dem Default-FIFO ein begrenztes;
withMailboxOverflow wählt die Policy, per Default drop-head. Die
Policy allein wird abgelehnt — eine unbounded Mailbox läuft nie über,
das wäre ein No-op, das wie Konfiguration aussieht.
withMailbox(factory) ist die allgemeine Form — du gibst eine
brandneue Mailbox-Instanz aus der Factory zurück. Die Factory wird
einmal pro Actor-Instanz aufgerufen (inklusive bei Restart), jeder
neu gestartete Actor bekommt also eine frische, leere
Mailbox-Datenstruktur. Sie ersetzt die Queue, statt sie zu
konfigurieren: mit withMailboxCapacity kombiniert ist das ein
Konfigurationsfehler statt einer stillen Vorrangregel, und das
Framework verdrahtet keine Drop-Telemetrie in das, was du
zurückgibst.
Der Default ist unbounded: eine Schranke wählst du pro Actor mit diesen
Knöpfen, oder einmal für ein ganzes Deployment mit
actor-ts.mailbox.default.capacity, gegen den die eigene Einstellung
der Spawn-Stelle immer gewinnt — siehe
Mailbox-Dimensionierung für die
Actors, die er erreicht.
Für einen Actor, dessen Spawn-Stelle du nicht ändern kannst, gibt es
dieselben zwei Knöpfe in der Konfiguration, pro Pfad: ein
actor-ts.deployment-Eintrag
setzt mailbox-capacity und mailbox-overflow (und throughput) für die
Actors, die sein Key trifft — "/user/ingest", die Routees von
"/user/pool/routee-*", die Verbindungen von "/user/chat/ws-*". Er
liegt unter den Knöpfen oben und über dem globalen Block:
withMailboxCapacity und withMailbox gewinnen weiterhin, die Kapazität
eines Eintrags gewinnt gegen actor-ts.mailbox.default.capacity, und sein
0 lässt die getroffenen Actors unbegrenzt, egal wie der globale Block
gesetzt ist.
Mailboxes + Stash
Abschnitt betitelt „Mailboxes + Stash“Wenn ein Actor this.context.stash() innerhalb von onReceive
aufruft, wird die aktuelle Nachricht geparkt. Wenn der Actor später
unstashAll() aufruft, werden die geparkten Nachrichten an die
Front der Mailbox re-prepended.
Das funktioniert für jeden Mailbox-Typ gleich — das Framework
ruft mailbox.prependUser(envs), und die Mailbox entscheidet, wie
sie re-inserted. Besonders bei PriorityMailbox: unstashed
Nachrichten werden re-priorisiert: eine gestashte
bulk-Nachricht reiht sich wieder in die bulk-Schicht ein, selbst
wenn du sie gestasht hast, während dringende Nachrichten ankamen.
Stash-Reihenfolge wird innerhalb einer Priority-Schicht bewahrt. Eine
ControlAwareMailbox setzt jede Nachricht an den Kopf ihrer eigenen
Klasse zurück; eine gestashte Control-Nachricht wird also weiterhin vor
den gewöhnlichen übergeben.
Ein Bound gilt auch für das Replay. Welche begrenzte Mailbox du
auch gewählt hast: unstashAll() unterliegt der Capacity und der
Overflow-Policy, die du gesetzt hast — ein Replay ist Traffic, der
wieder in die Queue eintritt, keine Hintertür daran vorbei.
Unterschiedlich ist nur, woher der Platz kommt: PriorityMailbox
re-priorisiert, und BoundedMailbox setzt das Replay an die Front und
schafft am Ende der Queue Platz — eine volle Mailbox verliert also ihre
neuesten Nachrichten statt der bewusst geparkten; eine
ControlAwareMailbox tut dasselbe auf ihrer gewöhnlichen Klasse. Unter reject geht
gar nichts verloren: unstashAll() wirft MailboxFullError, der
gesamte Batch bleibt gestasht, und der Fehler erreicht den Supervisor
deines Actors wie jeder andere. Dimensioniere die Capacity für den
Backlog plus das, was du zu stashen erwartest — oder nimm die Drops
als Preis des Bounds in Kauf.
Eine Ausnahme, und es ist dieselbe wie überall sonst. Ein Envelope
mit undroppable — ein Terminated aus der Death Watch, ein
WebSocket-Accept- oder -Close-Command, eine Änderungsbenachrichtigung
von DistributedData — wird auch auf dem Rückweg an der Schranke vorbei
aufgenommen. Die Markierung reist auf dem Envelope
mit, statt von der Queue erinnert zu werden, genau damit sie einen
context.stash()/unstashAll()-Rundlauf übersteht: Eine Schranke
bekommt eine Gelegenheit, eine Benachrichtigung abzuwerfen, und nicht
eine zweite, nur weil der Actor sie zwischendurch geparkt hat.
Das ist eine Aussage über die Schranke, nicht darüber, was der Actor
zu sehen bekommt. Ein Terminated, das unter einem einfachen
watch geparkt wurde, kommt hier hinein und wird dann vom Dispatch
abgelehnt — denn die Registrierung, die der Tod verbraucht hat, ist
genau das, was es eingelassen hätte. Es endet als
Dead Letter statt als zweite
Zustellung. Das ist nicht das Werk der Schranke, und darum lohnt es
sich, beides auseinanderzuhalten: eine Benachrichtigung, die die
Schranke abgeworfen hat, erreicht den Dispatch gar nicht erst und
hinterlässt also auch keinen Dead Letter. Siehe
Death Watch für die Registrierung, die
einen Stash übersteht — watchWith, über dessen Domain-Nachricht die
Death Watch keine Meinung mehr hat. Die WebSocket-Accept- und
-Close-Commands haben keine solche Buchführung und werden normal
erneut zugestellt, und ebenso eine Änderungsbenachrichtigung von
DistributedData — der Replicator hat aufgehört, sie zu überschreiben,
als der Actor sie zum ersten Mal übergeben bekam, sie wird also mit dem
Wert von damals erneut abgespielt.
Siehe Become und Stash für die volle Behavior-Switching-Geschichte.
Wann die Mailbox-Wahl wichtig ist
Abschnitt betitelt „Wann die Mailbox-Wahl wichtig ist“Für die meisten Actors ist die unbounded Default-FIFO richtig. Greife in vier Situationen zu einer Alternative:
- Producer/Consumer-Mismatch. Der Producer kann schneller emittieren, als der Consumer drainen kann. Begrenze die Mailbox des Consumers; wähle eine Overflow-Policy, die zur Workload passt (drop-head für Telemetrie, reject für HTTP-getriebenen Backpressure).
- Latenz-Budget pro Kind. Manche Nachrichten müssen in zehn
Millisekunden behandelt werden (user-facing Requests), andere
können Minuten warten (Hintergrund-Reconciliation).
Priority-Mailbox; die dringende Sorte bekommt
0, die Hintergrund-Sorte bekommt100. - Memory-Bound. Ein Actor ohne Anwendungs-Level-Prioritäts-Unterscheidung,
dessen Queue ohne Limit wächst, wenn er zurückfällt — ein
Audit-Log-Subscriber bei einer Spitze, oder alles, was von einem
Producer gespeist wird, den du nicht kontrollierst. Begrenze ihn auf
eine Zahl, die zu deinem Memory-Budget passt;
drop-head, wenn die neuesten Events am wertvollsten sind,drop-new, wenn es die schon angenommenen sind. Beobachteactor_mailbox_wait_seconds, um das herauszufinden, bevor du es brauchst — sie steigt, sobald ein Actor nicht mehr mitkommt, währendactor_mailbox_sizeerst meldet, wenn eine Queue 10 000 Nachrichten überschreitet. Das p99 vonactor_mailbox_depthist das, woraus du die Zahl selbst wählst: Eine Kapazität ist eine Wette auf den schlimmsten Ausschlag, und dieses Histogramm ist die Messung davon. - Ein Kommando hängt hinter einem Backlog. Einige wenige Sorten von
Nachrichten — eine Pause, eine Rekonfiguration, eine administrative
Anfrage — dürfen nicht hinter einer Flut von allem anderen warten, und
der Rest hat keine Rangfolge, die eine Priority-Mailbox wert wäre.
ControlAwareMailbox; nenne diese Sorten in ihrem Prädikat.
Wie es weitergeht
Abschnitt betitelt „Wie es weitergeht“- Dispatcher — der Scheduler, der aus der Mailbox zieht. Mailbox = die Queue; Dispatcher = wann zu drainen ist.
- Become und Stash —
Nachrichten für später parken, sie via
unstashAllwiederherstellen. - Actor —
onReceiveist das, wohin die Mailbox Nachrichten ausliefert. - Coordinated Shutdown — was mit ausstehenden Mailbox-Nachrichten während des sauberen Shutdowns passiert.
Die BoundedMailbox-,
PriorityMailbox- und
ControlAwareMailbox-API-Referenzen
decken die volle Settings-Form ab.
