Zum Inhalt springen
Deutsch

Parallelität

JavaScript führt pro Actor-System einen Thread aus. Ein Worker-Thread ist ein weiterer Thread, und das Framework kann auf jedem ein Actor-System hosten — genau das tut das Worker-Mesh. Diese Seite handelt von der Schicht darüber: Actors auf diese Threads zu verteilen, ohne die Anwendung zu ändern. Eine Konfigurationszahl startet die Threads, und system.spawn setzt Actors darauf.

actor-ts.parallelism {
workers = auto # 0 = off (the default) | N | "auto"
}
// unchanged, character for character
const system = ActorSystem.create('my-app');
const ref = system.spawn(ImageResizer, 'resizer');
ref.tell({ kind: 'resize', bytes });

Mit workers = 0 ist das System das Single-Thread-System, das es immer war: kein Thread, kein Cluster, kein Modul-Import, und spawn zahlt einen Null-Check. Mit jedem anderen Wert startet ActorSystem.create im Hintergrund ein Mesh — der Main-Thread tritt einem eigenen Cluster bei, spawnt die Worker, und jeder Worker tritt bei — und spawn wird zu einer Platzierungsentscheidung. Ein Actor, dessen Pfad auf offload passt, wird auf einem Worker erzeugt; jeder andere dort, wo er immer erzeugt wurde. In beiden Fällen ist der Aufruf synchron und liefert eine ActorRef, deren path der Pfad ist, den der Actor zu Hause gehabt hätte.

spawn(ImageResizer, 'resizer') übergibt ein Klassenobjekt, und eine Klasse kann keinen Thread überqueren: postMessage klont Daten, nie Code, und keine Runtime kann von einem Klassenobjekt auf das Modul zurückschließen, das es definiert hat. Also muss der Worker die Klassen selbst import()ieren, und beide Seiten einigen sich auf einen Namen für jede — ihren Export-Namen, der einen Minifier überlebt und zwei Klassen mit demselben .name auseinanderhält.

Das ist das Einzige, was die Anwendung liefert: ein Modul, das die auszulagernden Actor-Klassen exportiert. Nur Exports — keine Registrierung, keine Dekoratoren:

src/actors.ts
export { ImageResizer } from './actors/ImageResizer.js';
export { ReportBuilder } from './actors/ReportBuilder.js';

Per Konvention ist es actors.js (oder .ts) neben dem Entry-Modul — der Datei, die die Runtime ausführen sollte — und dann muss nichts konfiguriert werden. Ein anderes Modul, oder mehrere, wird im Code benannt:

const parallelism = ParallelismOptions.create()
.withModule(new URL('./workers/actors.js', import.meta.url));
const systemOptions = ActorSystemOptions.create().withParallelism(parallelism);
const system = ActorSystem.create('my-app', systemOptions);

module ist bewusst kein HOCON-Schlüssel, aus demselben Grund, aus dem worker-cluster.bootstrap keinen hat: Eine Konfigurationsdatei darf nicht entscheiden, welchen Code ein Worker ausführt. Ist workers größer als null und nirgends ein Modul zu finden, wirft ActorSystem.create einen OptionsError, der die gesuchten Pfade und die Option nennt, die eines benennt.

Ein Modul darf außerdem ein setup(context) exportieren; der Worker führt es aus, sobald sein Knoten oben ist, mit System, Cluster und Registry in der Hand. Dort wird ein Actor gespawnt, den ein Worker von Anfang an hosten soll, und dort gehört Actor-Konfiguration hin, die keinen Thread überqueren kann (siehe unten).

actor-ts.parallelism {
workers = 0 # 0 = off | N | "auto" = available parallelism minus the main thread
offload = ["/user/*"] # path patterns; * = one segment, ** = any depth; /system is refused
placement = "consistent-hash" # consistent-hash (by actor name) | round-robin
leader = "main" # main | worker — who hosts the shard coordinator and role-less singletons
spawn-timeout = 10s # a worker's acknowledgment of a spawn; then the ref fails
buffer-size = 100000 # messages held across every spawn still awaiting its worker
}
SchlüsselBedeutung
workers"auto" ist die verfügbare Parallelität der Maschine minus eins, weil der Main-Thread ein arbeitendes Mitglied ist: Er führt aus, was er nicht ausgelagert hat, und relayt jeden Frame zwischen Workern. Ein CPU-Kontingent eines Containers wird berücksichtigt, wo die Runtime es zeigt (os.availableParallelism()), sonst greift navigator.hardwareConcurrency.
offloadWelche Top-Level-Actors wandern. * passt auf ein Pfadsegment, ** auf eines oder mehrere; /user/resize-* ist in Ordnung. Ein Muster, das /system erreichen könnte, wird abgelehnt — siehe Systemactors auf Workern.
placementconsistent-hash hasht den Actor-Namen, sodass derselbe Name über Neustarts der Anwendung hinweg auf demselben Worker landet. round-robin verteilt Spawns gleichmäßig in Spawn-Reihenfolge.
leaderDer Cluster-Leader ist das Mitglied mit der niedrigsten Adresse; main hält ihn auf dem Main-Thread, worker verschiebt ihn — und den Shard-Coordinator mit ihm — auf einen Worker.
spawn-timeoutWie lange ein Spawn auf die Bestätigung des Workers wartet, bevor die Ref fehlschlägt und ihr Puffer zu Dead Letters wird.
buffer-sizeDie Schranke für Nachrichten an Actors, deren Worker sie noch nicht bestätigt haben, über das ganze System. Darüber hinaus gehen die restlichen mit einer einmaligen Warnung zu Dead Letters.

