Parallelism
Este conteúdo não está disponível em sua língua ainda.
JavaScript runs one thread per actor system. A worker thread is another
thread, and the framework can host an actor system on each one — the
worker mesh does exactly that. This page is about
the layer on top of it: placing actors on those threads without changing
the application. One config number starts the threads, and system.spawn
puts actors on them.
actor-ts.parallelism { workers = auto # 0 = off (the default) | N | "auto"}// unchanged, character for characterconst system = ActorSystem.create('my-app');const ref = system.spawn(ImageResizer, 'resizer');ref.tell({ kind: 'resize', bytes });With workers = 0 the system is the single-threaded one it always was: no
thread, no cluster, no module import, and spawn pays one null check.
With anything else, ActorSystem.create starts a mesh in the background —
the main thread joins a cluster of its own, spawns the workers, and every
worker joins it — and spawn becomes a placement decision. An actor
whose path matches offload is created on a worker; every other one is
created where it always was. Either way the call is synchronous and
returns an ActorRef whose path is the path the actor would have had at
home.
The actor module
Section titled “The actor module”spawn(ImageResizer, 'resizer') hands over a class object, and a class
cannot cross a thread: postMessage clones data, never code, and no
runtime can map a class object back to the module that defined it. So the
worker has to import() the classes itself, and the two sides agree on a
name for each one — its export name, which survives a minifier and
tells two classes with the same .name apart.
That is the one thing the application provides: a module that exports the actor classes to offload. Only exports — no registration, no decorators:
export { ImageResizer } from './actors/ImageResizer.js';export { ReportBuilder } from './actors/ReportBuilder.js';By convention it is actors.js (or .ts) next to the entry module —
the file the runtime was asked to run — and then nothing has to be
configured. To name another one, or several, do it in code:
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 is deliberately not a HOCON key, for the reason
worker-cluster.bootstrap has none: a config file must not decide which
code a worker runs. With workers above zero and no module anywhere,
ActorSystem.create throws an OptionsError naming the paths it looked
for and the option that names one.
A module may also export a setup(context); the worker runs it once its
node is up, with the system, the cluster and the registry in hand. That is
where an actor a worker should host from the start is spawned, and where
per-actor configuration that cannot cross a thread belongs (see below).
Configuration
Section titled “Configuration”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}| Key | Meaning |
|---|---|
workers | "auto" is the machine’s available parallelism minus one, because the main thread is a working member: it runs whatever it did not offload and relays every cross-worker frame. It honours a container’s CPU quota where the runtime exposes it (os.availableParallelism()), and falls back to navigator.hardwareConcurrency. |
offload | Which top-level actors move. * matches one path segment, ** one or more; /user/resize-* is fine. A pattern that could reach /system is refused — see System actors on workers. |
placement | consistent-hash hashes the actor’s name, so the same name lands on the same worker across restarts of the application. round-robin spreads spawns evenly in spawn order. |
leader | The cluster leader is the lowest-addressed member; main keeps it on the main thread, worker moves it — and the shard coordinator with it — onto a worker. |
spawn-timeout | How long a spawn waits for the worker to acknowledge it before the ref fails and what it held goes to dead letters. |
buffer-size | The bound on messages sent to actors whose workers have not acknowledged them yet, across the whole system. Past it, the rest go to dead letters with one warning. |
The threads themselves — hostnames, ports, cluster roles, the ready timeout,
restart pacing, and how often the workers’ metrics are pulled into the main
thread’s /metrics (worker-mesh.metrics-relay-interval) — are configured
where the worker mesh reads them:
actor-ts.worker-mesh.* and actor-ts.worker-cluster.*. One knob lives in
one place.
What a spawn does
Section titled “What a spawn does”system.spawn stays synchronous. When the path matches offload:
- The name is checked the way a local spawn checks it, on the caller’s stack.
- A worker is picked — by hash of the name, or round-robin.
- A pending ref is returned at once. Its
path,equalsandtoStringare settled; atellbefore the worker has answered is queued, in order, and replayed the moment it does. Anaskworks the same way. - A spawn frame goes to the worker, which validates the name, creates the
actor under its own
/user, and acknowledges with the path. The pending ref switches to a remote ref and drains its queue.
A spawn the worker refuses — a class it cannot find, a name already taken
there — fails the ref: everything it held becomes a dead letter naming the
ref as recipient, and so does everything sent afterwards. The reason is
logged. A worker that never answers fails the ref at spawn-timeout.
Before the mesh is up, spawns wait and their refs buffer. A mesh that fails
to start — a module that does not import, a worker that never becomes
ready — is logged once, fails what was waiting, and makes every later
offloaded spawn throw with the cause.
system.terminate() is still the one call the application makes to shut
down. It terminates every worker’s system first — so an offloaded actor
gets its postStop like a local one — waits for them (bounded by the same
shutdown-drain-timeout the workers use, plus a second), then stops the
threads and the main thread’s own actors.
Three limits, each with a loud error
Section titled “Three limits, each with a loud error”Children stay with their parent
Section titled “Children stay with their parent”context.spawn is not redirected. A child is constructed in its parent’s
heap — on whichever thread the parent’s onReceive runs — because
supervision hands a live Error and a ref from child to parent, child
death watch is a direct link, and parent–child is the chattiest
relationship in an actor system. So the unit of offload is the subtree:
an offloaded top-level actor takes its children with it, and load spreads
through several top-level actors, sharding, or a
cluster router over one routee per worker
— a local Router cannot spread it, since its routees are its children
— not through more workers per subtree. Paths are unaffected: ref.path.toString() is the
same whether the actor is local or offloaded, because a path carries the
system name and not the thread.
System actors on workers
Section titled “System actors on workers”offload refuses any pattern that could reach /system — /system/* as
much as /* or /** — for two reasons. Framework actors are created
through an internal door rather than spawn, so the entry would do
nothing; and no node may address /system/… by name across the wire
anyway. The error names the route that works, because the wish is
legitimate and a worker is a cluster node, so the placement the cluster
already has applies to it unchanged:
- a singleton or a sharded entity type with a role that only the
workers carry (
actor-ts.worker-mesh.worker-roles) runs on a worker; - the shard coordinator follows the leader, and
leader = "worker"moves it. With the default hostnames the main thread sorts first and leads;leader = "worker"gives the workers the hostnamecompute, which sorts beforemain. Hostnames an operator set explicitly are kept, and refused when they contradict the leader.
Per-node infrastructure — the pub-sub mediator, the replicator, shard regions, the DevTools probe — exists on every worker anyway; there is nothing to move.
Persistence is the one piece a worker does not open at startup. A worker’s system is built from the main thread’s effective configuration, its persistence selection included, but none of the code that registered the plug-ins crosses the thread — so where the main thread opens its selected stores as part of its startup, a worker opens none, and its startup cannot fail over a plug-in it was never given. A store an offloaded actor uses is resolved on that worker at first use, from what the worker itself has registered.
What is visible, and what is not
Section titled “What is visible, and what is not”An offloaded actor is absent from the main thread’s cell tree: not in
ActorSelection, not in the DevTools tree of the main thread. Its
metrics do reach the main thread: every
actor-ts.worker-mesh.metrics-relay-interval (default 10s) the mesh
pulls each worker’s registry, and GET /metrics on the main thread
exports the whole process, each series carrying thread="main" or
thread="worker-N" — sum without (thread) for the process total, see
the scope of a scrape.
A worker’s figures are at most one interval old, and
worker_mesh_snapshot_age_seconds says how old. With workers = 0 none
of this applies, and the exposition is exactly what it was.
The measured table
Section titled “The measured table”benchmarks/parallelism/config-scaling.ts runs the same application under
workers = 0, 1, 2, 4, 8, auto — sixteen actors, one message each per
iteration — in two shapes: cpu, where each message burns a fixed amount
of the machine’s time, and chatty, where a message does nothing but
get answered. Speed-up against workers = 0:
| Shape / workers | 1 | 2 | 4 | 8 | auto (31) |
|---|---|---|---|---|---|
| cpu · 10 µs per message | 0.16x | 0.19x | 0.17x | 0.15x | 0.13x |
| cpu · 100 µs per message | 0.57x | 0.97x | 1.15x | 1.17x | 0.64x |
| cpu · 1 ms per message | 0.86x | 1.67x | 3.01x | 4.03x | 4.60x |
| chatty | 0.05x | 0.05x | 0.05x | 0.04x | 0.01x |
Measured 2026-09-16 on Bun 1.4.2, Windows 11, 32 hardware threads.
Three things to read off it. The threads break even at about a hundred
microseconds of work per message and pay from there — four times faster
at a millisecond. A chatty actor is twenty times slower on a worker
than at home, which is the number behind keeping offload narrower than
/user/* for an application whose actors mostly forward. And the ceiling
is the relay: every frame between two threads, and every gossip round of
the mesh, passes through the main thread, so auto on a 32-thread machine
loses to eight workers at a hundred microseconds — sixteen actors cannot
use thirty-one workers, and the idle ones still cost the relay their
heartbeats. Size workers to the actors that compute, not to the cores.
Where to next
Section titled “Where to next”- Worker mesh — the layer underneath: the threads, the broker, the hostnames and restart pacing.
- Dispatchers — a dispatcher decides when an actor runs on its thread; it is not a thread.
- Cluster sharding — spreading one entity type over the workers by role.
- Death watch —
watch()on an offloaded actor works, across the thread.
