Перейти к содержимому
Русский

Blocking and CPU-bound work

Это содержимое пока не доступно на вашем языке.

An actor system on Bun, Node or Deno runs on one thread. Every actor’s onReceive runs on it, every timer fires on it, every socket is read on it. That is what makes the model cheap — a tell is an array push — and it is also the one thing that can take the whole process down at once: a handler that computes for a hundred milliseconds stalls every actor for a hundred milliseconds. This page is about where work that computes should go.

An async onReceive is awaited by the actor’s cell: the mailbox waits, the next message is not delivered until the promise settles. While the handler is suspended at an await, the event loop is free and every other actor runs — which is exactly right for I/O, where the work happens elsewhere (the kernel, a database, a socket) and the await is a wait.

It does nothing for CPU. A loop that hashes a password, compresses a buffer or folds an FFT over a sensor window runs to completion on the one thread before anything else gets a turn, and wrapping it in async or Promise.resolve().then(...) moves it to a later turn without shortening it. There is no thread pool behind a promise.

Work that computes belongs in one of three places, and the first is the one most often forgotten.

1. Native async APIs that already run on a thread pool. The runtime ships a thread pool for exactly this, reachable only through the async forms: zlib.gzip (not gzipSync), crypto.scrypt / pbkdf2 / hkdf, crypto.subtle.*, fs.promises.*, dns.promises.*. The work runs off the main thread and the await is a real wait. If a native async form exists for what you do, use it — nothing below beats it.

One measured caveat (Node 26, Bun 1.4, Deno 2.6; a 24 MiB body with a 1 ms timer alive across the await): on Deno, node:zlib’s async forms defer the call and then run the deflate as one main-thread block — the timer fired 0 times, exactly as under gzipSync, where Bun and Node let it fire 30–115 times. crypto.scrypt does go to the pool on all three. So on Deno, compressing a large body is tier 2: hand it to the OffloadPool below. The framework’s own object-storage compression calls the async forms and documents this residual rather than routing through the pool itself — see Compression.

2. Worker threads, for pure-JS CPU work. Three shapes, by what the work is:

  • a function — hash this, compress that, transform this window — goes to the OffloadPool below: context.offload(task, args), a result back, no actor involved on the far side;
  • an actor whose whole life is compute goes to a worker thread of its own, transparently, through actor-ts.parallelism.workers — the actor and its subtree run there, and every message to it crosses the thread. The worker mesh is the layer underneath, for driving the threads by hand;
  • N identical actors, one per worker, behind one local address — a ClusterRouter on the main thread over the routee each worker’s actor module spawns in setup. A local Router pool is not this tier: its routees are children on the router’s own thread, so it buys concurrency for handlers that wait and never a second core. The decision matrix on the routing overview puts the five mechanisms side by side, with the recipe and its three traps.

3. Native addons that bring their own threads. A library backed by Rust or C++ (an image codec, a database driver) that does its work off the JS thread and resolves a promise is tier 1 from the actor’s point of view: await it.

Ordering: an offloaded result is a later message

Section titled “Ordering: an offloaded result is a later message”

Whichever tier the work runs on, it finishes after the handler that started it has returned. The actor may have handled ten more messages by then; its state is not what it was. So the result must come back as a message, not as a continuation that reaches into state:

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);
}
}
}

The continuation does one thing: it turns the result into a tell. It does not increment registered, because by the time it runs the actor may be mid-way through another message — or restarted, or stopped — and a callback that mutates state from outside the actor’s turn is the one concurrency bug the actor model exists to make impossible. pipeTo patterns and ask from inside an actor follow the same rule; the futures patterns page has the shapes.

OffloadPool: pure functions on worker threads

Section titled “OffloadPool: pure functions on worker threads”

The single-threaded runtime’s blocking dispatcher. A task is a named export of a module — a function cannot cross a thread, so it is named rather than passed — and its arguments and result are structured-cloned. Every worker imports the module once and keeps it; a run costs the clone of its arguments and the clone of its result.

