@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,275 @@
|
|
|
1
|
+
# Other systems
|
|
2
|
+
|
|
3
|
+
A host is one **system**, named by its `systemID`. An actor of one system
|
|
4
|
+
can send to an actor of another (another host, in this process or on
|
|
5
|
+
another machine) by its address, `tinyactors://<systemID>/...`. The host
|
|
6
|
+
decides whether an address is its own. A send to another system goes to
|
|
7
|
+
your **transport**, a handler that carries it there; the other side
|
|
8
|
+
gives it to its host with `host.send`. The transport and the wire are
|
|
9
|
+
yours: a socket, a queue, HTTP, a worker's `postMessage`.
|
|
10
|
+
|
|
11
|
+
## Two systems
|
|
12
|
+
|
|
13
|
+
Each send to another system reaches the `transport` handler as a `Send`.
|
|
14
|
+
Its `target` and `origin` are `Address`es, and its `message` is the
|
|
15
|
+
outgoing half, an object of `target`, `event`, `data`, `sendid`,
|
|
16
|
+
`origin` and `traceparent` (`null` for a field the send lacks), which
|
|
17
|
+
the receiving side passes to `host.send(message)` as it is, in this
|
|
18
|
+
process or in another binding's: a Python host takes it too. On a wire,
|
|
19
|
+
`encode` writes the message as it is, its addresses as CBOR's tag 32 (as
|
|
20
|
+
a Python host's `encode` does), and `decode` reads them back as
|
|
21
|
+
`Address`es. (`JSON.stringify` writes an `Address` as its text, so a
|
|
22
|
+
message goes through JSON as it is: see "Addresses" below.)
|
|
23
|
+
|
|
24
|
+
```js
|
|
25
|
+
import { Address, compileCharts, decode, encode, Host } from '@tinyactors/node';
|
|
26
|
+
|
|
27
|
+
const shopChart = `
|
|
28
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
29
|
+
datamodel="ecmascript" name="checkout" initial="paying">
|
|
30
|
+
<state id="paying">
|
|
31
|
+
<onentry>
|
|
32
|
+
<send event="charge" target="tinyactors://bank/@teller"><param name="amount" expr="12"/></send>
|
|
33
|
+
</onentry>
|
|
34
|
+
<transition event="approved" target="done"><log expr="'approved by ' + _event.origin"/></transition>
|
|
35
|
+
</state>
|
|
36
|
+
<final id="done"/>
|
|
37
|
+
</scxml>`;
|
|
38
|
+
const bankChart = `
|
|
39
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
40
|
+
datamodel="ecmascript" name="teller" initial="open">
|
|
41
|
+
<state id="open">
|
|
42
|
+
<transition event="charge">
|
|
43
|
+
<log expr="'charging ' + _event.data.amount + ' for ' + _event.origin"/>
|
|
44
|
+
<send event="approved" targetexpr="_event.origin"/>
|
|
45
|
+
</transition>
|
|
46
|
+
</state>
|
|
47
|
+
</scxml>`;
|
|
48
|
+
|
|
49
|
+
const image = (name, text) => {
|
|
50
|
+
const compiled = compileCharts([{ name, text }]);
|
|
51
|
+
const bytes = compiled.image;
|
|
52
|
+
compiled.close();
|
|
53
|
+
return bytes;
|
|
54
|
+
};
|
|
55
|
+
|
|
56
|
+
// The wire: bytes in a queue, delivered on a later turn of the event loop.
|
|
57
|
+
const hosts = {};
|
|
58
|
+
const wire = (message) => {
|
|
59
|
+
const bytes = encode(message);
|
|
60
|
+
setTimeout(() => {
|
|
61
|
+
const received = decode(bytes);
|
|
62
|
+
hosts[received.target.system].send(received);
|
|
63
|
+
});
|
|
64
|
+
};
|
|
65
|
+
|
|
66
|
+
const log = (host, entry) => console.log(entry.text);
|
|
67
|
+
hosts.shop = new Host({ systemID: 'shop' }, { log, transport: (host, send) => wire(send.message) });
|
|
68
|
+
hosts.bank = new Host({ systemID: 'bank' }, { log, transport: (host, send) => wire(send.message) });
|
|
69
|
+
hosts.shop.addImage(image('checkout.scxml', shopChart));
|
|
70
|
+
hosts.bank.addImage(image('teller.scxml', bankChart));
|
|
71
|
+
|
|
72
|
+
hosts.bank.spawn(hosts.bank.chart('teller'), { name: 'teller' });
|
|
73
|
+
hosts.shop.spawn(hosts.shop.chart('checkout'));
|
|
74
|
+
await new Promise((resolve) => setTimeout(resolve, 50));
|
|
75
|
+
await Promise.all([hosts.shop.idle(), hosts.bank.idle()]);
|
|
76
|
+
hosts.shop.close();
|
|
77
|
+
hosts.bank.close();
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```output
|
|
81
|
+
charging 12 for tinyactors://shop/#_scxml_1
|
|
82
|
+
approved by tinyactors://bank/#_scxml_1
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The receiver answers to `_event.origin`, which is the sender's full
|
|
86
|
+
address, so the answer goes back through the bank's transport.
|
|
87
|
+
|
|
88
|
+
**A send that cannot be delivered** is the transport's to report. While
|
|
89
|
+
the handler runs, `send.fail()` does it. Later, on the sending host,
|
|
90
|
+
`host.fail(sender, sendid)` does, where `sender` is the message's
|
|
91
|
+
`origin` (the actor that sent it, not its target): the sender gets
|
|
92
|
+
`error.communication` with that `sendid`.
|
|
93
|
+
Delivery that worked needs no answer. Without a `transport` handler, each
|
|
94
|
+
send to another system is failed.
|
|
95
|
+
|
|
96
|
+
**An input's target may be an address.** `host.send` takes a session, an
|
|
97
|
+
address string or an `Address`; a local address (`tinyactors://shop/@teller`
|
|
98
|
+
on the host named `shop`) is resolved by the host to its actor. A message's
|
|
99
|
+
`origin` is the sender's address as the other side gave it, and becomes
|
|
100
|
+
the event's `_event.origin`.
|
|
101
|
+
|
|
102
|
+
## Over a socket
|
|
103
|
+
|
|
104
|
+
Across processes, a transport writes each message as a frame on a
|
|
105
|
+
connection. Over TCP, call `socket.setNoDelay(true)` on both ends: the
|
|
106
|
+
frames are small, and an answer is often a frame too, so with Nagle's
|
|
107
|
+
algorithm on (Node.js's default) a second small write waits for the
|
|
108
|
+
peer's delayed acknowledgement, about 40 ms on Linux's loopback, before
|
|
109
|
+
it leaves. (Python's asyncio turns it off by itself.) Here each frame is
|
|
110
|
+
four bytes of length and the message's CBOR:
|
|
111
|
+
|
|
112
|
+
```js
|
|
113
|
+
import { connect, createServer } from 'node:net';
|
|
114
|
+
import { decode, encode, Host } from '@tinyactors/node';
|
|
115
|
+
|
|
116
|
+
/** Calls `receive` with each message the frames on `socket` hold. */
|
|
117
|
+
function frames(socket, receive) {
|
|
118
|
+
let buffered = Buffer.alloc(0);
|
|
119
|
+
socket.on('data', (chunk) => {
|
|
120
|
+
buffered = Buffer.concat([buffered, chunk]);
|
|
121
|
+
while (buffered.length >= 4 && buffered.length >= 4 + buffered.readUInt32BE(0)) {
|
|
122
|
+
const length = buffered.readUInt32BE(0);
|
|
123
|
+
receive(decode(buffered.subarray(4, 4 + length)));
|
|
124
|
+
buffered = buffered.subarray(4 + length);
|
|
125
|
+
}
|
|
126
|
+
});
|
|
127
|
+
}
|
|
128
|
+
const frame = (message) => {
|
|
129
|
+
const body = encode(message);
|
|
130
|
+
const head = Buffer.alloc(4);
|
|
131
|
+
head.writeUInt32BE(body.length);
|
|
132
|
+
return Buffer.concat([head, body]);
|
|
133
|
+
};
|
|
134
|
+
|
|
135
|
+
let toBank;
|
|
136
|
+
let toShop;
|
|
137
|
+
const log = (host, entry) => console.log(entry.text);
|
|
138
|
+
const shop = new Host({ systemID: 'shop' }, { log, transport: (host, send) => toBank.write(frame(send.message)) });
|
|
139
|
+
const bank = new Host({ systemID: 'bank' }, { log, transport: (host, send) => toShop.write(frame(send.message)) });
|
|
140
|
+
shop.addCharts({ 'checkout.scxml': `<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" datamodel="ecmascript" name="checkout">
|
|
141
|
+
<state id="paying">
|
|
142
|
+
<onentry><send event="charge" target="tinyactors://bank/@teller"/></onentry>
|
|
143
|
+
<transition event="approved" target="done"><log expr="'approved'"/></transition>
|
|
144
|
+
</state>
|
|
145
|
+
<final id="done"/>
|
|
146
|
+
</scxml>` });
|
|
147
|
+
bank.addCharts({ 'teller.scxml': `<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" datamodel="ecmascript" name="teller">
|
|
148
|
+
<state id="s"><transition event="charge"><log expr="'charging ' + _event.origin"/><send event="approved" targetexpr="_event.origin"/></transition></state>
|
|
149
|
+
</scxml>` });
|
|
150
|
+
|
|
151
|
+
// The bank listens on a port of the system's choosing; the shop connects.
|
|
152
|
+
const server = createServer((socket) => {
|
|
153
|
+
socket.setNoDelay(true);
|
|
154
|
+
toShop = socket;
|
|
155
|
+
frames(socket, (message) => bank.send(message));
|
|
156
|
+
});
|
|
157
|
+
await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
|
|
158
|
+
toBank = connect(server.address().port, '127.0.0.1');
|
|
159
|
+
toBank.setNoDelay(true);
|
|
160
|
+
frames(toBank, (message) => shop.send(message));
|
|
161
|
+
await new Promise((resolve) => toBank.once('connect', resolve));
|
|
162
|
+
await new Promise((resolve) => setImmediate(resolve)); // the server's side of the connection
|
|
163
|
+
|
|
164
|
+
bank.spawnChart('teller', { name: 'teller' });
|
|
165
|
+
const order = shop.spawnChart('checkout', { name: 'order' });
|
|
166
|
+
while (shop.actorByName('order') !== undefined) await new Promise((resolve) => setTimeout(resolve, 5));
|
|
167
|
+
console.log('order', order, 'ended');
|
|
168
|
+
toBank.end();
|
|
169
|
+
server.close();
|
|
170
|
+
shop.close();
|
|
171
|
+
bank.close();
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
```output
|
|
175
|
+
charging tinyactors://shop/#_scxml_1
|
|
176
|
+
approved
|
|
177
|
+
order 1n ended
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
A frame that cannot be written, or a peer that is gone, is the transport's
|
|
181
|
+
to report: `send.fail()` while its handler runs, `host.fail(origin,
|
|
182
|
+
sendid)` after.
|
|
183
|
+
|
|
184
|
+
## Addresses
|
|
185
|
+
|
|
186
|
+
`new Address(text)` reads an address; its `system`, `session` (a
|
|
187
|
+
`bigint`) and `name` are its parts, `undefined` for a part the text
|
|
188
|
+
lacks. `Address.fromSession(system, session)` and `Address.fromName(system,
|
|
189
|
+
name)` make one, and `toString()` gives the text:
|
|
190
|
+
|
|
191
|
+
```js
|
|
192
|
+
import { Address } from '@tinyactors/node';
|
|
193
|
+
|
|
194
|
+
const bySession = Address.fromSession('shop', 42n);
|
|
195
|
+
const byName = Address.fromName('shop', 'front desk');
|
|
196
|
+
console.log(bySession.text, bySession.system, bySession.session);
|
|
197
|
+
console.log(byName.text, byName.name);
|
|
198
|
+
console.log(new Address('not an address').system);
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
```output
|
|
202
|
+
tinyactors://shop/#_scxml_42 shop 42n
|
|
203
|
+
tinyactors://shop/@front%20desk front desk
|
|
204
|
+
undefined
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
`JSON.stringify` writes an address as its text (`address.toJSON()`), and
|
|
208
|
+
`new Address(text)` reads it back, so a transport's `send.message` goes
|
|
209
|
+
through JSON and into the other side's `host.send` as it is:
|
|
210
|
+
|
|
211
|
+
```js
|
|
212
|
+
import { Address, Host } from '@tinyactors/node';
|
|
213
|
+
|
|
214
|
+
let wire;
|
|
215
|
+
const shop = new Host({ systemID: 'shop' }, { transport: (host, send) => { wire = JSON.stringify(send.message); } });
|
|
216
|
+
const bank = new Host({ systemID: 'bank' }, { log: (host, entry) => console.log(entry.text) });
|
|
217
|
+
shop.addCharts({ 'checkout.scxml': `<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" datamodel="ecmascript" name="checkout">
|
|
218
|
+
<state id="s"><onentry><send event="charge" target="tinyactors://bank/@teller"><param name="amount" expr="12"/></send></onentry></state>
|
|
219
|
+
</scxml>` });
|
|
220
|
+
bank.addCharts({ 'teller.scxml': `<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0" datamodel="ecmascript" name="teller">
|
|
221
|
+
<state id="s"><transition event="charge"><log expr="'charge ' + _event.data.amount + ' from ' + _event.origin"/></transition></state>
|
|
222
|
+
</scxml>` });
|
|
223
|
+
bank.spawnChart('teller', { name: 'teller' });
|
|
224
|
+
shop.spawnChart('checkout');
|
|
225
|
+
await shop.idle();
|
|
226
|
+
|
|
227
|
+
const message = JSON.parse(wire); // its addresses are strings
|
|
228
|
+
console.log(typeof message.target, message.target);
|
|
229
|
+
bank.send(message);
|
|
230
|
+
await bank.idle();
|
|
231
|
+
console.log(new Address(message.origin).session);
|
|
232
|
+
shop.close();
|
|
233
|
+
bank.close();
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
```output
|
|
237
|
+
string tinyactors://bank/@teller
|
|
238
|
+
charge 12 from tinyactors://shop/#_scxml_1
|
|
239
|
+
1n
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Inside event data an address is plain text: values have no address type.
|
|
243
|
+
|
|
244
|
+
## SCXML's BasicHTTP
|
|
245
|
+
|
|
246
|
+
SCXML defines an HTTP processor, BasicHTTP, whose events travel as form
|
|
247
|
+
posts. The package has its codec, for an I/O processor or a server of
|
|
248
|
+
your own: `encodeHTTPPost({ url, event, fields, body })` writes the
|
|
249
|
+
request a send makes, as bytes for a socket, and
|
|
250
|
+
`parseHTTPRequest(bytes)` reads an incoming request's event (its
|
|
251
|
+
`_scxmleventname` field, or `HTTP.<METHOD>`) and its form fields.
|
|
252
|
+
|
|
253
|
+
```js
|
|
254
|
+
import { encodeHTTPPost, parseHTTPRequest } from '@tinyactors/node';
|
|
255
|
+
|
|
256
|
+
const request = encodeHTTPPost({
|
|
257
|
+
url: 'http://localhost:8080/scxml',
|
|
258
|
+
event: 'order.placed',
|
|
259
|
+
fields: [{ name: 'sku', value: 'tea' }, { name: 'qty', value: '2' }],
|
|
260
|
+
});
|
|
261
|
+
console.log(new TextDecoder().decode(request).split('\r\n')[0]);
|
|
262
|
+
|
|
263
|
+
const incoming = parseHTTPRequest(request);
|
|
264
|
+
console.log(incoming.method, incoming.target, incoming.event);
|
|
265
|
+
console.log(incoming.fields.map(({ name, value }) => `${name}=${value}`).join(' '));
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
```output
|
|
269
|
+
POST /scxml HTTP/1.1
|
|
270
|
+
POST /scxml order.placed
|
|
271
|
+
sku=tea qty=2
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
The host does no HTTP itself: sending the bytes and serving the port are
|
|
275
|
+
your program's.
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# The quickjs sandbox
|
|
2
|
+
|
|
3
|
+
A host runs its charts' JavaScript on one of two datamodels. They take
|
|
4
|
+
the same charts, and a host uses one of them for all its charts:
|
|
5
|
+
|
|
6
|
+
- **`native`** (the default) runs chart code in `node:vm` contexts of
|
|
7
|
+
your own engine, V8 under Node.js and JavaScriptCore under Bun. It is
|
|
8
|
+
fast and its values are your engine's, but a `vm` context is not a
|
|
9
|
+
security boundary: a chart can reach the process it runs in.
|
|
10
|
+
- **`quickjs`** runs chart code in QuickJS, a separate JavaScript engine
|
|
11
|
+
compiled into the package, with no I/O at all (no modules, no timers,
|
|
12
|
+
no files, no network) and limits on how long an evaluation runs and how
|
|
13
|
+
much memory the engine takes.
|
|
14
|
+
|
|
15
|
+
Choose quickjs for charts you did not write or do not trust: charts your
|
|
16
|
+
users upload, charts from another team's service, charts generated by a
|
|
17
|
+
program. Chart code on the native datamodel is trusted code.
|
|
18
|
+
|
|
19
|
+
```js
|
|
20
|
+
import { compileCharts, Host } from '@tinyactors/node';
|
|
21
|
+
|
|
22
|
+
const compiled = compileCharts([{ name: 'uploaded.scxml', text: `
|
|
23
|
+
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
|
|
24
|
+
datamodel="ecmascript" name="uploaded" initial="s">
|
|
25
|
+
<state id="s">
|
|
26
|
+
<transition event="spin"><script>while (true) {}</script></transition>
|
|
27
|
+
<transition event="hog"><script>const hoard = []; for (;;) hoard.push(new Array(1000).fill(1));</script></transition>
|
|
28
|
+
<transition event="peek"><log expr="typeof process + ' ' + typeof require + ' ' + typeof setTimeout"/></transition>
|
|
29
|
+
<transition event="error.execution"><log expr="'stopped: error.execution'"/></transition>
|
|
30
|
+
</state>
|
|
31
|
+
</scxml>` }]);
|
|
32
|
+
|
|
33
|
+
const host = new Host({ systemID: 'sandbox' }, {
|
|
34
|
+
datamodel: 'quickjs',
|
|
35
|
+
quickjs: { maxOps: 1000, memoryLimit: 16 * 1024 * 1024 },
|
|
36
|
+
log: (host, entry) => console.log(entry.text),
|
|
37
|
+
});
|
|
38
|
+
host.addImage(compiled.image);
|
|
39
|
+
compiled.close();
|
|
40
|
+
|
|
41
|
+
const actor = host.spawn(host.chart('uploaded'));
|
|
42
|
+
host.send(actor, 'spin');
|
|
43
|
+
host.send(actor, 'hog');
|
|
44
|
+
host.send(actor, 'peek');
|
|
45
|
+
await host.idle();
|
|
46
|
+
host.close();
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
```output
|
|
50
|
+
stopped: error.execution
|
|
51
|
+
stopped: error.execution
|
|
52
|
+
undefined undefined undefined
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
An evaluation that runs too long or asks for too much memory is stopped,
|
|
56
|
+
and the actor gets `error.execution`, as for any expression that throws;
|
|
57
|
+
it goes on with its next event.
|
|
58
|
+
|
|
59
|
+
## The limits
|
|
60
|
+
|
|
61
|
+
`options.quickjs`, with `datamodel: 'quickjs'` only (with the native
|
|
62
|
+
datamodel it is a `TypeError`):
|
|
63
|
+
|
|
64
|
+
| Option | Default | What it bounds |
|
|
65
|
+
|---|---|---|
|
|
66
|
+
| `maxOps` | 1,000,000 | the engine's interrupt checks one evaluation may make before it is stopped |
|
|
67
|
+
| `memoryLimit` | 1 GiB (`2 ** 30`) | bytes for the whole engine, every actor of the host together |
|
|
68
|
+
| `stackLimit` | the engine's | bytes of native stack for JavaScript |
|
|
69
|
+
| `realm` | `'auto'` | `'isolated'` gives every actor a context of its own (below) |
|
|
70
|
+
|
|
71
|
+
The default `memoryLimit` keeps a runaway allocation from taking the
|
|
72
|
+
process: a loop that allocates ends in `error.execution` once the engine
|
|
73
|
+
holds 1 GiB, where without a limit it would grow until the system killed
|
|
74
|
+
the process. It is sized for a host of tens of thousands of resident
|
|
75
|
+
actors (40,000 take about 112 MB of engine heap); a host meant to keep
|
|
76
|
+
more resident sets a larger one, and `Number.MAX_SAFE_INTEGER` is as
|
|
77
|
+
good as none. For untrusted charts set both `maxOps` and a
|
|
78
|
+
`memoryLimit` of your own, as small as their real work allows. `maxOps` is
|
|
79
|
+
not time: it counts the engine's interrupt checks, one for every 10,000
|
|
80
|
+
jumps and calls QuickJS counts down, and how long a check takes depends
|
|
81
|
+
on the code between them. The time a looping evaluation holds
|
|
82
|
+
the host (and every host of the thread, since they share it), measured
|
|
83
|
+
on x86_64 Linux, Intel Xeon @ 2.10GHz, node 22 and bun 1.4.1 alike
|
|
84
|
+
(2026-10-18):
|
|
85
|
+
|
|
86
|
+
| Loop | `maxOps: 200` | `1000` | `10_000` | the default, 1,000,000 |
|
|
87
|
+
|---|---|---|---|---|
|
|
88
|
+
| `while (true) {}` | 6 ms | 27 to 39 ms | 260 ms | 26 s |
|
|
89
|
+
| `while (_event.data.value !== null) {}` | 50 ms | 240 to 250 ms | 2.5 to 2.7 s | about 256 s |
|
|
90
|
+
|
|
91
|
+
So a check costs 26 to 250 microseconds here, and the default lets one
|
|
92
|
+
runaway evaluation stop the process's hosts for minutes. Choose `maxOps`
|
|
93
|
+
by the longest stall your other actors can take: a few hundred (5 to 50
|
|
94
|
+
ms) for a service that answers requests, 1000 (about 25 to 250 ms) for
|
|
95
|
+
background work, and measure your own charts' real work against it,
|
|
96
|
+
since an evaluation that needs more checks than `maxOps` fails every
|
|
97
|
+
time. `maxOps` does not bound memory: a loop that allocates can take
|
|
98
|
+
gigabytes in fewer checks, which `memoryLimit` stops. An evaluation
|
|
99
|
+
stopped by `maxOps` gets `error.execution` with `_event.data.reason`
|
|
100
|
+
`'fuel'`, one stopped by `memoryLimit` `'memory'`.
|
|
101
|
+
|
|
102
|
+
## Realms
|
|
103
|
+
|
|
104
|
+
By default (`realm: 'auto'`) the actors of a chart that declares no
|
|
105
|
+
top-level names share one context, each a small scope object, as on the
|
|
106
|
+
native datamodel; a chart whose scripts declare top-level names gives
|
|
107
|
+
each of its actors a context of its own. The shared context's global object is frozen, so a chart
|
|
108
|
+
cannot add globals, but the builtins (`Math`, `Array.prototype`, ...)
|
|
109
|
+
are shared by every actor of the host: a chart that changes one changes
|
|
110
|
+
it for the others. With `realm: 'isolated'` every actor gets a context of
|
|
111
|
+
its own, at the cost of its memory, so no chart sees another's changes.
|
|
112
|
+
|
|
113
|
+
## What differs from the native datamodel
|
|
114
|
+
|
|
115
|
+
The same chart runs on both, and what a chart can observe is the same
|
|
116
|
+
SCXML. Around the edges:
|
|
117
|
+
|
|
118
|
+
- **Hibernation stores more.** QuickJS writes its own values into a blob:
|
|
119
|
+
`Date`, `Map`, `Set`, typed arrays and object graphs with cycles come
|
|
120
|
+
back, and a class's instance comes back as a plain object. A function
|
|
121
|
+
in a variable still keeps the actor in memory
|
|
122
|
+
([Hibernation](hibernation.md)).
|
|
123
|
+
- **Values cross by encoding.** Event data and spawn params are converted
|
|
124
|
+
to the engine's values and back, through the same value table
|
|
125
|
+
([README](../../README.md#values)). What a chart sends follows
|
|
126
|
+
JavaScript's rules for a value sent elsewhere: a key holding
|
|
127
|
+
`undefined` is dropped and an array's `undefined` is `null`, where the
|
|
128
|
+
native datamodel keeps both.
|
|
129
|
+
- **Its costs differ.** In the repository's measurements most operations
|
|
130
|
+
cost less on quickjs, and an idle actor takes less memory
|
|
131
|
+
([Capacity and memory](capacity.md)).
|
|
132
|
+
|
|
133
|
+
`host.quickjsHeapBytes` is the engine's heap in bytes, every actor's
|
|
134
|
+
together, for an operator watching it against `memoryLimit`; it is
|
|
135
|
+
`undefined` on a native host and once the host is closed.
|