Blockierende und CPU-lastige Arbeit
Ein Actor-System auf Bun, Node oder Deno läuft auf einem Thread. Jedes
onReceive jedes Actors läuft darauf, jeder Timer feuert darauf, jeder
Socket wird darauf gelesen. Das macht das Modell billig — ein tell ist
ein Array-Push — und es ist zugleich das Eine, das den ganzen Prozess auf
einmal lahmlegen kann: Ein Handler, der hundert Millisekunden rechnet,
hält jeden Actor hundert Millisekunden an. Diese Seite handelt davon,
wohin rechnende Arbeit gehört.
await ist keine Parallelität
Abschnitt betitelt „await ist keine Parallelität“Ein asynchrones onReceive wird von der Zelle des Actors awaited: Die
Mailbox wartet, die nächste Nachricht wird nicht zugestellt, bis das
Promise settled. Während der Handler an einem await hängt, ist die
Event-Loop frei und jeder andere Actor läuft — genau richtig für I/O, wo
die Arbeit woanders passiert (im Kernel, in einer Datenbank, auf einem
Socket) und das await ein Warten ist.
Für CPU bringt es nichts. Eine Schleife, die ein Passwort hasht, einen
Buffer komprimiert oder eine FFT über ein Sensorfenster faltet, läuft auf
dem einen Thread bis zum Ende, bevor irgendetwas anderes drankommt, und sie
in async oder Promise.resolve().then(...) zu wickeln, verschiebt sie
auf eine spätere Runde, ohne sie zu verkürzen. Hinter einem Promise steht
kein Thread-Pool.
Drei Stufen
Abschnitt betitelt „Drei Stufen“Rechnende Arbeit gehört an einen von drei Orten, und der erste ist der am häufigsten vergessene.
1. Native Async-APIs, die bereits auf einem Thread-Pool laufen. Die
Runtime bringt genau dafür einen Thread-Pool mit, erreichbar nur über die
asynchronen Formen: zlib.gzip (nicht gzipSync), crypto.scrypt /
pbkdf2 / hkdf, crypto.subtle.*, fs.promises.*, dns.promises.*.
Die Arbeit läuft abseits des Main-Threads, und das await ist ein echtes
Warten. Gibt es für das, was du tust, eine native Async-Form, nimm sie —
nichts weiter unten schlägt sie.
Ein gemessener Vorbehalt (Node 26, Bun 1.4, Deno 2.6; ein 24-MiB-Body mit
einem 1-ms-Timer, der über das await hinweg läuft): Auf Deno schieben
die asynchronen Formen von node:zlib den Aufruf auf und führen das
Deflate dann als einen Block auf dem Main-Thread aus — der Timer feuerte
0-mal, genau wie unter gzipSync, wo Bun und Node ihn 30–115-mal feuern
ließen. crypto.scrypt geht auf allen dreien in den Pool. Auf Deno ist
das Komprimieren eines großen Bodys also Stufe 2: gib es dem
OffloadPool unten. Die Object-Storage-Komprimierung des Frameworks
ruft die asynchronen Formen auf und dokumentiert diesen Rest, statt selbst
durch den Pool zu leiten — siehe
Komprimierung.
2. Worker-Threads, für reine JS-CPU-Arbeit. Drei Formen, je nachdem, was die Arbeit ist:
- eine Funktion — hash das, komprimiere jenes, transformiere dieses
Fenster — geht an den
OffloadPoolunten:context.offload(task, args), ein Ergebnis zurück, kein Actor auf der anderen Seite; - ein Actor, dessen ganzes Leben Rechnen ist, geht auf einen eigenen
Worker-Thread, transparent, über
actor-ts.parallelism.workers— der Actor und sein Teilbaum laufen dort, und jede Nachricht an ihn überquert den Thread. Das Worker-Mesh ist die Schicht darunter, um die Threads von Hand zu steuern; - N identische Actors, einer pro Worker, hinter einer lokalen
Adresse — ein
ClusterRouterauf dem Main-Thread über den Routee, den das Actor-Modul jedes Workers insetupspawnt. Ein lokalerRouter-Pool ist nicht diese Stufe: Seine Routees sind Kinder auf dem Thread des Routers, er kauft also Nebenläufigkeit für Handler, die warten, und nie einen zweiten Core. Die Entscheidungsmatrix im Routing-Überblick stellt die fünf Mechanismen nebeneinander, mit dem Rezept und seinen drei Fallen.
3. Native Addons, die eigene Threads mitbringen. Eine Bibliothek mit Rust- oder C++-Kern (ein Bild-Codec, ein Datenbanktreiber), die ihre Arbeit abseits des JS-Threads erledigt und ein Promise auflöst, ist aus Sicht des Actors Stufe 1: awaiten.
Reihenfolge: Ein ausgelagertes Ergebnis ist eine spätere Nachricht
Abschnitt betitelt „Reihenfolge: Ein ausgelagertes Ergebnis ist eine spätere Nachricht“Auf welcher Stufe die Arbeit auch läuft, sie endet, nachdem der Handler, der sie gestartet hat, zurückgekehrt ist. Der Actor mag bis dahin zehn weitere Nachrichten verarbeitet haben; sein Zustand ist nicht mehr der von vorher. Also muss das Ergebnis als Nachricht zurückkommen, nicht als Continuation, die in den Zustand greift:
import { Actor, ActorRef, defineOffloadTask } from 'actor-ts';
const hashPassword = defineOffloadTask<[string], string>( new URL('./hash.js', import.meta.url), 'hashPassword',);
type Command = | { readonly kind: 'register'; readonly password: string; readonly replyTo: ActorRef<string> } | { readonly kind: 'hashed'; readonly hash: string; readonly replyTo: ActorRef<string> };
class Registrar extends Actor<Command> { private registered = 0;
override onReceive(command: Command): void { if (command.kind === 'register') { // The result comes back to this actor as a message of its own. void this.context.offload(hashPassword, [command.password]) .then((hash) => this.context.self.tell({ kind: 'hashed', hash, replyTo: command.replyTo })); } else { this.registered++; // state is touched on the actor's own turn command.replyTo.tell(command.hash); } }}Die Continuation tut eine Sache: Sie macht aus dem Ergebnis ein tell.
Sie erhöht nicht registered, denn wenn sie läuft, kann der Actor mitten
in einer anderen Nachricht sein — oder neu gestartet, oder gestoppt —, und
ein Callback, der Zustand außerhalb der Runde des Actors verändert, ist
genau der Nebenläufigkeitsfehler, den das Actor-Modell unmöglich machen
soll. pipeTo-Muster und ask aus einem Actor heraus folgen derselben
Regel; die Seite Futures-Patterns hat
die Formen.
OffloadPool: Reine Funktionen auf Worker-Threads
Abschnitt betitelt „OffloadPool: Reine Funktionen auf Worker-Threads“Der blockierende Dispatcher der Single-Thread-Runtime. Ein Task ist ein benannter Export eines Moduls — eine Funktion kann keinen Thread überqueren, also wird sie benannt statt übergeben —, und seine Argumente und sein Ergebnis werden structured-cloned. Jeder Worker importiert das Modul einmal und behält es; ein Lauf kostet den Klon seiner Argumente und den Klon seines Ergebnisses.
// src/hash.ts — pure, importable by a worker, nothing from the frameworkexport function hashPassword(password: string): string { let hash = 0; for (let round = 0; round < 200_000; round++) { for (let i = 0; i < password.length; i++) hash = (hash * 31 + password.charCodeAt(i)) | 0; } return hash.toString(16);}import { defineOffloadTask } from 'actor-ts';
// Resolved against the caller, so the worker finds the same file.const hashPassword = defineOffloadTask<[string], string>( new URL('./hash.js', import.meta.url), 'hashPassword',);Aus einem Actor heraus lässt context.offload(task, args, options?) ihn
auf dem Standard-Pool des Systems laufen und löst mit dem Ergebnis auf.
Außerhalb eines Actors, oder für einen zweiten Pool mit eigenen
Einstellungen, baut man einen:
import { ActorSystem } from 'actor-ts';import { OffloadPool, OffloadPoolOptions } from 'actor-ts/worker';
const system = ActorSystem.create('app');const offloadPoolOptions = OffloadPoolOptions.create() .withSize(4) .withTaskTimeoutMs(5_000);const pool = OffloadPool.start(system, offloadPoolOptions);
const hash = await pool.run(hashPassword, ['correct horse battery staple']);Was der Pool tut
Abschnitt betitelt „Was der Pool tut“Worker werden gespawnt, wenn Tasks eintreffen, bis size, und jenseits
von min-size nach idle-timeout ohne Arbeit wieder abgebaut — ein
ruhiger Pool kostet nichts. Ein Task, der wirft, lässt den Lauf mit einem
OffloadTaskError fehlschlagen, der Name, Message und Stack des Workers
trägt; der Worker überlebt. Ein Lauf jenseits seiner Deadline schlägt mit
OffloadTimeoutError fehl, und der Worker wird terminiert, weil der
Thread zu stoppen der einzige Weg ist, synchrones JavaScript zu stoppen;
der Pool spawnt innerhalb eines Restart-Budgets einen Ersatz, und jenseits
des Budgets hört er auf zu spawnen und jeder Lauf schlägt sofort mit
OffloadPoolUnavailableError fehl — lauter als ein Pool, der still nichts
tut. Ein AbortSignal des Aufrufers bricht einen wartenden Lauf ab, ohne
einen Worker anzufassen, und einen laufenden, indem sein Worker terminiert
wird, ohne das Budget zu belasten. system.terminate() stoppt jeden
Worker.
actor-ts.offload-pool { size = "auto" # workers at most; "auto" = available parallelism minus the main thread min-size = 0 # workers kept alive through idleness max-queue = 10000 # tasks waiting for a worker before overflow decides overflow = "reject" # reject (OffloadQueueFullError) | wait (back-pressure) idle-timeout = 60s # a worker beyond min-size with nothing to do is retired after this task-timeout = 0s # 0 = no deadline unless run() names one; a deadline terminates the worker max-restarts = 10 # worker terminations (crash, deadline) replaced inside restart-window; -1 = forever restart-window = 60s warm-up = off # spawn every worker at start instead of on the first task that needs it}overflow = "wait" hält einen Lauf offen, bis ein Warteschlangenplatz
frei wird — Gegendruck, den der Aufrufer als Latenz spürt statt als
Fehler. Der Default lehnt ab, die eigene Wahl der Mailbox für eine
Schranke: Ein Aufrufer, der OffloadQueueFullError sieht, kann abwerfen
oder wiederholen; einer, der wartet, kann Warten nicht von Hängen
unterscheiden.
Ein Transferable in den Argumenten — ein ArrayBuffer unter einem Typed
Array — kann verschoben statt kopiert werden: pool.run(task, [bytes.buffer], { transfer: [bytes.buffer] }). Die Sicht des Aufrufers
ist danach detached. Die Transferliste nimmt den ArrayBuffer, nie die
Sicht: Ein Eintrag, der nicht transferierbar ist, oder ein bereits
verschobener Buffer lässt den Lauf sofort mit OffloadArgumentsError
fehlschlagen — der Worker hat nichts erhalten und bleibt unberührt.
Das Verschieben gilt nur für die Argumente — das Ergebnis kommt per
Structured Clone zurück, wie groß es auch ist. Ein SharedArrayBuffer
unter den Argumenten wird weder kopiert noch verschoben, sondern
geteilt: Beide Threads lesen und schreiben denselben Speicher,
Atomics ist das Koordinationsprimitiv, und weder eine Transferliste
noch das Framework sind daran beteiligt. Beides sind Eigenschaften des
Structured Clone der Runtime, gelten also auf Bun 1.4.2, Node 26 und
Deno 2.6.8 gleichermaßen, und der Offload-Smoke-Case hält sie auf allen
dreien fest.
Der Pool meldet offload_tasks_total{task, outcome},
offload_queue_depth und offload_task_seconds{task}.
Wann es sich lohnt
Abschnitt betitelt „Wann es sich lohnt“Die Grenze ist nicht umsonst: Ein Hop kostet einen Structured Clone in
jede Richtung und zwei Event-Loop-Runden, etwa drei Mikrosekunden pro Task
bei gepipelineten Aufrufen. benchmarks/worker/task-offload-breakeven.ts
misst, ab wann der Pool gegen dieselbe Schleife inline gewinnt (Bun 1.4.2,
32 Hardware-Threads, 32 Tasks pro Iteration):
| Arbeit pro Aufruf | pool(1) | pool(31) |
|---|---|---|
| 1 µs | 0.26× | 0.14× |
| 10 µs | 0.66× | 1.23× |
| 100 µs | 0.91× | 8.2× |
| 1 ms | 0.96× | 14.6× |
| 10 ms | 0.96× | 15.0× |
Der Break-even liegt also bei etwa zehn Mikrosekunden Arbeit pro Aufruf, hundert Mikrosekunden sind der Punkt, an dem der Pool klar gewinnt, und ein Task, der weniger braucht, gehört inline. Ein Passwort-Hash, eine Komprimierung, eine Bildtransformation liegen alle weit darüber.
Gerüche
Abschnitt betitelt „Gerüche“- Ein
*Sync(-Aufruf in einem Handler —gzipSync,pbkdf2Sync,readFileSync,execSync. Seine Async-Form ist Stufe 1; gibt es keine, Stufe 2. - Ein
whileoderforüber ein großes Array pro Nachricht. Einmal pro Nachricht sind hundertmal pro Sekunde; die Schleife verschieben oder das Array verkleinern. - Ein Hash oder eine Komprimierung pro Request, auf dem Actor. Die
häufigste Abkürzung, und die, für die
offloadexistiert. JSON.parseeines mehrere Megabyte großen Bodys auf dem Actor. Am Rand beim Hereinkommen parsen, auslagern oder streamen.- Ein
O(users)-Scan pro Lookup. Kein Threading-Problem — ein Index.
Der erste Geruch ist abgesichert: tests/unit/ci/NoSyncWorkInHandlers.test.ts
durchsucht src/ und examples/ nach einer geschlossenen Liste der
blockierenden *Sync-Namen von Node — zlib, die Crypto-Key-Derivations,
Kindprozesse, das Dateisystem, @grpc/proto-loader — in
Erwähnungsposition, sodass ein Alias-Local oder ein Import-Specifier wie
ein Aufruf zählt, und weist jede Datei ab, die einen davon öfter erwähnt,
als ihr Ledger-Eintrag erlaubt. Das Ledger hält die Aufrufe, die laufen,
bevor ein Actor existiert (die Config-Kette, TLS-Material, ein in
preStart geparstes .proto), oder in einem Test-Harness, jeder mit
seinem Grund daneben; alles andere ist rot. Es ist ein Ratchet, kein
Gegner — zlib['gzipSync'] entgeht ihm —, also bleibt der Rest der Liste
oben die Review-Checkliste.
Wie es weitergeht
Abschnitt betitelt „Wie es weitergeht“- Parallelität — ganze Actors auf Worker-Threads, aus einer Konfigurationszahl.
- Dispatcher — ein Dispatcher entscheidet, wann ein Actor auf seinem Thread läuft; er ist kein Thread.
- Futures-Patterns — die Formen, um aus einem Promise wieder eine Nachricht zu machen.
- Worker-Mesh — die Threads darunter, von Hand gesteuert.