// 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',
);

From inside an actor, context.offload(task, args, options?) runs it on the system’s default pool and resolves with the result. Outside an actor, or for a second pool with its own settings, build one:

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

Workers are spawned as tasks arrive, up to size, and retired beyond min-size after idle-timeout with nothing to do — a quiet pool costs nothing. A task that throws rejects the run with an OffloadTaskError carrying the worker’s error name, message and stack; the worker survives. A run past its deadline rejects with OffloadTimeoutError and the worker is terminated, because stopping the thread is the only way to stop synchronous JavaScript; the pool spawns a replacement inside a restart budget, and past the budget it stops spawning and every run fails at once with OffloadPoolUnavailableError — louder than a pool that quietly does nothing. A caller’s AbortSignal cancels a queued run without touching a worker, and a running one by terminating its worker, free of the budget. system.terminate() stops every 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" keeps a run pending until a queue slot frees — back-pressure the caller feels as latency rather than as an error. The default rejects, the mailbox’s own choice for a bound: a caller that sees OffloadQueueFullError can shed or retry, one that waits cannot tell waiting from a hang.

A transferable inside the arguments — an ArrayBuffer under a typed array — can be moved instead of copied: pool.run(task, [bytes.buffer], { transfer: [bytes.buffer] }). The caller’s view is detached afterwards. The transfer list takes the ArrayBuffer, never the view: an entry that is not transferable, or a buffer already moved, fails the run at once with OffloadArgumentsError — the worker received nothing and is untouched. The move is arguments only — the result is structured-cloned back, however large. A SharedArrayBuffer among the arguments is neither copied nor moved but shared: both threads read and write the same memory, Atomics is the coordination primitive, and no transfer list or framework support is involved. Both are properties of the runtime’s structured clone, so they hold on Bun 1.4.2, Node 26 and Deno 2.6.8 alike, and the offload smoke case keeps them held on all three.

The pool reports offload_tasks_total{task, outcome}, offload_queue_depth and offload_task_seconds{task}.

The boundary is not free: a hop costs a structured clone each way and two event-loop turns, about three microseconds a task when the calls are pipelined. benchmarks/worker/task-offload-breakeven.ts measures where the pool starts to win against running the same loop inline (Bun 1.4.2, 32 hardware threads, 32 tasks per iteration):

work per callpool(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×

So the crossover is about ten microseconds of work per call, a hundred microseconds is where the pool clearly wins, and a task that takes less than that belongs inline. A password hash, a compression, an image transform are all well past it.

  • A *Sync( call in a handler — gzipSync, pbkdf2Sync, readFileSync, execSync. Its async form is tier 1; if there is none, tier 2.
  • A while or for over a large array per message. Once per message is a hundred times per second; move the loop or shrink the array.
  • A hash or a compression per request, on the actor. The commonest shortcut, and the one offload exists for.
  • JSON.parse of a multi-megabyte body on the actor. Parse on the way in at the edge, offload, or stream.
  • An O(users) scan per lookup. Not a threading problem — an index.

The first smell is guarded: tests/unit/ci/NoSyncWorkInHandlers.test.ts scans src/ and examples/ for a closed list of Node’s blocking *Sync names — zlib, the crypto key derivations, child processes, the filesystem, @grpc/proto-loader — in mention position, so an aliased local or an import specifier counts like a call, and refuses any file that mentions one more often than its ledger entry allows. The ledger holds the calls that run before any actor exists (the config chain, TLS material, a .proto parsed in preStart) or in a test harness, each with its reason beside it; everything else is red. It is a ratchet, not an adversary — zlib['gzipSync'] evades it — so the rest of the list above stays the review checklist.

  • Parallelism — whole actors on worker threads, from one config number.
  • Dispatchers — a dispatcher decides when an actor runs on its thread; it is not a thread.
  • Futures patterns — the shapes for turning a promise back into a message.
  • Worker mesh — the threads underneath, driven by hand.