Zum Inhalt springen
Deutsch

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.

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.

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 OffloadPool unten: 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 ClusterRouter auf dem Main-Thread über den Routee, den das Actor-Modul jedes Workers in setup spawnt. Ein lokaler Router-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.

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 framework
export 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']);

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}.

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 Aufrufpool(1)pool(31)
1 µs0.26×0.14×
10 µs0.66×1.23×
100 µs0.91×8.2×
1 ms0.96×14.6×
10 ms0.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.

  • Ein *Sync(-Aufruf in einem Handler — gzipSync, pbkdf2Sync, readFileSync, execSync. Seine Async-Form ist Stufe 1; gibt es keine, Stufe 2.
  • Ein while oder for ü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 offload existiert.
  • JSON.parse eines 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.

  • 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.