Zum Inhalt springen
Deutsch

Dispatcher-Tuning

Der Dispatcher entscheidet, wann Actor-Nachrichten auf der JavaScript-Event-Loop laufen. Vier Formen werden ausgeliefert:

DispatcherSchedult viaPasst zu
HybridDispatcher (Default)queueMicrotask, jeder 64. Turn setImmediateHTTP-Server + gemischtes I/O; die meisten Apps.
MicrotaskDispatcherqueueMicrotaskNur zum Messen — hungert I/O unter Dauerlast aus.
ImmediateDispatchersetImmediate / setTimeout(0)Jeder Turn muss an I/O abgeben.
ThroughputDispatchersetImmediate mit N-dann-yieldBatch-Verarbeitung über viele Actors.

Der Default — HybridDispatcher — passt für die meisten Apps. Diese Seite behandelt, wann er nicht passt und wie du eine bessere Wahl triffst.

const system = ActorSystem.create('my-app');
// ↑ uses HybridDispatcher unless actor-ts.dispatcher.default says otherwise

Actor-Turns werden über die Microtask-Queue übergeben; ein Turn, der auf einen anderen folgt, läuft also, ohne auf die Event-Loop zu warten. Jeder 64. Turn geht stattdessen über setImmediate — damit laufen I/O-Callbacks (HTTP-Handler, Broker-Nachrichten, Timer-Feuer), bevor die Zählung von vorn beginnt. Ein Turn umfasst bis zu actor-ts.actor.throughput Nachrichten (per Default 16), die Loop kommt also mindestens alle ~1 024 Nachrichten dran.

Für HTTP-Server + Broker-Actor-Cluster (der häufige Fall) hält das I/O in einer Schranke, ohne pro Turn einen setImmediate-Sprung zu zahlen — den Sprung, den der ImmediateDispatcher, der bisherige Default, konstruktionsbedingt zahlt, zu rund 2,4 µs pro Turn, die ein Request/Response-Actor nicht amortisieren kann. actor-ts.dispatcher.default wählt systemweit einen anderen Dispatcher; ein nicht gesetzter oder unbekannter Wert bedeutet den Hybrid.

P99-HTTP-Response-Time ist 200ms; Actors verarbeiten Zehntausende
Nachrichten/sec. Die Actor-Arbeit ist nicht das Problem — sondern
dass HTTP-Requests nicht drankommen.

Ursache: Ein Actor (oder eine Gruppe Actors) verarbeitet Nachrichten so schnell, dass HTTP-Handler auf ihren Turn warten.

Fix: Beim Default-Dispatcher bleiben und das Batch-Budget des beschäftigten Actors senken:

import { ActorOptions } from 'actor-ts';
const heavyOptions = ActorOptions.create().withThroughput(4);
const heavyActor = system.spawnAnonymous(HeavyWorker, heavyOptions);

Jeder Turn des schweren Actors endet jetzt nach 4 statt nach 16 Nachrichten. Der Default-Dispatcher lässt die Event-Loop jeden 64. Turn laufen; die Strecke Arbeit des schweren Actors, hinter der HTTP warten kann, schrumpft also von ~1 024 Nachrichten auf 256. HTTP-Latenz sinkt; der Durchsatz des schweren Actors fällt nur so weit, wie der kleinere Batch ihn kostet.

Wartet HTTP immer noch zu lange, gib systemweit häufiger ab: mit einem kleineren Hybrid-Budget (Dispatchers.Hybrid(16) lässt die Loop jeden 16. Turn laufen) oder mit dem ImmediateDispatcher, der nach jedem Turn abgibt — zum Preis des setImmediate-Sprungs, den der Default vermeiden soll. Das Budget zählt Turns, ist also eine ganze Zahl ab 1, und bei 1 läuft die Loop nach jedem Turn. 0, eine negative oder gebrochene Zahl, NaN und Infinity werden beim Bau des Dispatchers mit einem OptionsError abgelehnt: Unter 1 liefe nie ein Turn, und ein Budget, das nie abläuft, gibt nie ab.

Symptom: niedriger Actor-Durchsatz, niedrige CPU-Nutzung

Abschnitt betitelt „Symptom: niedriger Actor-Durchsatz, niedrige CPU-Nutzung“
Das Actor-System macht 1000 msg/sec auf einer idle CPU. Profil
zeigt Zeit in setImmediate verbracht.

