Dispatcher-Tuning
Der Dispatcher entscheidet, wann Actor-Nachrichten auf der JavaScript-Event-Loop laufen. Vier Formen werden ausgeliefert:
| Dispatcher | Schedult via | Passt zu |
|---|---|---|
HybridDispatcher (Default) | queueMicrotask, jeder 64. Turn setImmediate | HTTP-Server + gemischtes I/O; die meisten Apps. |
MicrotaskDispatcher | queueMicrotask | Nur zum Messen — hungert I/O unter Dauerlast aus. |
ImmediateDispatcher | setImmediate / setTimeout(0) | Jeder Turn muss an I/O abgeben. |
ThroughputDispatcher | setImmediate mit N-dann-yield | Batch-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.
Default-Verhalten
Abschnitt betitelt „Default-Verhalten“const system = ActorSystem.create('my-app');// ↑ uses HybridDispatcher unless actor-ts.dispatcher.default says otherwiseActor-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.
Symptom: hohe HTTP-Latenz unter Actor-Last
Abschnitt betitelt „Symptom: hohe HTTP-Latenz unter Actor-Last“P99-HTTP-Response-Time ist 200ms; Actors verarbeiten ZehntausendeNachrichten/sec. Die Actor-Arbeit ist nicht das Problem — sonderndass 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. Profilzeigt 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
awaitauf 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.
ThroughputDispatcher-Optionen
Abschnitt betitelt „ThroughputDispatcher-Optionen“new ThroughputDispatcher(100); // queued actor turns per tickDer 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 ab1:0, eine negative oder gebrochene Zahl,NaNundInfinitywerden beim Bau des Dispatchers mit einemOptionsErrorabgelehnt, weil unter1nie ein Turn abgearbeitet wird und ein Drain ohne Grenze nie abgibt. Das konfigurierteactor-ts.dispatcher.throughputnimmt dieselben Werte und wird nicht wie der Per-Actor-throughputauf1angehoben: Mitdefault = throughputin diesem Block lässt eine0dortActorSystem.createscheitern.- Zwischen Batches yieldet er immer via
setImmediate(mit Fallback aufsetTimeout(0), wosetImmediatenicht 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.
Per-Actor-Throughput
Abschnitt betitelt „Per-Actor-Throughput“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.
Was eine Nachricht kostet, wenn niemand zusieht
Abschnitt betitelt „Was eine Nachricht kostet, wenn niemand zusieht“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.
Per-Actor-Dispatcher
Abschnitt betitelt „Per-Actor-Dispatcher“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.
Systemweiter Dispatcher
Abschnitt betitelt „Systemweiter Dispatcher“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 Zugactor_message_handler_seconds — innerhalb von onReceiveLies 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.
Ist der Dispatcher selbst die Queue?
Abschnitt betitelt „Ist der Dispatcher selbst die Queue?“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
ThroughputDispatchermit 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
withThroughputdieses 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.
Heuristiken
Abschnitt betitelt „Heuristiken“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 actorEvery turn must yield to I/O → ImmediateDispatcherWohin als nächstes
Abschnitt betitelt „Wohin als nächstes“- Dispatcher — die konzeptuelle Referenz.
- Blockierende und CPU-lastige Arbeit — das Tuning, das keine Dispatcher-Einstellung leisten kann: Ein Handler, der rechnet, hält den Thread, was auch immer das Throughput-Budget sagt.
- Mailbox-Sizing — der komplementäre Knopf.
- Stock-Metriken — die Per-Actor-Performance-Metriken.
