Zum Inhalt springen
Deutsch

Throttling

Jeder Actor leert seine Mailbox so schnell, wie sein Dispatcher es zulässt. Throttling setzt eine Ratenbegrenzung pro Actor davor: einen Token-Bucket, den die Runtime vor dem Ausreihen jeder User-Nachricht prüft. So verhinderst du, dass ein Actor einen nachgelagerten Dienst, ein Log-Sink oder eine ratenbegrenzte API überrollt — ohne irgendetwas an den Actors zu ändern, die ihm Nachrichten senden.

import { Actor } from 'actor-ts';
type SampleMessage = { kind: 'sample'; value: number };
class Ingest extends Actor<SampleMessage> {
override preStart(): void {
// Höchstens 100 User-Nachrichten pro Sekunde, mit einem Burst von 20.
this.context.throttle({ qps: 100, burst: 20 });
}
override onReceive(message: SampleMessage): void {
// ... läuft mit der gedrosselten Rate
}
}

throttle kann von überall aufgerufen werden, wo der Actor läuft — preStart, einem Nachrichten-Handler, einem Behavior. Ein erneuter Aufruf ersetzt den Limiter; es gibt höchstens einen Throttle pro Actor.

Der Bucket fasst bis zu burst Tokens und füllt sich mit qps Tokens pro Sekunde nach. Das Ausreihen einer User-Nachricht kostet ein Token. Der Bucket startet voll, sodass ein untätiger Actor eine sofortige Spitze von bis zu burst Nachrichten aufnehmen kann, bevor die Begrenzung greift; danach fließen die Nachrichten mit qps.

FeldBedeutung
qpsNachfüllrate, Tokens pro Sekunde. Erforderlich, > 0. Infinity entfernt den Throttle (siehe Den Throttle aufheben).
burstBucket-Kapazität. Default: qps (eine Sekunde Nachfüllung).
onExcessWas zu tun ist, wenn der Bucket leer ist — 'pause' (Default) oder 'drop'.
nowZeitquelle; übergib eine deterministische Uhr in Tests. Default: Date.now.

Weil burst auf qps defaultet, glättet ein bloßes throttle({ qps: 100 }) den Verkehr auf ~100/Sekunde und toleriert dabei eine Sekunde Schwankung.

onExcess entscheidet über das Schicksal einer User-Nachricht, die ausgereiht wird, während der Bucket keine Tokens hat:

  • 'pause' (Default) — natürliche Backpressure. Die Nachricht bleibt in der Queue, und die Nachrichten-Pumpe des Actors pausiert, bis ein Token fällig ist, und läuft dann weiter. Jede Nachricht wird irgendwann verarbeitet; die Latenz wächst unter Last. Die Mailbox übernimmt das Puffern.
  • 'drop' — die Nachricht wird verworfen (mit einem Debug-Log). Nützlich für Telemetrie-artigen Verkehr, bei dem ein veraltetes Sample schlimmer ist als ein verlorenes.
import { Actor } from 'actor-ts';
type SampleMessage = { kind: 'sample'; value: number };
class Telemetry extends Actor<SampleMessage> {
override preStart(): void {
// Last abwerfen statt puffern — eine späte Metrik ist wertlos.
this.context.throttle({ qps: 50, burst: 10, onExcess: 'drop' });
}
override onReceive(message: SampleMessage): void {
// ... nur ~50 Samples pro Sekunde kommen hier an; der Rest wird verworfen
}
}

Zwei äquivalente Wege, einen aktiven Throttle zu entfernen und zur vollen Dispatch-Geschwindigkeit zurückzukehren:

this.context.cancelThrottle();
// exakt äquivalent:
this.context.throttle({ qps: Infinity });

{ qps: Infinity } ist der Wert für „keine Begrenzung”: eine unbegrenzte Rate hat keinen Bucket, also installiert die Runtime keinen. Das ist praktisch, wenn die Rate berechnet wird — eine einzige throttle({ qps: computeRate() })-Aufrufstelle kann den Limiter abschalten, indem sie Infinity liefert, ganz ohne Fallunterscheidung an der Aufrufstelle.

Der Throttle begrenzt ausschließlich User-Nachrichten. Diese umgehen ihn vollständig:

  • Systemnachrichten — create, terminate, Supervision, Timer-Auslösung. Sie laufen auf der System-Queue, vor den User-Nachrichten, sodass ein gedrosselter Actor trotzdem prompt stoppt und seine Timer planmäßig feuern.
  • Death-Watch-Benachrichtigungen — ein Terminated (oder sein watchWith-Ersatz) verbraucht kein Token und ist niemals die Nachricht, die ein onExcess: 'drop' verwirft. Ein Tod wird einmal angekündigt, daher lässt die Runtime ihn niemals von einem Throttle verwerfen.

Genau diese Trennung macht es sicher, einen Throttle aggressiv zu setzen: er verlangsamt die Arbeit des Actors, niemals seinen Lebenszyklus.

Wie jeder Options-Typ in actor-ts haben auch die Throttle-Optionen einen fluenten Builder, der mit dem einfachen Objekt austauschbar ist:

import { Actor, ThrottleOptions } from 'actor-ts';
type SampleMessage = { kind: 'sample'; value: number };
class Ingest extends Actor<SampleMessage> {
override preStart(): void {
const throttleOptions = ThrottleOptions.create()
.withQps(100)
.withBurst(20)
.withOnExcess('drop');
this.context.throttle(throttleOptions);
}
override onReceive(message: SampleMessage): void {
// ...
}
}

Ungültige Optionen werden vorab mit einem OptionsError abgelehnt, der das betroffene Feld benennt — ein fehlerhaftes qps oder burst scheitert also am throttle()-Aufruf und nicht erst später in der Runtime:

EingabeErgebnis
qps: 0, qps: -5, qps: NaNOptionsError — qps must be a positive finite number or Infinity
qps: InfinityAkzeptiert — hebt den Throttle auf
burst: 0, burst: -1OptionsError — burst must be a positive finite number
onExcess: 'explode'OptionsError — onExcess must be one of pause, drop

Aus einem Actor heraus aufgerufen, wandert dieser OptionsError wie jeder andere geworfene Fehler durch die Supervision.

Eine pause-gedrosselte Mailbox ist geparkt, nicht am Leeren — ein System-Shutdown wartet daher nicht auf sie. Ein qps: 10-Actor mit Backlog bräuchte Backlog ÷ 10 Sekunden zum Leeren, worauf kein Shutdown warten kann; also behandelt der Drain eine throttle-geparkte Queue als ruhig und schickt den Rest an die Dead Letters. Wenn dieser Backlog beim Shutdown wichtig ist, zuerst cancelThrottle(). Der Troubleshooting-Leitfaden führt das unter „das System leert sich nicht”.

  • Mailboxes — wo Pause-Backpressure puffert; beschränke sie, wenn ein Sender den Actor überholen kann.
  • Dispatchers — der Throttle sitzt vor dem Dispatcher, der sonst jede eingereihte Nachricht abarbeiten würde.
  • Death Watch — warum Termination-Benachrichtigungen vom Throttle ausgenommen sind.

Die ActorContext.throttle-API-Referenz deckt die vollständige Signatur und die Optionen ab.