Ursache: Turns gehen öfter durch die Event-Loop, als die Arbeit braucht. Der ImmediateDispatcher schickt konstruktionsbedingt jeden Turn durch setImmediate, der Default einen Turn von 64. Für Tight-Loop-CPU-Arbeit ohne I/O sind diese Yields Verschwendung.

Fix: Läuft das System auf dem ImmediateDispatcher — konfiguriert oder pro Actor gesetzt —, geh zurück zum Default. Läuft es schon auf dem Default, erhöhe das Budget des Hybrids, damit er seltener abgibt:

import { ActorSystem, ActorSystemOptions, Dispatchers } from 'actor-ts';
const actorSystemOptions = ActorSystemOptions.create().withDispatcher(Dispatchers.Hybrid(1_000));
const system = ActorSystem.create('compute-pipeline', actorSystemOptions);

Die Event-Loop kommt jetzt alle 1 000 Actor-Turns dran statt alle 64 — bis zu ~16 000 Nachrichten beim Default-Batch. Caveat: Das ist die Verzögerung, die jeder Timer und jeder Socket-Read im Prozess sehen kann; erhöhe das Budget also nur, wo nichts einen prompten Zug braucht:

  • Das System bedient keinen HTTP-Traffic (Compute-Only-Worker).
  • Seine Actors machen kein await auf I/O (rein CPU).

Der MicrotaskDispatcher ist nicht der Fix, auch wenn er die Yields ganz entfernt: Ohne jedes Budget lässt ein beschäftigtes System Timer und Sockets nie wieder laufen — siehe Dispatcher. Aus demselben Grund wird Dispatchers.Hybrid(Infinity) abgelehnt, statt als Hybrid angenommen zu werden, der nie abgibt.

new ThroughputDispatcher(100); // queued actor turns per tick

Der Konstruktor ist positional — throughput zuerst, eine optionale Dispatcher-id als zweites:

  • throughput — Turns, die pro Tick abgearbeitet werden, über alle Actors hinweg, die sich diesen Dispatcher teilen. Keine Nachrichten, und nicht pro Actor: Jeder Turn gehört einem anderen Actor, weil ein Actor immer nur einen Turn gleichzeitig eingereiht haben kann. Höher = mehr Durchsatz, schlechtere I/O-Verschränkung. Übliche Werte: 10-1000. Default ist 16. Eine ganze Zahl ab 1: 0, eine negative oder gebrochene Zahl, NaN und Infinity werden beim Bau des Dispatchers mit einem OptionsError abgelehnt, weil unter 1 nie ein Turn abgearbeitet wird und ein Drain ohne Grenze nie abgibt. Das konfigurierte actor-ts.dispatcher.throughput nimmt dieselben Werte und wird nicht wie der Per-Actor-throughput auf 1 angehoben: Mit default = throughput in diesem Block lässt eine 0 dort ActorSystem.create scheitern.
  • Zwischen Batches yieldet er immer via setImmediate (mit Fallback auf setTimeout(0), wo setImmediate nicht verfügbar ist), damit I/O und Timer verschränken. Das ist nicht konfigurierbar.

Für einen Batch-Prozessor mit vielen Actors, die Broker-Nachrichten verarbeiten: throughput: 200 ist ein vernünftiger Startpunkt.

Wie viele Nachrichten ein Actor pro Turn vor dem Yield abarbeitet, ist eine von allem am Dispatcher getrennte Einstellung:

import { ActorOptions } from 'actor-ts';
const bulkOptions = ActorOptions.create().withThroughput(64);
const bulk = system.spawnAnonymous(BulkProcessor, bulkOptions);

Systemweit heißt dieselbe Stellschraube actor-ts.actor.throughput:

actor-ts {
actor {
throughput = 64
}
}

Für einen Actor oder eine Familie davon, deren Spawn-Stelle du nicht ändern kannst, setzt ein actor-ts.deployment-Eintrag sie pro Pfad:

actor-ts.deployment {
"/user/bulk" { throughput = 64 }
"/user/pool/routee-*" { throughput = 32 }
}

Die Präzedenz ist die übliche, eine Ebene länger — withThroughput() schlägt den passenden Deployment-Eintrag, der schlägt actor-ts.actor.throughput, und der schlägt den eingebauten Default von 16.