Die Threads selbst — Hostnamen, Ports, Cluster-Rollen, das Ready-Timeout, das Restart-Pacing und wie oft die Metriken der Worker in das /metrics des Main-Threads gezogen werden (worker-mesh.metrics-relay-interval) — werden dort konfiguriert, wo das Worker-Mesh sie liest: actor-ts.worker-mesh.* und actor-ts.worker-cluster.*. Ein Knopf lebt an einem Ort.

system.spawn bleibt synchron. Passt der Pfad auf offload:

  1. Der Name wird so geprüft, wie ein lokaler Spawn ihn prüft, auf dem Stack des Aufrufers.
  2. Ein Worker wird gewählt — per Hash des Namens oder Round-Robin.
  3. Eine Pending-Ref wird sofort zurückgegeben. Ihre path, equals und toString stehen fest; ein tell, bevor der Worker geantwortet hat, wird in Reihenfolge gepuffert und in dem Moment nachgespielt, in dem er antwortet. Ein ask funktioniert genauso.
  4. Ein Spawn-Frame geht an den Worker, der den Namen validiert, den Actor unter seinem eigenen /user erzeugt und mit dem Pfad bestätigt. Die Pending-Ref schaltet auf eine Remote-Ref um und leert ihren Puffer.

Ein Spawn, den der Worker ablehnt — eine Klasse, die er nicht findet, ein dort schon vergebener Name — lässt die Ref fehlschlagen: Alles, was sie hielt, wird zum Dead Letter mit der Ref als Empfänger, und alles danach ebenso. Der Grund wird geloggt. Ein Worker, der nie antwortet, lässt die Ref bei spawn-timeout fehlschlagen.

Bevor das Mesh oben ist, warten Spawns und ihre Refs puffern. Ein Mesh, das nicht startet — ein Modul, das sich nicht importieren lässt, ein Worker, der nie ready wird — wird einmal geloggt, lässt das Wartende fehlschlagen und lässt jeden späteren ausgelagerten spawn mit der Ursache werfen.

system.terminate() bleibt der eine Aufruf, mit dem die Anwendung herunterfährt. Er terminiert zuerst das System jedes Workers — sodass ein ausgelagerter Actor sein postStop bekommt wie ein lokaler —, wartet auf sie (begrenzt durch dasselbe shutdown-drain-timeout, das die Worker nutzen, plus eine Sekunde), und stoppt dann die Threads und die eigenen Actors des Main-Threads.

context.spawn wird nicht umgelenkt. Ein Kind wird im Heap seines Elters konstruiert — auf dem Thread, auf dem dessen onReceive läuft —, weil Supervision ein lebendiges Error und eine Ref vom Kind zum Elter reicht, Death Watch auf Kinder eine direkte Verbindung ist und Eltern–Kind die geschwätzigste Beziehung in einem Actor-System ist. Also ist die Auslagerungseinheit der Teilbaum: Ein ausgelagerter Top-Level-Actor nimmt seine Kinder mit, und Last verteilt sich über mehrere Top-Level-Actors, Sharding oder einen Cluster-Router über einen Routee pro Worker — ein lokaler Router kann sie nicht verteilen, weil seine Routees seine Kinder sind — nicht über mehr Worker pro Teilbaum. Pfade sind davon unberührt: ref.path.toString() ist gleich, ob der Actor lokal oder ausgelagert ist, weil ein Pfad den Systemnamen trägt und nicht den Thread.

