@tinyactors/node 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +648 -154
- package/docs/guide/browser.md +494 -0
- package/docs/guide/capacity.md +202 -0
- package/docs/guide/charts.md +578 -0
- package/docs/guide/hibernation.md +201 -0
- package/docs/guide/inspection.md +381 -0
- package/docs/guide/io-processors.md +269 -0
- package/docs/guide/migration.md +323 -0
- package/docs/guide/other-systems.md +275 -0
- package/docs/guide/quickjs.md +135 -0
- package/docs/guide/services.md +317 -0
- package/docs/guide/snapshots.md +186 -0
- package/docs/guide/telemetry.md +265 -0
- package/docs/guide/testing.md +272 -0
- package/docs/values.md +107 -0
- package/index.d.ts +1166 -1820
- package/index.mjs +6 -0
- package/lib/convenience.mjs +162 -0
- package/lib/direct.mjs +65 -0
- package/package.json +29 -16
- package/index.js +0 -34
- package/lib/actor.js +0 -85
- package/lib/debug/breakpoints.js +0 -349
- package/lib/debug/console.js +0 -149
- package/lib/debug/expressions.js +0 -133
- package/lib/debug/frames.js +0 -119
- package/lib/debug/labels.js +0 -142
- package/lib/debug/macrosteps.js +0 -207
- package/lib/debug/protocol.js +0 -186
- package/lib/debug/sources.js +0 -218
- package/lib/debug/variables.js +0 -265
- package/lib/debug.js +0 -1434
- package/lib/definition.js +0 -139
- package/lib/errors.js +0 -24
- package/lib/events.js +0 -56
- package/lib/image.js +0 -90
- package/lib/loader.js +0 -68
- package/lib/metrics.js +0 -333
- package/lib/native.js +0 -8
- package/lib/otlp.js +0 -332
- package/lib/statechart.js +0 -768
- package/lib/system.js +0 -2183
- package/lib/tracing.js +0 -164
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# Capacity and memory
|
|
2
|
+
|
|
3
|
+
A host keeps its actors in blocks of memory it sizes from the config,
|
|
4
|
+
one block (a **region**) per segment, that is per `addImage`. You can
|
|
5
|
+
leave the sizes to the host, which grows a region when something in it
|
|
6
|
+
runs out, or size a host up front for the population you expect. This
|
|
7
|
+
guide says what the sizes are, how a region grows, how to read what a
|
|
8
|
+
host uses, and what an actor costs.
|
|
9
|
+
|
|
10
|
+
## The sizes
|
|
11
|
+
|
|
12
|
+
The config's `system` map gives each new segment its first sizes. Each
|
|
13
|
+
key is a whole number; an absent key, or 0, is the default:
|
|
14
|
+
|
|
15
|
+
| Key | Default | What it counts |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| `maxActors` | 64 | actors, hibernated ones included |
|
|
18
|
+
| `maxEvents` | 256 | events waiting in the actors' queues |
|
|
19
|
+
| `maxTimers` | 64 | pending delayed sends |
|
|
20
|
+
| `maxRequests` | 16 | running invocations (child charts and services) |
|
|
21
|
+
| `workspaces` | 4 | actors in the middle of a step at once (a sender keeps its workspace until its send is handled); never refused: an actor waits for one, and the host adds more |
|
|
22
|
+
| `instanceBytes` | derived from the image and `maxActors` | the actors' variables and states |
|
|
23
|
+
| `stringBytes` | 16384 + 16 × `maxActors` | strings the actors hold |
|
|
24
|
+
| `ticksPerSecond` | 1,000,000,000 | the host's clock rate |
|
|
25
|
+
|
|
26
|
+
A size is a segment's first size, not a limit. When a pool fills, the
|
|
27
|
+
host grows that segment between runs, into a new region with more of what
|
|
28
|
+
ran out and the rest as it was. A pool doubles, or grows by more, up to 16 times
|
|
29
|
+
at once, when doubling would add less than a quarter of the region, so a
|
|
30
|
+
small pool beside a large region grows in a few copies, and in proportion
|
|
31
|
+
to itself. A grown region
|
|
32
|
+
never shrinks. A run or an input is refused (`TA_ERROR_NO_MEMORY`) only
|
|
33
|
+
when a pool is at its largest size (`maxActors` is at most 8,388,606) or
|
|
34
|
+
the system allocator refuses the memory.
|
|
35
|
+
|
|
36
|
+
## Reading what a host uses
|
|
37
|
+
|
|
38
|
+
`host.hostStats` ([Inspecting a host](inspection.md)) answers with
|
|
39
|
+
`pools`, an array of one entry per live segment, in segment order. Each
|
|
40
|
+
entry has its `segment` (the number `addImage` returned) and, for
|
|
41
|
+
`actors`, `events`, `timers`, `workspaces`, `requests` and `slabBytes`
|
|
42
|
+
(the instance and string memory), the pool's `capacity`, what it holds
|
|
43
|
+
now (`used`) and the most it held at once (`highWater`). Each segment
|
|
44
|
+
grows on its own, so their pools are reported apart: two images, or a
|
|
45
|
+
migration's old and new versions, are two entries.
|
|
46
|
+
|
|
47
|
+
```js
|
|
48
|
+
import { compileCharts, Host } from '@tinyactors/node';
|
|
49
|
+
|
|
50
|
+
const compiled = compileCharts([{ name: 'idle.scxml', text: `
|
|
51
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
52
|
+
datamodel="ecmascript" name="idle"><state id="waiting"/></scxml>` }]);
|
|
53
|
+
const image = compiled.image;
|
|
54
|
+
compiled.close();
|
|
55
|
+
|
|
56
|
+
for (const system of [{}, { maxActors: 1000 }]) {
|
|
57
|
+
const host = new Host({ systemID: 'demo', system });
|
|
58
|
+
host.addImage(image);
|
|
59
|
+
const before = (await host.hostStats()).pools[0].actors;
|
|
60
|
+
for (let i = 0; i < 1000; i++) host.spawn(host.chart('idle'));
|
|
61
|
+
const after = (await host.hostStats()).pools[0].actors;
|
|
62
|
+
console.log(`maxActors ${system.maxActors ?? 'default'}: capacity ${before.capacity}, ` +
|
|
63
|
+
`then ${after.used} used, high water ${after.highWater}, grown: ${after.capacity > before.capacity}`);
|
|
64
|
+
|
|
65
|
+
host.addImage(image);
|
|
66
|
+
console.log('segments reported:', (await host.hostStats()).pools.map((pool) => pool.segment).join(', '));
|
|
67
|
+
host.close();
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
```output
|
|
72
|
+
maxActors default: capacity 64, then 1000 used, high water 1000, grown: true
|
|
73
|
+
segments reported: 0, 1
|
|
74
|
+
maxActors 1000: capacity 1000, then 1000 used, high water 1000, grown: false
|
|
75
|
+
segments reported: 0, 1
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`highWater` against `capacity` is what a config sized up front needs: run
|
|
79
|
+
a realistic load, read the high-water marks, and give the next host those
|
|
80
|
+
sizes. `host.hostConfig()` answers the sizes a host was made with, every
|
|
81
|
+
default filled in.
|
|
82
|
+
|
|
83
|
+
## Sizing a host up front
|
|
84
|
+
|
|
85
|
+
Growing costs a copy of the region each time, and a grown region keeps
|
|
86
|
+
its size, so a host that will hold a known population is better sized for
|
|
87
|
+
it. A hibernated actor keeps its slot and its record in the host (about
|
|
88
|
+
64 bytes), so `maxActors` counts every actor, while the instance and
|
|
89
|
+
string memory are needed for the resident ones only. For `R` actors
|
|
90
|
+
resident out of `N` on a counter chart of a few variables, the
|
|
91
|
+
repository's hibernation gate uses:
|
|
92
|
+
|
|
93
|
+
```js
|
|
94
|
+
import { Host } from '@tinyactors/node';
|
|
95
|
+
|
|
96
|
+
const N = 2_000_000; // actors
|
|
97
|
+
const R = 1000; // resident at most
|
|
98
|
+
const room = 64;
|
|
99
|
+
const host = new Host({ systemID: 'big', system: {
|
|
100
|
+
maxActors: N + room, maxEvents: 4096,
|
|
101
|
+
instanceBytes: 2048 * (R + room), stringBytes: 16384 + 64 * (R + room),
|
|
102
|
+
} });
|
|
103
|
+
console.log((await host.hostConfig()).system.maxActors);
|
|
104
|
+
host.close();
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
```output
|
|
108
|
+
2000064
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
A chart with more variables or longer strings needs more per resident
|
|
112
|
+
actor; read `slabBytes.highWater` under load to see.
|
|
113
|
+
|
|
114
|
+
## What an actor costs
|
|
115
|
+
|
|
116
|
+
Measured with `mise run measure` in the repository (2026-10-17, x86_64
|
|
117
|
+
Linux 6.18, Intel Xeon @ 2.10GHz, 4 CPUs, 16 GiB; node 22.23.3, bun
|
|
118
|
+
1.4.1): 10,000 actors of a chart with three `<data>`, one of them a list,
|
|
119
|
+
resident and idle, in bytes per actor.
|
|
120
|
+
|
|
121
|
+
| runtime, datamodel | resident | engine heap | region | after one event: resident | heap |
|
|
122
|
+
|---|---|---|---|---|---|
|
|
123
|
+
| node, native | 1188 | 197 | 287 | 1589 | 281 |
|
|
124
|
+
| node, quickjs | 891 | 10 | 287 | 1363 | 11 |
|
|
125
|
+
| bun, native | 1632 | 255 | 287 | 2602 | 345 |
|
|
126
|
+
| bun, quickjs | 1195 | 24 | 287 | 1602 | 24 |
|
|
127
|
+
|
|
128
|
+
The engine heap is what the JavaScript engine reports after a full
|
|
129
|
+
collection; on quickjs the sandbox's own heap is in "resident" only, and
|
|
130
|
+
it is bounded by `quickjs.memoryLimit`, 1 GiB unless the host sets
|
|
131
|
+
another: about 2.8 KB an idle resident actor, so a host meant to keep
|
|
132
|
+
hundreds of thousands of quickjs actors resident raises it
|
|
133
|
+
([the quickjs sandbox](quickjs.md#the-limits)). The
|
|
134
|
+
rest of resident is mostly the engine's fixed cost, which a larger
|
|
135
|
+
population spreads thinner: at 40,000 actors the native datamodel is
|
|
136
|
+
about 750 bytes resident on Node.js and 970 on Bun. The region here was
|
|
137
|
+
sized up front (`maxActors`). A chart whose scripts declare top-level
|
|
138
|
+
names costs a `vm` context per actor on top: about 143 KB on Node.js and
|
|
139
|
+
60 KB on Bun ([Writing charts](charts.md#scripts)). A hibernated actor
|
|
140
|
+
costs about 60 bytes in the host and its blob in your store.
|
|
141
|
+
|
|
142
|
+
## Work does not grow with the population
|
|
143
|
+
|
|
144
|
+
`tools/scale.mjs` (`mise run scale` in the repository) times every
|
|
145
|
+
operation of the API on a host of N actors and on one of 2N, each in a
|
|
146
|
+
process of its own. It fails when an operation costs more than 1.5 times
|
|
147
|
+
as much at 2N: per call for an operation on one actor, per actor for one
|
|
148
|
+
on the whole population. Most of the actors are hibernated in SQLite and
|
|
149
|
+
one in a hundred runs an invoked service; then the same with every actor
|
|
150
|
+
resident.
|
|
151
|
+
|
|
152
|
+
One run of it (2026-10-17, x86_64 Linux 6.18, Intel Xeon @ 2.10GHz, 4
|
|
153
|
+
CPUs, 16 GiB, a virtual machine; node 22.23.3, bun 1.4.1). Each cell is
|
|
154
|
+
the cost at N, then at 2N, in microseconds, and their ratio.
|
|
155
|
+
|
|
156
|
+
Hibernated: 2,000,000 and 4,000,000 actors, at most 1000 counters
|
|
157
|
+
resident, 20,000 and 40,000 actors each running an invoked service.
|
|
158
|
+
|
|
159
|
+
| operation | unit | node, native | node, quickjs | bun, native | bun, quickjs |
|
|
160
|
+
|---|---|---|---|---|---|
|
|
161
|
+
| populate (spawn and hibernate) | µs per actor | 11.71 → 11.62 (0.99) | 7.16 → 7.36 (1.03) | 8.64 → 8.51 (0.99) | 6.74 → 6.58 (0.98) |
|
|
162
|
+
| spawn | µs per call | 5.47 → 5.43 (0.99) | 2.45 → 2.54 (1.04) | 4.82 → 5.59 (1.16) | 2.92 → 2.70 (0.92) |
|
|
163
|
+
| terminate | µs per call | 0.755 → 0.733 (0.97) | 0.565 → 0.560 (0.99) | 0.925 → 0.889 (0.96) | 0.758 → 0.742 (0.98) |
|
|
164
|
+
| send | µs per call | 4.44 → 4.41 (0.99) | 2.06 → 2.15 (1.04) | 3.71 → 3.61 (0.97) | 2.28 → 2.33 (1.02) |
|
|
165
|
+
| sendMany | µs per event | 4.84 → 4.79 (0.99) | 2.38 → 2.29 (0.96) | 3.50 → 3.40 (0.97) | 2.38 → 2.13 (0.89) |
|
|
166
|
+
| send (hibernated: woken from the store) | µs per call | 34.97 → 30.14 (0.86) | 33.20 → 40.71 (1.23) | 27.13 → 29.38 (1.08) | 34.26 → 35.97 (1.05) |
|
|
167
|
+
| hibernate | µs per call | 5.94 → 5.78 (0.97) | 4.50 → 4.55 (1.01) | 4.22 → 4.20 (0.99) | 4.37 → 4.32 (0.99) |
|
|
168
|
+
| wake | µs per call | 7.07 → 7.34 (1.04) | 3.84 → 4.02 (1.05) | 7.93 → 7.57 (0.95) | 4.85 → 4.75 (0.98) |
|
|
169
|
+
| actorByName | µs per call | 0.532 → 0.507 (0.95) | 0.415 → 0.426 (1.03) | 0.426 → 0.415 (0.98) | 0.304 → 0.300 (0.99) |
|
|
170
|
+
| actorState | µs per call | 4.63 → 4.38 (0.95) | 4.34 → 4.80 (1.11) | 4.13 → 4.37 (1.06) | 3.95 → 4.20 (1.06) |
|
|
171
|
+
| hostStats | µs per call | 19.28 → 19.47 (1.01) | 19.32 → 19.76 (1.02) | 19.45 → 16.84 (0.87) | 14.51 → 14.14 (0.97) |
|
|
172
|
+
| I/O processor round trip | µs per call | 13.30 → 12.54 (0.94) | 8.47 → 8.33 (0.98) | 9.89 → 9.46 (0.96) | 7.88 → 6.48 (0.82) |
|
|
173
|
+
| transport round trip | µs per call | 34.01 → 34.13 (1.00) | 25.85 → 28.06 (1.09) | 27.99 → 31.32 (1.12) | 22.87 → 22.52 (0.98) |
|
|
174
|
+
| delayed send and its timer | µs per call | 7.19 → 7.48 (1.04) | 3.39 → 3.44 (1.02) | 5.93 → 5.97 (1.01) | 3.87 → 3.79 (0.98) |
|
|
175
|
+
| invoked service round trip | µs per call | 14.28 → 15.49 (1.08) | 10.86 → 11.78 (1.08) | 11.54 → 13.32 (1.15) | 9.84 → 10.34 (1.05) |
|
|
176
|
+
| sweep (every actor) | µs per actor | 0.008 → 0.007 (0.97) | 0.007 → 0.007 (0.98) | 0.008 → 0.007 (0.94) | 0.007 → 0.008 (1.03) |
|
|
177
|
+
| migrate (one session) | µs per call | 32.02 → 28.74 (0.90) | 20.00 → 16.20 (0.81) | 24.48 → 24.95 (1.02) | 17.45 → 20.93 (1.20) |
|
|
178
|
+
| snapshot | µs per actor | 0.110 → 0.105 (0.96) | 0.075 → 0.077 (1.04) | 0.090 → 0.080 (0.89) | 0.084 → 0.082 (0.97) |
|
|
179
|
+
| restore (and its first turn) | µs per actor | 0.313 → 0.297 (0.95) | 0.200 → 0.200 (1.00) | 0.236 → 0.234 (0.99) | 0.193 → 0.199 (1.03) |
|
|
180
|
+
| close | µs per actor | 0.081 → 0.102 (1.26) | 0.078 → 0.087 (1.11) | 0.079 → 0.106 (1.35) | 0.087 → 0.104 (1.19) |
|
|
181
|
+
|
|
182
|
+
All resident: 1,000,000 and 2,000,000 actors. Two million resident actors
|
|
183
|
+
take up to 9.2 GB, so four million do not fit on this machine.
|
|
184
|
+
|
|
185
|
+
| operation | unit | node, native | node, quickjs | bun, native | bun, quickjs |
|
|
186
|
+
|---|---|---|---|---|---|
|
|
187
|
+
| populate (spawn, the segment growing) | µs per actor | 6.50 → 6.48 (1.00) | 4.49 → 4.17 (0.93) | 5.39 → 5.84 (1.08) | 4.55 → 4.37 (0.96) |
|
|
188
|
+
| spawn | µs per call | 5.36 → 5.53 (1.03) | 2.59 → 3.18 (1.23) | 4.84 → 4.93 (1.02) | 2.86 → 2.71 (0.95) |
|
|
189
|
+
| send | µs per call | 6.58 → 6.84 (1.04) | 4.35 → 4.88 (1.12) | 7.89 → 7.03 (0.89) | 4.55 → 4.64 (1.02) |
|
|
190
|
+
| hibernate | µs per call | 7.75 → 7.64 (0.99) | 7.68 → 7.42 (0.97) | 6.35 → 6.93 (1.09) | 7.48 → 7.82 (1.04) |
|
|
191
|
+
| wake | µs per call | 8.93 → 8.49 (0.95) | 3.05 → 3.27 (1.07) | 6.94 → 8.36 (1.20) | 3.93 → 3.57 (0.91) |
|
|
192
|
+
| snapshot | µs per actor | 6.62 → 6.46 (0.98) | 5.60 → 6.32 (1.13) | 4.59 → 2.94 (0.64) | 6.12 → 6.51 (1.06) |
|
|
193
|
+
| migrate (a chart, every actor) | µs per actor | 23.38 → 24.60 (1.05) | 12.26 → 14.03 (1.15) | 18.36 → 18.38 (1.00) | 12.01 → 13.27 (1.11) |
|
|
194
|
+
| restore (and its first turn) | µs per actor | 16.41 → 15.45 (0.94) | 4.45 → 5.46 (1.23) | 9.08 → 9.01 (0.99) | 4.75 → 4.90 (1.03) |
|
|
195
|
+
| close | µs per actor | 0.675 → 0.532 (0.79) | 1.78 → 1.47 (0.82) | 0.557 → 0.506 (0.91) | 1.70 → 1.40 (0.82) |
|
|
196
|
+
|
|
197
|
+
Peak resident memory, at N and 2N: hibernated node native 1718 / 3273
|
|
198
|
+
MB; node quickjs 1763 / 3368 MB; bun native 1396 / 2605 MB; bun quickjs
|
|
199
|
+
1358 / 2561 MB; all resident node native 3380 / 6493 MB; node quickjs
|
|
200
|
+
4236 / 8289 MB; bun native 4175 / 8176 MB; bun quickjs 4673 / 9239 MB.
|
|
201
|
+
The full run, with every operation, is in `build/scale-*.json` after
|
|
202
|
+
`mise run scale`.
|