Das ist die Einstellung, die den Scheduling-Overhead für einen beschäftigten Actor beseitigt. Jede Nachricht kostete früher einen vollen setImmediate-Roundtrip (~2,4 µs), unabhängig von jeder Dispatcher-Einstellung; das Batching amortisiert ihn über den gesamten Batch, was bei einer tell-getriebenen Last grob 2-3× wert ist.

Der Trade-off ist Fairness, und zwar direkt: Ein Batch läuft ohne Yield bis zu seinem Budget, also ist Budget × Handler-Zeit die Verzögerung, die jeder Timer, jeder Socket-Read und jeder andere Actor sehen kann. Senke es Richtung 1 für einen Actor mit langsamem Handler, der sich ein System mit latenzsensitiver Arbeit teilt; erhöhe es für einen Actor mit kurzem Handler, der ein Durchsatz-Flaschenhals ist. Ein Batch endet immer vorzeitig bei leerer Mailbox, bei Stop oder Suspend und bei einem leerlaufenden Throttle-Bucket — das Budget ist also eine Obergrenze, nie eine Zusage.

Wissenswert, bevor du irgendetwas tunst, weil es den Maßstab setzt, an dem alles andere gemessen wird.

Auf dem ImmediateDispatcher dominiert der Scheduling-Roundtrip alles andere auf dem Nachrichtenpfad — rund 2,4 µs gegenüber einer rohen Mailbox-Operation von einigen zehn Nanosekunden. Deshalb ist auf diesem Dispatcher Per-Actor-Throughput die Einstellung mit dem größten Effekt auf eine tell-getriebene Last, und deshalb bewegt eine schnellere Queue oder ein schlankerer Handler die Zahl weit weniger, als es sich anfühlt. Der voreingestellte HybridDispatcher existiert, um diesen Sprung den meisten Turns abzunehmen: Er übergibt sie als Microtasks und zahlt das setImmediate nur einmal alle 64.

Darunter liegt der Per-Message-Overhead des Frameworks selbst, mit Metriken und Tracing aus. Das waren früher vier Extension-Registry-Lookups, vier Metrik-Label-Objekte, gebaut für eine Registry, die sie verwirft, ein Closure, ein Wegwerf-Array und zwei Clock-Reads — pro Nachricht, in jedem System, egal ob irgendetwas beobachtet wurde. #411 hat all das entfernt; übrig bleiben eine Handvoll Feldzugriffe und Null-Checks. Beide Extensions lassen sich weiterhin zur Laufzeit einschalten, und eine Nachricht ist entweder ganz oder gar nicht instrumentiert — die Handles werden einmal pro Nachricht aufgelöst statt an jedem Instrumentierungspunkt.

Wenn du Allokationsdruck statt Latenz verfolgst, isoliert benchmarks/memory/receive-path.ts genau das, und sein Header erklärt, warum sich der Effekt als Durchsatz und nicht als Heap zeigt.

import { ActorOptions, Dispatchers } from 'actor-ts';
const computeOptions = ActorOptions.create().withDispatcher(Dispatchers.Hybrid(1_000));
const heavy = system.spawnAnonymous(BulkProcessor, computeOptions);
const httpHandler = system.spawn(
HttpHandler,
// → uses the system's default dispatcher (HybridDispatcher unless configured)
);

Frei mischen: Ein reiner Compute-Actor kann auf einem Hybrid mit erhöhtem Budget laufen — er gibt die Event Loop alle 1 000 Turns frei statt alle 64 —, während HTTP-Handler auf dem Default bleiben. Nicht auf einem MicrotaskDispatcher allerdings: Microtasks laufen leer, bevor irgendein Timer- oder Socket-Callback dran ist, egal welcher Dispatcher sie eingereiht hat — eine unbegrenzte Kette auf einem Actor hungert die Handler daneben also genauso aus wie eine systemweite.

Wofür ein Per-Actor-Dispatcher nicht taugt, ist Batching. Ein ThroughputDispatcher für einen einzigen Actor arbeitet eine Queue ab, die nie mehr als dessen einen ausstehenden Turn hält — sein Budget ist also unerreichbar. Nutze stattdessen withThroughput(). Ein ThroughputDispatcher lohnt sich, wenn eine Gruppe von Actors ihn sich teilt.

const actorSystemOptions = ActorSystemOptions.create().withDispatcher(new ThroughputDispatcher(100));
const system = ActorSystem.create('my-app', actorSystemOptions);

