mini_racer_rs 1.3.0 → 1.4.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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 89724c314c6b6e76bcbf4766ee4bca491da165fb3a171a4810b31f67ef5c482b
4
- data.tar.gz: 79363136b12b9284b9b7d7df8799d8228107d89fd3a60e708a153aef0cfd7efc
3
+ metadata.gz: 5fa48ce83f4ac181230edd5df5a490007698ead30ba777abd6d9ab5c0816cdeb
4
+ data.tar.gz: a397d43582531e16d1b0f21b4eeee1026ee261e01af57f62f6019894ded53c0a
5
5
  SHA512:
6
- metadata.gz: a8ef0724b17c87ef891ff91e25673a8a98aba87b8e1f8ecad7cb9824b1e4e7ea39d60d5e5b30d6b435cc56eb06b3bd2a553f47b4f9182febf9cfe7b582a388a7
7
- data.tar.gz: ef0ff9c5648543b82440b5fa12e4a90b3842df6bd3736a1da404ebf1aa1c0ce3e0a9d9a335447db14245e71467406a4fff10c4b0a8372602fcf28a4d79c3ad88
6
+ metadata.gz: 1faa024992d863cd72c866cdc7b23db3608a2c0c1b19f31cb1cc9d9a4cf71ead36ea55507b1de8e2613e341202a027b0eb14fa7cf8e09e0b7f433c6d93b14521
7
+ data.tar.gz: 46134cb7a25b3c4e2aab913d0b6faafd84a7042d61c01ae092b01a4206ef09e8b59056c881788d3e5e03996fc12260f30dc69e7899076c2223cdde03a5613f5d
data/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # Changelog
2
2
 
