Routing — Überblick
Ein Router ist ein Actor, dessen einzige Aufgabe es ist, jede
eingehende Nachricht an einen (oder mehrere) seiner Routees
weiterzuleiten. Du spawnst den Router einmal; hinter ihm sitzen N
Worker-Actors; Sender tellen dem Router und wissen nie, wie viele
Routees existieren.
Zwei Formen liefert das Framework aus:
| Form | Wo es lebt | Routees sind… |
|---|---|---|
Router (lokal) | Ein Node, ein Actor-System. | Kinder des Routers, zur Spawn-Zeit erstellt aus demselben Actor. |
ClusterRouter | Über Cluster-Nodes hinweg. | Up-Members des Clusters, aus Mitgliedschaft abgeleitet + ein Routee-Pfad. |
Beide exponieren dieselbe externe Schnittstelle: eine einzelne
ActorRef<TMessage>, die Aufrufer tellen. Der Unterschied ist was
auf der anderen Seite ist.
Wann zu einem Router greifen
Abschnitt betitelt „Wann zu einem Router greifen“Vier Patterns:
- I/O-gebundene Handler am Laufen halten. Ein einzelner Actor
verarbeitet eine Nachricht nach der anderen; ein Handler, der auf
eine Datenbank oder einen HTTP-Aufruf
awaitet, parkt also jede spätere Nachricht hinter diesem Warten. Ein 4-Routee-Round-Robin- Router lässt vier davon gleichzeitig in der Luft sein, ohne das Message-Ordering innerhalb eines Routees zu brechen. Das ist Nebenläufigkeit, keine CPU-Parallelität: Die Routees sind Kinder des Routers, auf seinem Thread, und die Runtime ist single-threaded — vier CPU-gebundene Routees sind also keinen Deut schneller fertig als einer (benchmarks/single-node/router-pool.tsmisst genau das). CPU-Arbeit geht ancontext.offloadoder an einen Pool über Threads. - Last über Nodes verteilen. Ein Cluster-Router mit
role-gefilterten Routees gibt dir Fan-Out über jeden Node, der die
'compute'-Rolle trägt. Füge einen Node hinzu, der Router nimmt ihn auf; entferne einen Node, der Router stoppt das Senden an ihn. - Arbeit deterministisch an einen Routee pinnen. Consistent-Hashing (nur Cluster) legt jede Nachricht mit demselben Key auf denselben Routee — nützlich, wenn jeder Routee Per-Key-Zustand hält (einen Cache, eine Session, einen Zähler).
- N Routees um dieselbe Antwort rennen lassen. Scatter/Gather stellt jedem Routee dieselbe Frage und liefert die Antwort dessen, der zuerst antwortet — das N-Fache an Arbeit gegen das Minimum aus N Latenzen. Das ist ein anderes Ziel als die ersten drei: Tail- Latenz, nicht Durchsatz. Siehe Scatter/Gather.
Ein minimales Beispiel
Abschnitt betitelt „Ein minimales Beispiel“import { ActorSystem, Router, Actor } from 'actor-ts';
class Worker extends Actor<{ payload: string }> { override onReceive(message: { payload: string }): void { this.log.info(`worked on ${message.payload}`); }}
const system = ActorSystem.create('demo');
const pool = system.spawn( Router.roundRobin(4, Worker), 'workers',);
pool.tell({ payload: 'a' }); // → worker-1pool.tell({ payload: 'b' }); // → worker-2pool.tell({ payload: 'c' }); // → worker-3pool.tell({ payload: 'd' }); // → worker-4pool.tell({ payload: 'e' }); // → worker-1 (Round-Robin wraps)Die pool-Ref sieht für Aufrufer wie ein einzelner Actor aus; unter
der Haube zykelt der Routing-Actor durch vier Worker-Kinder.
Die fünf Strategien
Abschnitt betitelt „Die fünf Strategien“| Strategie | Was sie tut | Am besten für |
|---|---|---|
round-robin | Ein Routee pro Nachricht, zyklisch. Gleichmäßige Verteilung nach Nachrichten-Count. | Homogene Workloads. |
random | Ein Routee pro Nachricht, gleichverteilt zufällig. | Wie Round-Robin, aber zustandslos. |
broadcast | Jeder Routee bekommt jede Nachricht. | Notifications, Cache-Invalidierungen. |
smallest-mailbox | Ein Routee pro Nachricht, der mit der kürzesten Queue. | Ungleiche Kosten pro Nachricht. |
consistent-hashing (nur Cluster) | Ein Routee pro Nachricht, Key-gepinnt. | Per-Key-Zustand (Sharding-Light). |
smallest-mailbox ist die Strategie, die nach Rückstau statt nach
Nachrichten-Count balanciert. Round-Robin vergibt Züge blind — ein
Routee, der eine teure Nachricht gezogen hat, bekommt seinen nächsten
1-aus-N trotzdem pünktlich und fällt zurück; Smallest-Mailbox liest
die Queue-Tiefe jedes Routees und wählt den flachsten, ein
beschäftigter Routee wird also so lange nicht mehr gewählt, bis er
aufgeholt hat. Bezahlt wird das mit einer Tiefenabfrage pro Routee
pro Nachricht — deshalb bleibt Round-Robin der Default.
Beide Router haben sie, aber sie erfahren die Tiefe unterschiedlich. Der lokale liest die Mailboxen seiner Routees direkt — sie sind seine eigenen Kinder, im selben Prozess. Der Cluster-Router kann das nicht: eine entfernte Mailbox liegt auf einem anderen Node, und pro Nachricht zu fragen würde den Router hinter einen Netzwerk-Roundtrip parken. Er routet stattdessen auf einer gecachten Tiefe, aufgefrischt auf einem Hintergrund-Tick — etwas Aktualität gegen eine Routing-Entscheidung eingetauscht, die synchron bleibt. Siehe Cluster-Router dazu, was dieser Nachlauf kosten kann und was nicht.
Siehe Strategien für den Deep Dive plus
den Broadcast-Nachrichten-Wrapper, der die Strategie pro Nachricht
überschreibt.
Alle fünf sind One-Shot: Der Router wählt Routees, leitet weiter,
fertig — die Antwort, falls es eine gibt, ist Sache des Routees und des
ursprünglichen Senders. Router.scatterGatherFirstCompleted ist der
eine Router, der nicht in diese Form passt: Er fragt jeden Routee und
antwortet dem Aufrufer selbst mit der ersten eintreffenden Antwort. Er
ist deshalb keine Strategie, die du Router.custom reichen kannst,
sondern eine eigene Factory — siehe
Scatter/Gather.
Pool vs Group
Abschnitt betitelt „Pool vs Group“Der lokale Router ist immer ein Pool — er erstellt seine
Routees selbst. Der Cluster-ClusterRouter ist eher eine Group
— die Routees existieren bereits (ein Actor pro Up-Member an einem
bekannten Pfad), und der Router findet sie nur.
Für die meisten Fälle ist Pool das, was du willst. Das Group-Modell taucht auf, wenn du willst, dass bestehende Actors (z.B. Shard-Regionen, Fixed-Name-Workers, die beim Startup gespawnt wurden) gerouteten Traffic empfangen.
Siehe Pool vs Group, wann jede Form die richtige Passung ist.
Router und Supervision
Abschnitt betitelt „Router und Supervision“Der Router ist ein regulärer Actor — er hat seine eigene
Supervisor-Strategie und watcht jeden Routee. Wenn ein Routee
crashed:
- Ohne Eingriff wendet der Parent des Routees (der Router) seine
Supervisor-Strategie an. Standardmäßig ist das die
defaultStrategydes Frameworks — Restart bis zu 10/Minute. - Der neu gestartete Routee tritt dem Pool an demselben Pfad wieder bei. Der Router muss nichts Besonderes tun.
- Alles, was während des kurzen Restart-Fensters an den Routee geroutet wurde, bleibt in seiner Mailbox — die Mailbox wird für den Restart suspendiert und danach wieder aufgenommen (dieselbe Instanz, nicht gedrained), sodass diese Nachrichten verarbeitet werden, sobald der Routee wieder läuft.
Für Per-Routee-Supervisor-Strategien konfiguriere sie auf den Routee-Options:
import { ActorOptions, stoppingStrategy } from 'actor-ts';
const routeeOptions = ActorOptions.create().withSupervisorStrategy(stoppingStrategy);
system.spawn(Router.roundRobin(4, Worker, routeeOptions), 'workers');Jetzt wird jeder Worker, der throwt, gestoppt statt neu
gestartet — und der Router, der jeden Routee watcht, entfernt die tote
Ref auf ihr Terminated aus dem Pool. Der Pool ist um einen Routee
kleiner, und in die Lücke wird nichts geroutet; was der Routee bereits
angenommen hatte, landet durch seinen eigenen Stop in Dead Letters, wie
bei jedem stoppenden Actor. Ein Pool, der heilen statt schrumpfen soll,
wickelt jeden Routee in einen
BackoffSupervisor —
Router.roundRobin(4, BackoffSupervisor.factory({ child: Worker })) —
sodass der Slot nach einem Backoff wieder gefüllt wird, statt zu
verschwinden.
Router sind nicht (der einzige) Weg zur Parallelisierung
Abschnitt betitelt „Router sind nicht (der einzige) Weg zur Parallelisierung“Ein Router gibt dir N unabhängige Actors, die jeweils eine Nachricht
nach der anderen verarbeiten — auf einem Thread. Welcher der fünf
Wege, Arbeit zu verteilen, passt, hängt davon ab, was die Arbeitseinheit
ist, wie viele Threads sie nutzen soll und ob der Aufrufer eine Adresse
oder einen Funktionsaufruf will. Jede Zahl unten steht bereits so im
Baum, mit benannter Quelle; nichts ist hier neu gemessen.
| Mechanismus | Arbeitseinheit | Threads | Eine lokale Adresse? | Pool-Größe | Bei Routee-Stop / -Crash | Kosten pro Nachricht | Break-even | Wann |
|---|---|---|---|---|---|---|---|---|
Lokaler Router-Pool | Actor-Nachricht | 1 — der des Routers | ja | fix zur Spawn-Zeit | Crash → an Ort und Stelle neu gestartet durch die Default-Strategie; Stop → entfernt, der Pool ist um einen kleiner | lokales tell ~320 ns (benchmarks/worker/mesh-message-cost.ts) | jedes await im Handler — es kauft Nebenläufigkeit, nie CPU | Handler, die auf I/O warten |
ClusterRouter über das Worker-Mesh — das Rezept unten | Actor-Nachricht | N Worker | ja — der Router | ein Routee pro Worker; folgt der Mitgliedschaft | Crash → neu gestartet durch seinen eigenen Parent auf dem Worker; Stop → der Router sendet weiter an diesen Node, bis sich die Mitgliedschaft ändert | Cross-Thread-tell ~21 µs, ask ~180 µs (derselbe Benchmark) | ~100 µs Arbeit pro Nachricht (die gemessene Tabelle) | N identische Rechen-Actors hinter einer Ref |
OffloadPool / context.offload | reine Funktion | ein bedarfsgetriebener Pool | nein — ein Aufruf, ein Promise zurück | wächst mit der Last, schrumpft im Leerlauf | ein fehlgeschlagener Lauf rejected sein Promise; ein toter Worker wird innerhalb eines Restart-Budgets ersetzt | ~3 µs pro gepipelinetem Task (benchmarks/worker/task-offload-breakeven.ts) | ~10 µs pro Aufruf (wann es sich lohnt) | hashen, komprimieren, transformieren — kein Actor auf der anderen Seite |
actor-ts.parallelism.workers mit mehreren Top-Level-Actors | Actor samt Teilbaum | N Worker | eine Ref pro Actor, Pfad unverändert | ein Worker pro Spawn, gewählt durch placement | supervised vom Guardian seines Workers; die Ref tellt, askt und watcht über den Thread | Cross-Thread-tell ~21 µs, ask ~180 µs | ~100 µs Arbeit pro Nachricht | mehrere verschiedene Rechen-Actors, jeder mit eigener Adresse |
| Sharded Entity | Actor pro Key | jeder Node oder Worker mit der Rolle | per Key, durch die Shard-Region | genau ein lebender Actor pro Key | neu gestartet durch seinen Shard; beim Rebalancing verschoben | der Hop des Transports: ~21 µs im Mesh, ~22 µs tell / ~245 µs ask über TCP (FAQ) | dieselben ~100 µs, plus der eigene Zustand der Entity | genau ein Actor pro Key, mit Failover |
DistributedPubSub steht nicht in der Tabelle, weil es eine andere Frage beantwortet: Fan-Out an eine dynamische Subscriber-Menge — Actors kommen und gehen, und jeder von ihnen kann publizierte Events empfangen —, wo die Routee-Menge eines Routers fest ist oder der Mitgliedschaft folgt.
Eine Adresse, ein Actor pro Thread
Abschnitt betitelt „Eine Adresse, ein Actor pro Thread“Die zweite Zeile ist die Form, die die anderen vier nicht sind: N
identische Actors über N Threads, und Aufrufer halten eine lokale
Ref. Nichts liefert das als einen einzelnen Aufruf aus. Es setzt sich
aus zwei Dingen zusammen, die es gibt: Das Worker-Mesh führt das
setup(context) des Actor-Moduls auf jedem Worker aus, sobald dessen
Node oben ist, und ein ClusterRouter ist ein Group-Router über das,
was auf jedem Member mit einer Rolle unter einem Pfad lebt.
actor-ts.parallelism { workers = "auto" # one worker per core, minus the main thread offload = ["/user/offloaded-*"] # the router below must not match — see the traps}actor-ts.worker-mesh.worker-roles = ["compute"]// actors.ts — next to the entry module; every worker imports itimport { Actor, type ActorRef } from 'actor-ts';import { ClusterMailboxDepthAgent } from 'actor-ts/cluster';import type { WorkerMeshSetupContext } from 'actor-ts/worker';
export type EncodeCommand = { readonly kind: 'encode'; readonly frame: Uint8Array; readonly replyTo: ActorRef<EncodedFrame>;};
export type EncodedFrame = { readonly bytes: number; /** The address of the node that did the work: which thread, in a mesh. */ readonly encodedOn: string;};
export class Encoder extends Actor<EncodeCommand> { override onReceive(command: EncodeCommand): void { // The CPU work goes here; the reply names the thread that did it. const encodedOn = this.system.cluster.map((cluster) => cluster.selfAddress.toString()).getOrElse('main'); command.replyTo.tell({ bytes: command.frame.byteLength, encodedOn }); }}
/** Runs once on every worker, after its node has joined the mesh. */export function setup(context: WorkerMeshSetupContext): void { context.system.spawn(Encoder, 'encoder'); ClusterMailboxDepthAgent.serve(context.cluster); // only 'smallest-mailbox' reads it}// main.ts — the entry module; the router stays on this threadimport { ActorSystem, ParallelismExtensionId } from 'actor-ts';import { ClusterRouter, ClusterRouterOptions } from 'actor-ts/cluster';import type { EncodeCommand, EncodedFrame } from './actors.js';
const system = ActorSystem.create('media');const parallelism = system.extension(ParallelismExtensionId);await parallelism.whenReady();
const clusterRouterOptions = ClusterRouterOptions.create<EncodeCommand>() .withCluster(parallelism.workerMesh!.cluster) .withRouterType('round-robin') .withRouteePath('/user/encoder') .withRole('compute');const encoders = system.spawn(ClusterRouter.factory(clusterRouterOptions), 'encoders');
const encoded = await encoders.ask<EncodedFrame>({ kind: 'encode', frame: new Uint8Array(4096) });console.log(encoded.encodedOn); // e.g. media@worker:2 — each ask names the next worker in address order, wrapping aroundwhenReady() ist das eine Warten: Das Mesh ist oben und jedes setup
ist gelaufen, der erste Rebuild des Routers sieht also jeden Worker.
Routees sind lexikalisch sortiert, nach der String-Form ihrer Adresse —
media@worker:10 vor media@worker:2 —, die Round-Robin-Reihenfolge
ist also über Rebuilds hinweg stabil; für drei Worker lautet die
Rotation :2, :3, :4, wieder :2. Die Plain-Object-Form geht
ebenso —
ClusterRouter.factory({ cluster, routerType: 'round-robin', routeePath: '/user/encoder', role: 'compute' }).
Drei Fallen — die ersten beiden eine Nachricht, die nirgendwohin geht, die dritte ein Router, der weniger ausgleicht, als es scheint:
- Der Router darf
offloadnicht matchen.ClusterRouter.factory(…)gibt eine Factory zurück, und eine Factory ist eine Closure, die keinen Thread überqueren kann — einspawn, dessen Pfadoffloadmatcht, throwt auf dem Stack des Aufrufers und nennt die Lösung. Halte das Pattern vom Pfad des Routers fern, wie/user/offloaded-*oben. - Ohne
roleist der Main-Thread ebenfalls ein Routee. Der eigene Node des Routers ist ein Member wie jeder andere, und der Main-Thread hat keinen/user/encoder— jede (N+1)-te Nachricht wird also dort verworfen, wo sie ankommt, mit einer Warnung pro Nachricht (no envelope handler registered, dropping message to …; auf einem Node, derClusterShardinggestartet hat, übernimmt stattdessen die Sharding-Extension den nicht aufgelösten Envelope und warnt[sharding] no region/coordinator registered for …), und einaskdafür läuft in den Timeout. Die Rolle ist, was den Main-Thread aus dem Pool hält. smallest-mailboxbraucht den Agenten auf jedem Worker. Der Router liest Mailbox-Tiefen von einem kleinen Framework-Agenten auf jedem Routee-Node, und einsmallest-mailbox-Router startet diesen Agenten nur auf seinem eigenen Node. Die ZeileClusterMailboxDepthAgent.serve(context.cluster)insetupist, was die Worker berichten lässt; ohne sie bricht nichts, aber kein Routee berichtet je, und ohne irgendeine Messung ist die Strategie schlichtes Round-Robin. Dieser Rückfall gilt ganz oder gar nicht, nicht pro Worker: Ein Worker, der stumm bleibt, während andere berichten — seine Messung fehlt oder ist älter alsmailboxDepthStaleAfterMs—, wird übersprungen, statt an die Reihe zu kommen, weil der schweigende Node gerade der sein könnte, der kämpft. Cluster-Router nennt die Regel.
Was das Rezept nicht liefert: einen Pool, der mit der Last wächst und
schrumpft — das ist #212, und heute skaliert nur der OffloadPool so.
Was es liefert, ist ein Scrape für alles: Das Mesh leitet die
Metrik-Registry jedes Workers an den Main-Thread weiter (#1570); sobald
der Main-Thread also /metrics exportiert, steht die Arbeit der Encoder
dort — die Werte jedes Workers als thread="worker-<slot>"-Serien neben
den eigenen thread="main" des Routers, sum without (thread) für die
Summe des Pools — siehe den
Geltungsbereich eines Scrapes.
Wie es weitergeht
Abschnitt betitelt „Wie es weitergeht“- Router — die
Router.roundRobin(...),.random(...),.broadcast(...),.smallestMailbox(...),.custom(...)-Factories. - Strategien — was jede Strategie tut, plus eigene schreiben.
- Scatter/Gather — jeden Routee gleichzeitig fragen und mit der ersten Antwort antworten.
- Pool vs Group — wann einen Router verwenden, der seine Routees spawnt, vs einen, der sie findet.
- Cluster-Router — das mitgliedschafts-getriebene Cluster-Äquivalent.