offload lehnt jedes Muster ab, das /system erreichen könnte — /system/* genauso wie /* oder /** —, aus zwei Gründen. Framework-Actors werden über eine interne Tür erzeugt statt über spawn, der Eintrag täte also nichts; und kein Knoten darf /system/… ohnehin per Namen über die Wire adressieren. Der Fehler nennt den Weg, der funktioniert, denn der Wunsch ist legitim, und ein Worker ist ein Cluster-Knoten — die Platzierung, die der Cluster schon hat, gilt für ihn unverändert:

  • ein Singleton oder ein Sharding-Entity-Typ mit einer Rolle, die nur die Worker tragen (actor-ts.worker-mesh.worker-roles), läuft auf einem Worker;
  • der Shard-Coordinator folgt dem Leader, und leader = "worker" verschiebt ihn. Mit den Standard-Hostnamen sortiert der Main-Thread zuerst und führt; leader = "worker" gibt den Workern den Hostnamen compute, der vor main sortiert. Hostnamen, die ein Operator explizit gesetzt hat, bleiben erhalten und werden abgelehnt, wenn sie dem Leader widersprechen.

Infrastruktur pro Knoten — der PubSub-Mediator, der Replikator, Shard-Regionen, die DevTools-Sonde — existiert auf jedem Worker ohnehin; da ist nichts zu verschieben.

Persistence ist das eine Stück, das ein Worker beim Start nicht öffnet. Das System eines Workers wird aus der effektiven Konfiguration des Main-Threads gebaut, samt dessen Persistence-Auswahl, aber nichts von dem Code, der die Plug-ins registriert hat, wechselt den Thread — während der Main-Thread seine ausgewählten Stores als Teil des Starts öffnet, öffnet ein Worker also keinen, und sein Start kann nicht an einem Plug-in scheitern, das er nie bekommen hat. Ein Store, den ein ausgelagerter Actor benutzt, wird auf diesem Worker bei der ersten Verwendung aufgelöst, aus dem, was der Worker selbst registriert hat.

Ein ausgelagerter Actor fehlt im Zellbaum des Main-Threads: nicht in ActorSelection, nicht im DevTools-Baum des Main-Threads. Seine Metriken erreichen den Main-Thread aber: Alle actor-ts.worker-mesh.metrics-relay-interval (Default 10s) zieht das Mesh die Registry jedes Workers, und GET /metrics auf dem Main-Thread exportiert den ganzen Prozess, jede Serie mit thread="main" oder thread="worker-N" — sum without (thread) für die Prozesssumme, siehe den Geltungsbereich eines Scrapes. Die Werte eines Workers sind höchstens ein Intervall alt, und worker_mesh_snapshot_age_seconds sagt, wie alt. Mit workers = 0 gilt nichts davon, und die Exposition ist exakt die alte.

benchmarks/parallelism/config-scaling.ts lässt dieselbe Anwendung unter workers = 0, 1, 2, 4, 8, auto laufen — sechzehn Actors, je eine Nachricht pro Iteration — in zwei Formen: cpu, wo jede Nachricht eine feste Menge Maschinenzeit verbrennt, und chatty, wo eine Nachricht nichts tut, außer beantwortet zu werden. Speed-up gegenüber workers = 0:

Form / workers1248auto (31)
cpu · 10 µs pro Nachricht0.16x0.19x0.17x0.15x0.13x
cpu · 100 µs pro Nachricht0.57x0.97x1.15x1.17x0.64x
cpu · 1 ms pro Nachricht0.86x1.67x3.01x4.03x4.60x
chatty0.05x0.05x0.05x0.04x0.01x

Gemessen am 2026-09-16 auf Bun 1.4.2, Windows 11, 32 Hardware-Threads.

Drei Dinge lassen sich ablesen. Die Threads erreichen den Break-even bei etwa hundert Mikrosekunden Arbeit pro Nachricht und zahlen sich ab dort aus — viermal schneller bei einer Millisekunde. Ein geschwätziger Actor ist auf einem Worker zwanzigmal langsamer als zu Hause; das ist die Zahl, aus der folgt, offload für eine Anwendung mit vor allem weiterleitenden Actors enger als /user/* zu halten. Und die Decke ist das Relay: Jeder Frame zwischen zwei Threads und jede Gossip-Runde des Mesh läuft über den Main-Thread, weshalb auto auf einer 32-Thread-Maschine bei hundert Mikrosekunden gegen acht Worker verliert — sechzehn Actors können einunddreißig Worker nicht nutzen, und die untätigen kosten das Relay trotzdem ihre Heartbeats. workers nach den rechnenden Actors bemessen, nicht nach den Kernen.

  • Worker-Mesh — die Schicht darunter: die Threads, der Broker, die Hostnamen und das Restart-Pacing.
  • Dispatcher — ein Dispatcher entscheidet, wann ein Actor auf seinem Thread läuft; er ist kein Thread.
  • Cluster-Sharding — einen Entity-Typ per Rolle über die Worker verteilen.
  • Death Watch — watch() auf einem ausgelagerten Actor funktioniert, über den Thread hinweg.