3
+ ## [1.4.0](https://github.com/andymai/mini_racer_rs/compare/v1.3.0...v1.4.0) (2026-10-23)
4
+
5
+
6
+ ### Features
7
+
8
+ * add MiniRacerRs::Pool for ready contexts replaced off the request path ([#131](https://github.com/andymai/mini_racer_rs/issues/131)) ([9087488](https://github.com/andymai/mini_racer_rs/commit/9087488faacc37d362a28efd6181b972f9ee0d30))
9
+ * add MiniRacerRs.heap_limit so heap exhaustion raises instead of aborting ([#130](https://github.com/andymai/mini_racer_rs/issues/130)) ([f58d1e0](https://github.com/andymai/mini_racer_rs/commit/f58d1e052b2e93b9d750d08b058f769abc81c471))
10
+ * add MiniRacerRs.timeout for per-call time budgets ([#128](https://github.com/andymai/mini_racer_rs/issues/128)) ([da4b529](https://github.com/andymai/mini_racer_rs/commit/da4b529c5ee685df57b3b35b26cbf41518aa667e))
11
+
3
12
  ## [1.3.0](https://github.com/andymai/mini_racer_rs/compare/v1.2.0...v1.3.0) (2026-10-23)
4
13
 
5
14
 
data/COMPATIBILITY.md CHANGED
@@ -88,17 +88,26 @@ What mini_racer_rs adds under `MiniRacerRs`. An internal id is not for callers.
88
88
 
89
89
  | Id | CRuby | TruffleRuby |
90
90
  |---|---|---|
91
+ | `class:MiniRacerRs::HeapLimitError < MiniRacer::V8OutOfMemoryError` | done | n/a |
91
92
  | `class:MiniRacerRs::Pins < Object` | internal | n/a |
93
+ | `class:MiniRacerRs::Pool < Object` | done | n/a |
94
+ | `class:MiniRacerRs::Pool::ShutdownError < MiniRacer::Error` | done | n/a |
92
95
  | `class:MiniRacerRs::Spill < Object` | internal | n/a |
96
+ | `class:MiniRacerRs::TimeoutScope < Object` | internal | n/a |
93
97
  | `const:MiniRacerRs::NATIVE_VERSION` | done | n/a |
94
98
  | `const:MiniRacerRs::V8_VERSION` | done | n/a |
95
99
  | `const:MiniRacerRs::VERSION` | done | done |
96
100
  | `imethod:MiniRacerRs::ForkHook#_fork` | internal | n/a |
97
101
  | `imethod:MiniRacerRs::ForkHook#daemon` | internal | n/a |
102
+ | `imethod:MiniRacerRs::Pool#shutdown` | done | n/a |
103
+ | `imethod:MiniRacerRs::Pool#with` | done | n/a |
98
104
  | `module:MiniRacerRs` | done | done |
99
105
  | `module:MiniRacerRs::ForkHook` | internal | n/a |
100
106
  | `smethod:MiniRacerRs.counters` | done | n/a |
107
+ | `smethod:MiniRacerRs.heap_limit` | done | n/a |
108
+ | `smethod:MiniRacerRs.heap_limit=` | done | n/a |
101
109
  | `smethod:MiniRacerRs.register_source_map` | done | n/a |
110
+ | `smethod:MiniRacerRs.timeout` | done | n/a |
102
111
 
103
112
  ## Deviations
104
113
 
data/Cargo.lock CHANGED
@@ -593,7 +593,7 @@ checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
593
593
 
594
594
  [[package]]
595
595
  name = "mini_racer_engine"
596
- version = "1.3.0"
596
+ version = "1.4.0"
597
597
  dependencies = [
598
598
  "deno_core_icudata",
599
599
  "libc",
@@ -606,7 +606,7 @@ dependencies = [
606
606
 
607
607
  [[package]]
608
608
  name = "mini_racer_rs"
609
- version = "1.3.0"
609
+ version = "1.4.0"
610
610
  dependencies = [
611
611
  "magnus",
612
612
  "mini_racer_engine",
@@ -617,7 +617,7 @@ dependencies = [
617
617
 
618
618
  [[package]]
619
619
  name = "mini_racer_sourcemap"
620
- version = "1.3.0"
620
+ version = "1.4.0"
621
621
  dependencies = [
622
622
  "memchr",
623
623
  "serde",
@@ -627,7 +627,7 @@ dependencies = [
627
627
 
628
628
  [[package]]
629
629
  name = "mini_racer_sync"
630
- version = "1.3.0"
630
+ version = "1.4.0"
631
631
  dependencies = [
632
632
  "loom",
633
633
  "thiserror",
@@ -635,7 +635,7 @@ dependencies = [
635
635
 
636
636
  [[package]]
637
637
  name = "mini_racer_wire"
638
- version = "1.3.0"
638
+ version = "1.4.0"
639
639
  dependencies = [
640
640
  "criterion",
641
641
  "proptest",
data/Cargo.toml CHANGED
@@ -15,7 +15,7 @@ license = "MIT"
15
15
  publish = false
16
16
  repository = "https://github.com/andymai/mini_racer_rs"
17
17
  rust-version = "1.91"
18
- version = "1.3.0"
18
+ version = "1.4.0"
19
19
 
20
20
  [workspace.dependencies]
21
21
  criterion = {version = "0.8", default-features = false, features = ["cargo_bench_support"]}
data/README.md CHANGED
@@ -103,6 +103,9 @@ ExecJS.eval("[1, 2].map(x => x * 2)") # => [2, 4]
103
103
  | `Platform.set_flags!(*flags)` | Sets V8 flags before the first context. |
104
104
  | `MiniRacerRs.register_source_map(bundle, map)` | Registers a source map for a bundle, so `MiniRacer::RuntimeError` backtraces show its original files and positions. CRuby only. |
105
105
  | `MiniRacerRs.counters(context)` | Returns per-context activity counters without dispatching or taking the context lock, including while a script runs and after disposal. CRuby only. |
106
+ | `MiniRacerRs.timeout(milliseconds) { }` | Gives each JavaScript call started in the block a time budget, including calls made by ExecJS and react-rails. CRuby only. |
107
+ | `MiniRacerRs.heap_limit = bytes` | Sets a process-wide V8 heap limit for contexts created afterward, allowing heap exhaustion to raise `MiniRacerRs::HeapLimitError` instead of fatally ending the process. CRuby only. |
108
+ | `MiniRacerRs::Pool.new(size:, max_uses: nil, **options) { }`, `#with`, `#shutdown` | Prebuilds ready contexts, checks them out in arrival order, replaces them on a separate thread, and disposes them at shutdown. CRuby only. |
106
109
 
107
110
  `Context.new` accepts these options:
108
111
 
@@ -123,6 +126,45 @@ Detailed stack capture makes creating and throwing errors more expensive in affe
123
126
 
124
127
  **Counters.** `MiniRacerRs.counters(context)` returns a Hash of symbol-keyed counts for activity since context creation. It reads without a dispatch or the context lock, so another thread can inspect it while a script runs. After `dispose`, it returns the last counts. A forked child that takes a context over continues from the parent's counts. Values are read individually, so an in-flight request can appear in `dispatches` before its result bytes. Keys are `dispatches` (runner requests, including nested callback requests), `callbacks` (Ruby callables run for JavaScript), `bytes_to_js` (sources, requests, callback returns and errors), `bytes_from_js` (results and callback arguments), `js_ns` (runner time excluding callback, await task and fork waits), `gc_count` and `gc_ns` (V8 collections and time), and `terminated` (counts by `stop`, `timeout`, `interrupt`, `max_memory` and `heap_exhausted`). A non-context argument raises `TypeError`. CRuby only. In release builds, timing `js_ns` added about 30 ns to a roughly 0.72 µs call round trip. Counting alone measured within noise.
125
128
 
129
+ **Timeouts per call.** `MiniRacerRs.timeout` gives each `eval`, `eval_await`, `call`, and `call_await` started in the block on the current fiber its own time budget. This bounds calls made through ExecJS and react-rails, whose contexts are created without options.
130
+
131
+ ```ruby
132
+ MiniRacerRs.timeout(200) { React::ServerRendering.render("Page", props, {}) }
133
+ MiniRacerRs.timeout(5_000) { context.eval(bundle) }
134
+ ```
135
+
136
+ The method returns the block's value. Fibers, threads, enumerators, and Async tasks started inside the block inherit its timeout while the block remains open. The effective budget is the smallest of every open scope and the context's own `timeout:`. A scope never loosens that context limit. A tighter scope inside an attached callback can terminate its nested script at any depth while the outer script continues. An overrun raises `MiniRacer::ScriptTerminatedError`, and leftover microtasks receive the same bound. The context remains usable. `milliseconds` is validated like `timeout:`. Passing `0` adds no bound, and omitting the block raises `LocalJumpError`. CRuby only.
137
+
138
+ **Heap limits.** Set `MiniRacerRs.heap_limit` to make V8 heap exhaustion raise into Ruby. Without it, reaching V8's own limit fatally ends the process and takes every in-flight request with it.
139
+
140
+ ```ruby
141
+ MiniRacerRs.heap_limit = 512 * 1024 * 1024
142
+ begin
143
+ React::ServerRendering.render("Page", props, {})
144
+ rescue MiniRacerRs::HeapLimitError
145
+ React::ServerRendering.reset_pool
146
+ end
147
+ ```
148
+
149
+ `bytes` must be 32 MiB to 4 GiB; `nil` clears it. The process-wide setting sizes every context created afterward, including ExecJS and react-rails contexts. The reader returns the configured value. V8 rounds each heap down to its page size, by at most 256 KiB. A hit raises `MiniRacerRs::HeapLimitError`, a subclass of `MiniRacer::V8OutOfMemoryError`, then mini_racer_rs runs a full collection. The context remains usable if its heap fits; otherwise evals, calls, await forms, microtask checkpoints, and pumps keep raising until disposal. `attach`, `heap_stats`, `heap_snapshot`, `low_memory_notification`, and `dispose` remain available. Hits increment `MiniRacerRs.counters(context)[:terminated][:heap_exhausted]`. `max_memory:` remains a per-context post-collection check. The limit is soft: unwinding may use up to three times the old generation. It excludes ArrayBuffer and typed array backing stores, shared large sources, and parser memory. Heap-sizing flags conflict. The limit setter and `Platform.set_flags!` raise `ArgumentError` when the other configured `max_old_space_size`, `max_heap_size`, `max_semi_space_size`, or `predictable_gc_schedule`; context creation is also refused when flags would exceed the limit. Some single allocations can still abort. In 540 processes, 534 hits raised and left the context usable; six aborts were `JSON.parse` results about twice the limit under `--minor-ms`.
150
+
151
+ **Context pools.**
152
+
153
+ ```ruby
154
+ pool = MiniRacerRs::Pool.new(size: 4, max_uses: 5_000) do |context|
155
+ context.eval(bundle, filename: "bundle.js")
156
+ end
157
+ html = pool.with { |context| context.call("render", props) }
158
+ ```
159
+
160
+ `Pool.new` builds `size` contexts (1 to 1024) at once, passes `options` to `MiniRacer::Context.new`, and runs the setup block for initial and replacement contexts. Attach callbacks there. A setup error makes construction raise.
161
+
162
+ `with` returns its block's value. Waiting checkouts are served in arrival order. With a fiber scheduler, a waiting fiber parks without blocking its thread. Nested `with` calls on one fiber reuse its context and do not count as another use.
163
+
164
+ A context is replaced after `max_uses` checkouts, disposal by the block, `MiniRacer::V8OutOfMemoryError`, or `MiniRacer::ContextDisposedError`; either error still reaches the caller. Other errors, including `MiniRacer::ScriptTerminatedError`, keep it.
165
+
166
+ Replacements run on a separate Ruby thread, which disposes the old context before building the new one. The checkout that retires a context does not wait for its replacement to load, and two loaded contexts do not overlap. Failed replacement setup raises from the next checkout. After a fork, the child forgets inherited contexts without disposing them and builds new ones. `shutdown` disposes idle contexts immediately and in-use contexts at check-in. Later checkouts raise `MiniRacerRs::Pool::ShutdownError`. CRuby only.
167
+
126
168
  ## Switching from mini_racer
127
169
 
128
170
  ### What changes
@@ -23,6 +23,25 @@ use crate::{EngineError, InvalidSnapshot, SnapshotBlob, runner};
23
23
  const MIN_RUNNER_STACK_BYTES: usize = 2 << 20;
24
24
  const STACK_HEADROOM_BYTES: usize = 1 << 20;
25
25
 
26
+ /// How a script dispatch runs.
27
+ #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
28
+ pub struct ScriptOptions {
29
+ /// Awaits a promise result, as `eval_await` and `call_await` do.
30
+ pub awaited: bool,
31
+ /// A timeout for this script alone. It only tightens the context's: the
32
+ /// script, and the microtasks it leaves, run under the shorter of the two.
33
+ pub timeout: Option<Duration>,
34
+ }
35
+
36
+ impl ScriptOptions {
37
+ const fn awaited(awaited: bool) -> Self {
38
+ Self {
39
+ awaited,
40
+ timeout: None,
41
+ }
42
+ }
43
+ }
44
+
26
45
  #[derive(Debug, Clone, Copy, PartialEq, Eq)]
27
46
  pub enum WaitOutcome {
28
47
  Ready,
@@ -258,7 +277,7 @@ impl ContextHandle {
258
277
  source: impl Into<JsText>,
259
278
  host: &mut impl Host,
260
279
  ) -> Result<Vec<u8>, EngineError> {
261
- self.evaluate((filename.into(), source.into()), false, host)
280
+ self.evaluate(filename, source, ScriptOptions::awaited(false), host)
262
281
  }
263
282
 
264
283
  /// `eval`, then awaits a promise result: runs microtasks and due tasks
@@ -269,29 +288,33 @@ impl ContextHandle {
269
288
  source: impl Into<JsText>,
270
289
  host: &mut impl Host,
271
290
  ) -> Result<Vec<u8>, EngineError> {
272
- self.evaluate((filename.into(), source.into()), true, host)
291
+ self.evaluate(filename, source, ScriptOptions::awaited(true), host)
273
292
  }
274
293
 
275
- fn evaluate(
294
+ /// `eval` or `eval_await`, as `options` says.
295
+ pub fn evaluate(
276
296
  &self,
277
- (filename, source): (JsText, JsText),
278
- awaited: bool,
297
+ filename: impl Into<JsText>,
298
+ source: impl Into<JsText>,
299
+ options: ScriptOptions,
279
300
  host: &mut impl Host,
280
301
  ) -> Result<Vec<u8>, EngineError> {
302
+ let (filename, source) = (filename.into(), source.into());
281
303
  self.dispatch(
282
304
  DispatchKind::Script,
283
305
  |depth| Request::Eval {
284
306
  filename,
285
307
  source,
286
308
  depth,
287
- awaited,
309
+ awaited: options.awaited,
310
+ timeout: options.timeout,
288
311
  },
289
312
  host,
290
313
  )
291
314
  }
292
315
 
293
316
  pub fn call(&self, request: CallRequest, host: &mut impl Host) -> Result<Vec<u8>, EngineError> {
294
- self.invoke(request, false, host)
317
+ self.invoke(request, ScriptOptions::awaited(false), host)
295
318
  }
296
319
 
297
320
  /// `call`, then awaits a promise result, as `eval_await` does.
@@ -300,13 +323,14 @@ impl ContextHandle {
300
323
  request: CallRequest,
301
324
  host: &mut impl Host,
302
325
  ) -> Result<Vec<u8>, EngineError> {
303
- self.invoke(request, true, host)
326
+ self.invoke(request, ScriptOptions::awaited(true), host)
304
327
  }
305
328
 
306
- fn invoke(
329
+ /// `call` or `call_await`, as `options` says.
330
+ pub fn invoke(
307
331
  &self,
308
332
  request: CallRequest,
309
- awaited: bool,
333
+ options: ScriptOptions,
310
334
  host: &mut impl Host,
311
335
  ) -> Result<Vec<u8>, EngineError> {
312
336
  self.dispatch(
@@ -314,7 +338,8 @@ impl ContextHandle {
314
338
  |depth| Request::Call {
315
339
  request,
316
340
  depth,
317
- awaited,
341
+ awaited: options.awaited,
342
+ timeout: options.timeout,
318
343
  },
319
344
  host,
320
345
  )
@@ -632,7 +657,10 @@ impl ContextHandle {
632
657
  result
633
658
  }
634
659
 
635
- // A script nested in an untimed dispatch gets a timeout of its own.
660
+ // A nested script gets a timeout of its own, the context's tightened by
661
+ // the script's, unless a script around it ends first: in an untimed
662
+ // dispatch always, as with `timeout:`, and otherwise when its own is the
663
+ // shortest.
636
664
  fn nested(
637
665
  &self,
638
666
  block: &Arc<ControlBlock>,
@@ -643,14 +671,14 @@ impl ContextHandle {
643
671
  if block.term.is_disposing() {
644
672
  return Err(EngineError::Disposed);
645
673
  }
646
- let timer = match (kind, block.config.timeout) {
647
- (DispatchKind::Script, Some(timeout)) => {
674
+ let timer = match (kind, block.config.timeout_within(request.timeout())) {
675
+ (DispatchKind::Script, Some(timeout)) if !watchdog::ends_within(block, timeout) => {
648
676
  block.term.time_nested().map(|id| (timeout, id))
649
677
  }
650
678
  _ => None,
651
679
  };
652
680
  if let Some((timeout, id)) = timer
653
- && let Err(error) = watchdog::schedule(timeout, block, id)
681
+ && let Err(error) = watchdog::schedule_nested(timeout, block, id)
654
682
  {
655
683
  block.term.untime_nested(id);
656
684
  return Err(error);
@@ -671,7 +699,7 @@ impl ContextHandle {
671
699
  if let Some((_, id)) = timer
672
700
  && !wait.forked()
673
701
  {
674
- watchdog::clear(block, id);
702
+ watchdog::clear_nested(block, id);
675
703
  block.term.untime_nested(id);
676
704
  }
677
705
  result
@@ -1,4 +1,4 @@
1
- use std::sync::atomic::{AtomicBool, Ordering};
1
+ use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
2
2
  use std::sync::{Arc, Mutex, OnceLock};
3
3
  use std::time::{Duration, Instant};
4
4
 
@@ -92,16 +92,19 @@ pub enum Request {
92
92
  depth: Depth,
93
93
  },
94
94
  /// `awaited`: a promise result is awaited, as `eval_await` does.
95
+ /// `timeout`: the dispatch's own, which only tightens the context's.
95
96
  Eval {
96
97
  filename: JsText,
97
98
  source: JsText,
98
99
  depth: Depth,
99
100
  awaited: bool,
101
+ timeout: Option<Duration>,
100
102
  },
101
103
  Call {
102
104
  request: CallRequest,
103
105
  depth: Depth,
104
106
  awaited: bool,
107
+ timeout: Option<Duration>,
105
108
  },
106
109
  Attach {
107
110
  request: Vec<u8>,
@@ -136,6 +139,14 @@ pub enum Request {
136
139
  }
137
140
 
138
141
  impl Request {
142
+ /// The timeout a script request was given for itself.
143
+ pub const fn timeout(&self) -> Option<Duration> {
144
+ match self {
145
+ Self::Eval { timeout, .. } | Self::Call { timeout, .. } => *timeout,
146
+ _ => None,
147
+ }
148
+ }
149
+
139
150
  /// The bytes a counted dispatch hands JavaScript; `None` for the
140
151
  /// context's own setup and dispose, which no caller asked for.
141
152
  pub const fn payload(&self) -> Option<usize> {
@@ -216,13 +227,57 @@ pub struct ContextConfig {
216
227
  /// Has V8 report each exception that escapes a script, as `mini_racer`'s
217
228
  /// verbose `TryCatch` does: it prints where it happened to stdout.
218
229
  pub verbose_exceptions: bool,
230
+ /// The heap size, in bytes, V8 is given for the isolate. A script that
231
+ /// reaches it ends with `TerminationCause::HeapExhausted` where V8 would
232
+ /// abort the process, as long as what it allocates past the limit fits
233
+ /// in the room the runner lends V8 to end it.
234
+ pub heap_limit: Option<usize>,
235
+ }
236
+
237
+ /// What V8's near-heap-limit callback and the runner share for a context
238
+ /// with a heap limit. The callback touches nothing else but the termination
239
+ /// cell, so V8 may call it from any thread.
240
+ #[derive(Default)]
241
+ pub struct HeapWatch {
242
+ /// V8's limit for the old generation under the heap limit, which a hit
243
+ /// raises and the runner puts back.
244
+ pub old_generation: AtomicUsize,
245
+ /// V8's whole heap size limit under the heap limit, which the runner
246
+ /// checks once it has put the old generation's back.
247
+ pub reserved: AtomicUsize,
248
+ /// V8 called the callback since the runner last recovered.
249
+ pub hit: AtomicBool,
250
+ /// V8 terminated a script since the runner last recovered.
251
+ pub ended: AtomicBool,
252
+ /// The runner is collecting on its own, with no script to terminate.
253
+ pub collecting: AtomicBool,
254
+ /// A collection after a hit left the heap over its limit, so the context
255
+ /// runs no more JavaScript.
256
+ pub poisoned: AtomicBool,
257
+ }
258
+
259
+ impl HeapWatch {
260
+ /// For a forked child taking over the isolate this watched in its parent.
261
+ pub fn inherit(&self, parent: &Self) {
262
+ for (mine, theirs) in [
263
+ (&self.old_generation, &parent.old_generation),
264
+ (&self.reserved, &parent.reserved),
265
+ ] {
266
+ mine.store(theirs.load(Ordering::Relaxed), Ordering::Relaxed);
267
+ }
268
+ self.poisoned
269
+ .store(parent.poisoned.load(Ordering::Relaxed), Ordering::Relaxed);
270
+ }
219
271
  }
220
272
 
221
273
  /// The context's pending timeout and the earliest deadline the watchdog holds
222
274
  /// for it, so the watchdog keeps about one entry per context, not per dispatch.
275
+ /// Nested scripts timed on their own have slots apart, innermost last, so
276
+ /// the deadlines around each outlive it.
223
277
  #[derive(Default)]
224
278
  pub struct Timer {
225
279
  pub due: Option<(Instant, DispatchId)>,
280
+ pub nested: Vec<(Instant, DispatchId)>,
226
281
  pub queued: Option<Instant>,
227
282
  }
228
283
 
@@ -247,6 +302,7 @@ pub struct ControlBlock {
247
302
  // An idle single-threaded runner leaves its isolate here, its only owner
248
303
  // then, so a forked child can hand it to a runner of its own.
249
304
  pub custody: Mutex<Option<v8::SharedIsolate>>,
305
+ pub heap: HeapWatch,
250
306
  pub counters: Counters,
251
307
  }
252
308
 
@@ -267,6 +323,18 @@ impl Drop for ControlBlock {
267
323
  }
268
324
  }
269
325
 
326
+ impl ContextConfig {
327
+ /// The timeout a script runs under: the shorter of the context's and the
328
+ /// one the script was given, so a script's own only tightens it.
329
+ #[must_use]
330
+ pub fn timeout_within(&self, own: Option<Duration>) -> Option<Duration> {
331
+ match (self.timeout, own) {
332
+ (Some(context), Some(own)) => Some(context.min(own)),
333
+ (context, own) => context.or(own),
334
+ }
335
+ }
336
+ }
337
+
270
338
  impl ControlBlock {
271
339
  /// Asks the runner to park for a pending fork, in JavaScript or in a
272
340
  /// snapshot build, wherever V8 next checks for interrupts.
@@ -299,6 +367,7 @@ impl ControlBlock {
299
367
  isolate: OnceLock::new(),
300
368
  building: Mutex::new(None),
301
369
  custody: Mutex::new(None),
370
+ heap: HeapWatch::default(),
302
371
  counters,
303
372
  }
304
373
  }
@@ -8,6 +8,23 @@ pub enum FlagError {
8
8
  TooLong,
9
9
  #[error("platform already initialized")]
10
10
  AlreadyInitialized,
11
+ /// The flag sets a heap size V8 would use in place of the heap limit.
12
+ #[error("--{0} would override the heap limit")]
13
+ OverridesHeapLimit(&'static str),
14
+ }
15
+
16
+ /// Why `platform::set_heap_limit` refused a limit.
17
+ #[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
18
+ pub enum HeapLimitError {
19
+ #[error(
20
+ "heap limit must be from {} to {} bytes",
21
+ crate::process::platform::MIN_HEAP_LIMIT,
22
+ crate::process::platform::MAX_HEAP_LIMIT
23
+ )]
24
+ Range,
25
+ /// A flag already set sizes the heap in its place.
26
+ #[error("the heap limit would be overridden by --{0}")]
27
+ Overridden(&'static str),
11
28
  }
12
29
 
13
30
  /// Why a startup snapshot's blob is refused before V8 reads it, where V8
@@ -67,6 +84,26 @@ impl JsError {
67
84
  message: message.to_owned(),
68
85
  }
69
86
  }
87
+
88
+ /// A script that reached the context's heap limit of `limit` bytes.
89
+ pub(crate) fn heap_limit_reached(limit: usize) -> Self {
90
+ Self {
91
+ kind: JsErrorKind::Terminated(TerminationCause::HeapExhausted),
92
+ message: format!("heap limit of {limit} bytes reached"),
93
+ }
94
+ }
95
+
96
+ /// Any later script in a context whose heap a collection after a hit left
97
+ /// over its limit of `limit` bytes.
98
+ pub(crate) fn heap_limit_exceeded(limit: usize) -> Self {
99
+ Self {
100
+ kind: JsErrorKind::Terminated(TerminationCause::HeapExhausted),
101
+ message: format!(
102
+ "heap still over its limit of {limit} bytes after a collection: \
103
+ this context runs no more JavaScript"
104
+ ),
105
+ }
106
+ }
70
107
  }
71
108
 
72
109
  #[derive(Debug, thiserror::Error)]
@@ -88,6 +125,9 @@ pub enum EngineError {
88
125
  InvalidSnapshot(#[from] InvalidSnapshot),
89
126
  #[error("internal error: {0}")]
90
127
  Internal(String),
128
+ /// V8's flags sized a context's heap past its heap limit.
129
+ #[error("the heap limit is overridden by a V8 flag")]
130
+ HeapLimitOverridden,
91
131
  }
92
132
 
93
133
  fn ebusy() -> String {
@@ -17,11 +17,12 @@ mod spin;
17
17
  mod sys;
18
18
  mod text;
19
19
 
20
- pub use context::{ContextHandle, Host, Unparker, WaitHandle, WaitOutcome};
20
+ pub use context::{ContextHandle, Host, ScriptOptions, Unparker, WaitHandle, WaitOutcome};
21
21
  pub use control::{CallRequest, CallbackReply, ContextConfig, JsText};
22
22
  pub use counters::{Counts, Terminations};
23
23
  pub use error::{
24
- EngineError, FlagError, InvalidSnapshot, JsError, JsErrorKind, SourceMapError, TerminationCause,
24
+ EngineError, FlagError, HeapLimitError, InvalidSnapshot, JsError, JsErrorKind, SourceMapError,
25
+ TerminationCause,
25
26
  };
26
27
  pub use snapshot::{SnapshotBlob, WeakSnapshotBlob};
27
28
  pub use text::{Decoded, Transcoder};