Override den Default für jeden Actor, der nichts anderes spezifiziert. Nützlich für Batch-only-Systeme ohne HTTP-Traffic.

Zwei Stock-Metriken teilen die Latenz einer Nachricht genau dort, wo sie angenommen wird:

actor_mailbox_wait_seconds — in der Queue, wartet auf ihren Zug
actor_message_handler_seconds — innerhalb von onReceive

Lies sie zusammen; das Paar sagt dir, ob Dispatcher-Tuning überhaupt helfen kann:

  • Wait-p99 hoch, Handler-p99 niedrig — der Actor ist in Ordnung, die Nachrichten liegen in der Queue. Dispatcher-Tuning hilft: erhöhe das Per-Actor-Throughput-Budget, damit jeder Zug mehr Rückstau abbaut, oder nimm den Actor von einem Dispatcher herunter, den er sich mit langsamer Arbeit teilt.
  • Handler-p99 hoch — der Handler selbst ist die Kosten. Keine Dispatcher-Einstellung macht ihn schneller; das ist ein Code- oder Downstream-Problem, und ein höheres Budget macht die Latenz für alles, was sich die Runtime teilt, schlechter.

Die Queueing-Verzögerung musste früher aus dem Abstand zwischen p50 und p99 des Handler-Histogramms erschlossen werden, was sie mit der Varianz der Arbeit selbst vermischte. Sie wird jetzt direkt gemessen.

Das Gauge actor_mailbox_size unter Last zeigt, ob Actors mitkommen. Dauerhaft wachsende Tiefe = entweder ein langsamer Handler oder ein fehlkonfigurierter Dispatcher. Es ist das spätere der beiden Signale — eine Serie entsteht erst ab 10 000 wartenden Nachrichten, während die Wartezeit steigt, sobald ein Actor zurückfällt. actor_mailbox_depth füllt diese Lücke: ein Histogramm ohne Labels, einmal pro Zustellung beobachtet, sodass ein Ausschlag, der nie 10 000 erreicht, seinen Ausläufer dennoch zeigt.

Beide Metriken oben betreffen die Mailbox eines Actors. Eine Nachricht kann auch eine Ebene höher warten — im Dispatcher, nachdem die Zelle einen Zug angefordert hat und bevor dieser Zug beginnt:

actor_dispatcher_queue_delay_seconds{dispatcher="..."}

Im Ruhezustand ist das eine einzige Scheduling-Übergabe, Mikrosekunden. Wenn es steigt, ist weder der Actor das Problem noch seine Mailbox: Züge stauen sich hinter anderen Zügen, und genau dafür ist Dispatcher-Tuning da.

histogram_quantile(0.99,
rate(actor_dispatcher_queue_delay_seconds_bucket[5m]))
# Per dispatcher. A high p99 on one and not the others tells you which
# pool to split, and which actors to move off it.

Neben dem Mailbox-Paar gelesen vervollständigt es die Diagnose:

  • Delay-p99 hoch — die Züge konkurrieren. Entweder gibt etwas auf diesem Dispatcher nicht ab (ein ThroughputDispatcher mit zu hohem Budget oder ein blockierender Handler), oder zu viele Actors teilen ihn sich. Teile den Dispatcher auf, oder senke sein Throughput, damit er häufiger abgibt.
  • Delay-p99 niedrig, Mailbox-Wait-p99 hoch — die Züge starten prompt, und die eigene Queue eines Actors ist der Rückstau. Erhöhe withThroughput dieses Actors, damit jeder Zug mehr abbaut, statt am Dispatcher zu drehen.

Es gibt bewusst kein dispatcher_saturation_ratio — ein 0–1-Anteil „beschäftigt” lässt sich auf allen drei unterstützten Laufzeitumgebungen nicht ehrlich berechnen, und Stock-Metriken hält die Messungen hinter dieser Entscheidung fest. Der MicrotaskDispatcher ist der eine Fall, in dem eine niedrige Verzögerung kein Beleg für Luft ist — aus dem dort genannten Grund.

HTTP server + actors → HybridDispatcher (default)
Compute-heavy + no HTTP → Dispatchers.Hybrid(1_000)
Batch processing, many actors → ThroughputDispatcher (throughput 100-500)
One actor is the bottleneck → default dispatcher + withThroughput(64...256)
Mixed: heavy actor + HTTP → default dispatcher + withThroughput(2...8) on the heavy actor
Every turn must yield to I/O → ImmediateDispatcher