quickjs 0.20.0 → 0.21.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 605a1b267393aa0e4e3c722d1d53859eb28a4b90ed439c84d06342badb264233
-  data.tar.gz: a64971b38fa7cdf083ff0437c29fa4bdb72805120991ed353caa4c1630ae53df
+  metadata.gz: 3b261a41c198fb0494661ceee781db96bdb3a03614dfd4e5cb4361e0346979df
+  data.tar.gz: d22a2d8524c572dc6ba0d58a25ef2efe1474bdfed6f623b4bfe54564f6ec4fd1
 SHA512:
-  metadata.gz: 9de98af61a9071db5755e33edb9193ae755f89b77b04960c705e54832aa078b2dd384cc3f6ed3c2b9f87f7d57114152955e17ddeb29624b016af61c2f72e2bf3
-  data.tar.gz: 3563103113d14a14120674b1d53d330778d22494786401481af9205eae91b9d5a780554861b5c054180cef9460cbbae0a77c039602d6c35c8752e08e4dc44c88
+  metadata.gz: 277439c6f9183e3d7cd72d4a468384adac3ef3c5a33df9d3db6ceb86139d0dae2d2e75591cc4240159d8a3bbd04db33cb7fa077a03dd70c6a38a8227078723c1
+  data.tar.gz: bbb5bb21051db7337cbb14ff449bcc649b48c783fa947edb6edd0ec2cb643b8cc925259dbe771ee4d9b7ba31fb98c889ce1a289b5e9cbdf36640678697af3c03

data/README.md

@@ -358,6 +358,8 @@ vm.eval_code('1 + 1') # raises Quickjs::RuntimeError "VM has been disposed"
 Thread.new { vm.dispose! }
 ```
 
+Disposing a VM that is mid-evaluation on another thread would free the runtime out from under the running JS, so `dispose!` raises `ThreadError` while JS is executing on the VM (`eval_code`, `call`, `import`, `drain_jobs!`, `Runnable#run`) — dispose after the call returns.
+
 #### `Quickjs::VM#drain_jobs!`: Run pending JS jobs to completion
 
 QuickJS does not automatically drain the job queue at the end of a synchronous `eval_code` / `call`. Continuations scheduled via `Promise.resolve().then(...)` or `JS_EnqueueJob` stay pending until something explicitly runs them — `await` inside JS does, but a sync return path does not.
@@ -374,6 +376,17 @@ vm.eval_code('x')   #=> 1
 
 Useful when porting JS that assumed V8's implicit-drain semantics — V8 (and therefore [mini_racer](https://github.com/rubyjs/mini_racer)) flushes pending jobs at every eval boundary, so `eval_code` already sees `.then()` continuations run by the time it returns. QuickJS doesn't. Patterns like `Promise.resolve().then(() => { ... })` and Stimulus/Hotwire callbacks that assume "the next microtask tick" silently fall through unless you call `drain_jobs!` explicitly.
 
+#### Threads and parallelism
+
+`eval_code` releases Ruby's GVL while JS runs, as long as no JS→Ruby bridge is registered on the VM (no `define_function`, `module_loader`, `on_unhandled_rejection`, and none of `FEATURE_TIMEOUT` / `POLYFILL_FILE` / `POLYFILL_CRYPTO` — `console.log` is fine). Separate VMs on separate Ruby threads then evaluate genuinely in parallel on multi-core hosts; when a bridge is registered, the GVL stays held for that VM's evals and they serialize as usual.
+
+The rules for sharing VMs across threads:
+
+- **One VM, one thread at a time.** A `Quickjs::VM` is not safe for concurrent use from multiple threads — QuickJS contexts have no internal locking. Handing a VM off between threads (e.g. constructing it on a warmer thread and using it on another) is fine as long as only one thread touches it at a time.
+- **Create the VM on the thread that evaluates with it** when possible: QuickJS records the creating thread's stack bounds, and evaluating from a thread whose stack sits below them can trip a false stack-overflow error.
+- **Register bridges before evaluating.** `define_function`, `module_loader=`, and `on_unhandled_rejection` raise `ThreadError` while a GVL-released eval is in flight (e.g. from inside an `on_log` listener) — the running JS was allowed to release the GVL precisely because no bridge existed when it started.
+- **`MODULE_OS` caveat:** `os.signal` and `os.ttySetRaw` mutate process-wide state inside quickjs-libc, so don't call those two from VMs running concurrently on different threads. The common APIs (`os.sleep`, `os.setTimeout`, file I/O) only touch per-runtime state and are safe.
+
 ### Value Conversion
 
 | JavaScript | | Ruby | Note |

data/ext/quickjsrb/quickjsrb.c

@@ -25,6 +25,8 @@ const char *native_errors[] = {
 const int num_native_errors = sizeof(native_errors) / sizeof(native_errors[0]);
 
 static int dispatch_log(VMData *data, const char *severity, VALUE r_row);
+static void check_disposed(VMData *data);
+static void run_gvl_release_region(VMData *data, void *(*job_run)(void *), void *job, JSValue *j_result, void *owned_buf0, void *owned_buf1);
 
 JSValue to_js_value(JSContext *ctx, VALUE r_value);
 VALUE to_rb_value(JSContext *ctx, JSValue j_val);
@@ -871,7 +873,10 @@ static JSValue js_quickjsrb_set_timeout(JSContext *ctx, JSValueConst _this, int
   return JS_UNDEFINED;
 }
 
-static VALUE r_try_call_listener(VALUE r_args)
+// The single way the on_log listener is invoked. Called under rb_protect by
+// dispatch_log (uncaught-error headline rows) and unprotected — the caller's
+// outer rb_protect covers it — by r_build_and_dispatch_log (console rows).
+static VALUE r_call_log_listener(VALUE r_args)
 {
   VALUE r_listener = RARRAY_AREF(r_args, 0);
   VALUE r_log = RARRAY_AREF(r_args, 1);
@@ -886,7 +891,7 @@ static int dispatch_log(VMData *data, const char *severity, VALUE r_row)
   VALUE r_log = r_log_new(severity, r_row);
   VALUE r_args = rb_ary_new3(2, data->log_listener, r_log);
   int error;
-  rb_protect(r_try_call_listener, r_args, &error);
+  rb_protect(r_call_log_listener, r_args, &error);
   return error;
 }
 
@@ -902,13 +907,30 @@ static VALUE vm_m_on_log(VALUE r_self)
   return Qnil;
 }
 
-static JSValue js_quickjsrb_log(JSContext *ctx, JSValueConst _this, int argc, JSValueConst *argv, const char *severity)
+struct quickjsrb_log_call
 {
+  JSContext *ctx;
+  int argc;
+  JSValueConst *argv;
+  const char *severity;
+  JSValue result;
+};
+
+// Runs under rb_protect (see js_quickjsrb_log_inner) so no Ruby raise —
+// to_rb_value on an unconvertible argument (e.g. a Promise nested inside an
+// array), allocation failure, or the user's on_log listener — can longjmp
+// through QuickJS's interpreter frames, or, on the pure path (where this
+// runs inside rb_thread_call_with_gvl), across the rb_thread_call_without_gvl
+// region — which would leak its buffers and leave gvl_released_js stuck.
+static VALUE r_build_and_dispatch_log(VALUE r_call)
+{
+  struct quickjsrb_log_call *call = (struct quickjsrb_log_call *)r_call;
+  JSContext *ctx = call->ctx;
   VMData *data = JS_GetContextOpaque(ctx);
   VALUE r_row = rb_ary_new();
-  for (int i = 0; i < argc; i++)
+  for (int i = 0; i < call->argc; i++)
   {
-    JSValue j_logged = JS_DupValue(ctx, argv[i]);
+    JSValueConst j_logged = call->argv[i];
     VALUE r_raw;
     if (JS_VALUE_GET_NORM_TAG(j_logged) == JS_TAG_OBJECT && JS_PromiseState(ctx, j_logged) != -1)
     {
@@ -946,12 +968,22 @@ static JSValue js_quickjsrb_log(JSContext *ctx, JSValueConst _this, int argc, JS
     const char *body = JS_ToCString(ctx, j_logged);
     VALUE r_c = rb_str_new2(body);
     JS_FreeCString(ctx, body);
-    JS_FreeValue(ctx, j_logged);
 
     rb_ary_push(r_row, r_log_body_new(r_raw, r_c));
   }
 
-  int error = dispatch_log(data, severity, r_row);
+  r_call_log_listener(rb_ary_new3(2, data->log_listener, r_log_new(call->severity, r_row)));
+  return Qnil;
+}
+
+// Requires the GVL. A caught Ruby exception (from row building or the
+// listener) becomes a JS throw, so it unwinds through QuickJS as a regular
+// JS exception instead of a cross-boundary longjmp.
+static JSValue js_quickjsrb_log_inner(JSContext *ctx, int argc, JSValueConst *argv, const char *severity)
+{
+  struct quickjsrb_log_call call = {ctx, argc, argv, severity, JS_UNDEFINED};
+  int error;
+  rb_protect(r_build_and_dispatch_log, (VALUE)&call, &error);
   if (error)
   {
     VALUE r_error = rb_errinfo();
@@ -962,37 +994,102 @@ static JSValue js_quickjsrb_log(JSContext *ctx, JSValueConst _this, int argc, JS
   return JS_UNDEFINED;
 }
 
+static void *quickjsrb_log_with_gvl(void *p)
+{
+  struct quickjsrb_log_call *c = p;
+  VMData *data = JS_GetContextOpaque(c->ctx);
+  // The GVL is held for the duration of this callback. Clear the flag so
+  // JS re-entered from the on_log listener (a bridged eval_code, call,
+  // eval_bytecode, ...) routes its console.log inline — with the flag
+  // still true it would call rb_thread_call_with_gvl while already holding
+  // the GVL, which MRI aborts on. A plain save/restore pair suffices: the
+  // listener can't longjmp out (js_quickjsrb_log_inner rb_protects
+  // everything it runs).
+  bool prev = data->gvl_released_js;
+  data->gvl_released_js = false;
+  c->result = js_quickjsrb_log_inner(c->ctx, c->argc, c->argv, c->severity);
+  data->gvl_released_js = prev;
+  return NULL;
+}
+
+// Dispatcher: when the caller released the GVL around JS_Eval (see
+// vm_m_evalCode pure-path), Ruby APIs can't be touched directly. Re-acquire
+// the GVL via rb_thread_call_with_gvl before running the row-building body.
+// When the GVL is already held, call the body inline to avoid the re-acquire
+// overhead.
+static JSValue js_quickjsrb_log(JSContext *ctx, int argc, JSValueConst *argv, const char *severity)
+{
+  VMData *data = JS_GetContextOpaque(ctx);
+  // With no listener registered the built row would be discarded, so skip
+  // the whole pipeline — most importantly the GVL re-acquire below, which
+  // would otherwise turn every console.log of a log-heavy pure-path script
+  // into a full GVL round-trip for nothing. This deliberately also skips
+  // argument stringification (getters / toString / to_rb_value) and its
+  // side effects or failures: console.log with no listener is a true
+  // no-op. Reading a VALUE field for a Qnil comparison is a plain aligned
+  // pointer-sized read, safe without the GVL; a racing on_log registration
+  // (which itself requires the GVL) at worst drops this one row.
+  if (NIL_P(data->log_listener))
+    return JS_UNDEFINED;
+  if (data->gvl_released_js)
+  {
+    struct quickjsrb_log_call c = {ctx, argc, argv, severity, JS_UNDEFINED};
+    rb_thread_call_with_gvl(quickjsrb_log_with_gvl, &c);
+    return c.result;
+  }
+  return js_quickjsrb_log_inner(ctx, argc, argv, severity);
+}
+
 static JSValue js_console_info(JSContext *ctx, JSValueConst this, int argc, JSValueConst *argv)
 {
-  return js_quickjsrb_log(ctx, this, argc, argv, "info");
+  return js_quickjsrb_log(ctx, argc, argv, "info");
 }
 
 static JSValue js_console_verbose(JSContext *ctx, JSValueConst this, int argc, JSValueConst *argv)
 {
-  return js_quickjsrb_log(ctx, this, argc, argv, "verbose");
+  return js_quickjsrb_log(ctx, argc, argv, "verbose");
 }
 
 static JSValue js_console_warn(JSContext *ctx, JSValueConst this, int argc, JSValueConst *argv)
 {
-  return js_quickjsrb_log(ctx, this, argc, argv, "warning");
+  return js_quickjsrb_log(ctx, argc, argv, "warning");
 }
 
 static JSValue js_console_error(JSContext *ctx, JSValueConst this, int argc, JSValueConst *argv)
 {
-  return js_quickjsrb_log(ctx, this, argc, argv, "error");
+  return js_quickjsrb_log(ctx, argc, argv, "error");
 }
 
 // Run polyfill bytecode load + eval without the GVL so a background
 // warmer thread can populate a VM pool in parallel with the main thread
 // on multi-core hosts.
 //
-// Releasing the GVL here is only safe because the bundled polyfills are
-// pure JS (file / encoding / url) and no Ruby-bridged callbacks have
-// been registered on globalThis yet at this point in vm_m_initialize.
-// If the order ever changes — e.g. moving define_function setup ahead of
-// the polyfill loads — the polyfill bytecode could re-enter Ruby without
-// the GVL held. Keep host callback registration after polyfill loading.
-struct polyfill_load_args
+// Two call sites use this helper:
+//
+//   1. vm_m_initialize — pre-built bytecode (file / encoding / url) embedded
+//      as static C constants. setTimeout (FEATURE_TIMEOUT) and the File
+//      proxy (POLYFILL_FILE, registered ahead of the encoding/url loads)
+//      can already be live here, so the release is safe not because
+//      nothing is registered, but because a load never runs bridge code:
+//      js_quickjsrb_set_timeout only enqueues (pure C; the Ruby-calling
+//      js_delay_and_eval_job runs later, under a GVL-held drain/await), a
+//      load never drains the job queue, and the bundled polyfill
+//      top-levels (built from polyfills/src in this repo) don't call the
+//      File proxy. That audit is the invariant to preserve when rebuilding
+//      bundles or reordering vm_m_initialize.
+//
+//   2. vm_m_loadPolyfillBytecode — bytecode from a Ruby String, copied to a
+//      malloc'd buffer first so the buffer survives a GC compact. This
+//      bytecode is arbitrary (registered by companion gems), so no audit
+//      applies: the caller gates the release on can_eval_gvl_free() to
+//      bail whenever a direct-rb_funcall bridge (File proxy, crypto, …)
+//      is installed; console.log is covered by js_quickjsrb_log's
+//      gvl_released_js re-acquire either way.
+//
+// load_polyfill_bytecode delegates to the shared GVL-release region (see
+// run_gvl_release_region) so every caller inherits the re-acquire safety,
+// the dispose! handshake, and interrupt-proof cleanup automatically.
+struct bytecode_load_job
 {
   JSContext *ctx;
   const uint8_t *buf;
@@ -1000,19 +1097,33 @@ struct polyfill_load_args
   JSValue result;
 };
 
-static void *polyfill_load_no_gvl(void *p)
+// Shared bytecode read + eval core — pure C over JSValues, MUST NOT touch
+// the Ruby VM (the polyfill release path runs it without the GVL; the
+// GVL-held call sites invoke it directly).
+static void *bytecode_load_job_run(void *p)
 {
-  struct polyfill_load_args *args = p;
-  JSValue obj = JS_ReadObject(args->ctx, args->buf, args->buf_len, JS_READ_OBJ_BYTECODE);
-  args->result = JS_EvalFunction(args->ctx, obj); // frees obj
+  struct bytecode_load_job *job = p;
+  JSValue obj = JS_ReadObject(job->ctx, job->buf, job->buf_len, JS_READ_OBJ_BYTECODE);
+  // JS_EvalFunction on a JS_EXCEPTION input replaces the pending exception
+  // with a generic "bytecode function expected" TypeError, losing the actual
+  // deserialization diagnostic from JS_ReadObject. Short-circuit instead.
+  if (JS_IsException(obj))
+  {
+    job->result = obj;
+    return NULL;
+  }
+  job->result = JS_EvalFunction(job->ctx, obj); // frees obj
   return NULL;
 }
 
-static JSValue load_polyfill_bytecode(JSContext *ctx, const uint8_t *buf, size_t buf_len)
+// take_ownership: true when buf is malloc'd storage that the release region
+// should free on every exit path (including async-interrupt unwinds); false
+// when buf points at static bytecode.
+static JSValue load_polyfill_bytecode(VMData *data, const uint8_t *buf, size_t buf_len, bool take_ownership)
 {
-  struct polyfill_load_args args = {ctx, buf, buf_len, JS_UNDEFINED};
-  rb_thread_call_without_gvl(polyfill_load_no_gvl, &args, NULL, NULL);
-  return args.result;
+  struct bytecode_load_job job = {data->context, buf, buf_len, JS_UNDEFINED};
+  run_gvl_release_region(data, bytecode_load_job_run, &job, &job.result, take_ownership ? (uint8_t *)buf : NULL, NULL);
+  return job.result;
 }
 
 static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
@@ -1070,14 +1181,18 @@ static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
   }
   else if (RTEST(rb_funcall(r_features, rb_intern("include?"), 1, QUICKJSRB_SYM(featureTimeoutId))))
   {
+    // setTimeout itself only enqueues, but js_delay_and_eval_job (the
+    // enqueued callback) calls rb_funcall and rb_thread_wait_for
+    // synchronously while js_std_await drains the queue — so this counts
+    // as a Ruby bridge and eval must keep the GVL.
     JS_SetPropertyStr(
         data->context, j_global, "setTimeout",
-        JS_NewCFunction(data->context, js_quickjsrb_set_timeout, "setTimeout", 2));
+        quickjsrb_new_ruby_bridge(data->context, js_quickjsrb_set_timeout, "setTimeout", 2));
   }
 
   if (RTEST(rb_funcall(r_features, rb_intern("include?"), 1, QUICKJSRB_SYM(featurePolyfillFileId))))
   {
-    JSValue j_polyfillFileResult = load_polyfill_bytecode(data->context, &qjsc_polyfill_file_min, qjsc_polyfill_file_min_size);
+    JSValue j_polyfillFileResult = load_polyfill_bytecode(data, &qjsc_polyfill_file_min, qjsc_polyfill_file_min_size, false);
     JS_FreeValue(data->context, j_polyfillFileResult);
 
     quickjsrb_init_file_proxy(data);
@@ -1085,13 +1200,13 @@ static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
 
   if (RTEST(rb_funcall(r_features, rb_intern("include?"), 1, QUICKJSRB_SYM(featurePolyfillEncodingId))))
   {
-    JSValue j_polyfillEncodingResult = load_polyfill_bytecode(data->context, &qjsc_polyfill_encoding_min, qjsc_polyfill_encoding_min_size);
+    JSValue j_polyfillEncodingResult = load_polyfill_bytecode(data, &qjsc_polyfill_encoding_min, qjsc_polyfill_encoding_min_size, false);
     JS_FreeValue(data->context, j_polyfillEncodingResult);
   }
 
   if (RTEST(rb_funcall(r_features, rb_intern("include?"), 1, QUICKJSRB_SYM(featurePolyfillUrlId))))
   {
-    JSValue j_polyfillUrlResult = load_polyfill_bytecode(data->context, &qjsc_polyfill_url_min, qjsc_polyfill_url_min_size);
+    JSValue j_polyfillUrlResult = load_polyfill_bytecode(data, &qjsc_polyfill_url_min, qjsc_polyfill_url_min_size, false);
     JS_FreeValue(data->context, j_polyfillUrlResult);
   }
 
@@ -1100,10 +1215,11 @@ static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
     quickjsrb_init_crypto(data->context, j_global);
   }
 
-  // Host callbacks (console, setTimeout, Ruby-bridged functions) are
-  // registered below this point — after all polyfill loading above.
-  // load_polyfill_bytecode releases the GVL; any code moved above this
-  // line that touches Ruby APIs must re-acquire it first.
+  // console and the remaining host callbacks are registered below this
+  // point. setTimeout and the File proxy above predate the GVL-released
+  // polyfill loads only under the audit described at
+  // load_polyfill_bytecode — re-read it before reordering this function
+  // or registering anything else above the loads.
   JSValue j_console = JS_NewObject(data->context);
   JS_SetPropertyStr(
       data->context, j_console, "log",
@@ -1194,6 +1310,266 @@ static void arm_eval_timer(VMData *data)
   JS_SetInterruptHandler(JS_GetRuntime(data->context), interrupt_handler, data->eval_time);
 }
 
+// Pure-path predicate: true when no JS→Ruby bridge can fire during eval
+// other than console.log (which is handled by js_quickjsrb_log's
+// gvl_released_js re-acquire). When true, eval can safely run with the
+// GVL released so other Ruby threads make progress on different cores.
+// C-function bridges registered via quickjsrb_new_ruby_bridge (crypto.*,
+// File proxy, setTimeout) call rb_funcall directly — those would need to
+// learn the gvl_released_js pattern before they can run under a released
+// GVL, so we hold the GVL when any of them is installed.
+//
+// :feature_std / :feature_os intentionally pass: quickjs-libc never calls
+// into Ruby, and its state is almost entirely per-runtime (JSThreadState).
+// The exceptions are two file-scope globals reachable from niche APIs —
+// `oldtty` (os.ttySetRaw) and `os_pending_signals` (os.signal) — which can
+// race when multiple VMs run those APIs concurrently. Gating the whole
+// feature would re-serialize os.sleep / os.setTimeout across threads, so
+// the constraint is documented in the README instead.
+static bool can_eval_gvl_free(VMData *data)
+{
+  return RHASH_SIZE(data->defined_functions) == 0
+      && NIL_P(data->module_loader)
+      && NIL_P(data->on_unhandled_rejection)
+      && !data->has_native_ruby_bridge;
+}
+
+struct eval_code_job
+{
+  JSContext *ctx;
+  const char *code;
+  size_t code_len;
+  const char *filename;
+  bool async_mode;
+  JSValue result;
+};
+
+// Shared eval core: JS_Eval (+ js_std_await and the {value, done} unwrap for
+// async). Pure C over JSValues — MUST NOT touch the Ruby VM, because the
+// pure path runs it with the GVL released (see js_quickjsrb_log's dispatcher
+// for how console.log re-acquires). The bridged path calls it directly with
+// the GVL held; both paths share this body so a future fix to the eval
+// sequence can't silently diverge between them.
+static void *eval_code_job_run(void *p)
+{
+  struct eval_code_job *job = p;
+  int eval_flags = job->async_mode ? (JS_EVAL_TYPE_GLOBAL | JS_EVAL_FLAG_ASYNC) : JS_EVAL_TYPE_GLOBAL;
+  JSValue j_codeResult = JS_Eval(job->ctx, job->code, job->code_len, job->filename, eval_flags);
+  if (job->async_mode)
+  {
+    JSValue j_awaitedResult = js_std_await(job->ctx, j_codeResult); // frees j_codeResult
+    job->result = JS_GetPropertyStr(job->ctx, j_awaitedResult, "value");
+    JS_FreeValue(job->ctx, j_awaitedResult);
+  }
+  else
+  {
+    job->result = j_codeResult;
+  }
+  return NULL;
+}
+
+// A GVL-release region — the one place that owns the handshake required to
+// run a pure-C QuickJS job with the GVL released: the save/restore of
+// gvl_released_js (restore, not clear, so a region nested through an
+// on_log listener doesn't flip the outer region's console.log back to the
+// inline path), the evals_in_flight increment that makes dispose! refuse,
+// the stale-dispose re-check, and an rb_ensure cleanup that keeps all of
+// it balanced when an async interrupt (Thread#raise / Thread#kill /
+// Timeout) fires in rb_thread_call_without_gvl's GVL-re-acquire epilogue.
+struct gvl_release_region
+{
+  VMData *data;
+  void *(*job_run)(void *); // pure C over JSValues — must not touch Ruby
+  void *job;
+  // Where the job stores its JSValue result; the cleanup frees it when an
+  // interrupt lands inside the region (no-op for JS_UNDEFINED).
+  JSValue *j_result;
+  // malloc'd inputs owned by the region so they survive an interrupt
+  // unwinding past the caller's own frees; NULL slots are fine.
+  void *owned_bufs[2];
+  bool prev_gvl_released;
+  bool completed;
+};
+
+static VALUE gvl_release_region_run(VALUE p)
+{
+  struct gvl_release_region *region = (struct gvl_release_region *)p;
+  rb_thread_call_without_gvl(region->job_run, region->job, NULL, NULL);
+  region->completed = true;
+  return Qnil;
+}
+
+static VALUE gvl_release_region_cleanup(VALUE p)
+{
+  struct gvl_release_region *region = (struct gvl_release_region *)p;
+  VMData *data = region->data;
+  data->gvl_released_js = region->prev_gvl_released;
+  data->evals_in_flight--;
+  data->gvl_release_regions--;
+  free(region->owned_bufs[0]);
+  free(region->owned_bufs[1]);
+  // Frees the result when the interrupt landed after the job ran but
+  // before the run function marked completion. An interrupt during the
+  // caller's subsequent Ruby conversion can still leak the result — the
+  // same (accepted) exposure every GVL-held path has always had.
+  if (!region->completed)
+    JS_FreeValue(data->context, *region->j_result);
+  return Qnil;
+}
+
+// Run job_run(job) with the GVL released. owned_buf0/1 are malloc'd
+// buffers backing the job's inputs; ownership transfers to the region,
+// which frees them on every exit path — including the disposed bail-out
+// below and async-interrupt unwinds. The caller's check_disposed may be
+// stale by now (argument parsing can yield the GVL to a concurrent
+// dispose!), so re-check here: nothing between this check and the release
+// yields, and dispose! refuses while evals_in_flight > 0, so the two
+// sides can't miss each other.
+static void run_gvl_release_region(VMData *data, void *(*job_run)(void *), void *job, JSValue *j_result, void *owned_buf0, void *owned_buf1)
+{
+  if (data->disposed)
+  {
+    free(owned_buf0);
+    free(owned_buf1);
+    check_disposed(data); // raises
+  }
+
+  struct gvl_release_region region = {
+      .data = data,
+      .job_run = job_run,
+      .job = job,
+      .j_result = j_result,
+      .owned_bufs = {owned_buf0, owned_buf1},
+      .prev_gvl_released = data->gvl_released_js,
+      .completed = false,
+  };
+
+  data->evals_in_flight++;
+  data->gvl_release_regions++;
+  data->gvl_released_js = true;
+  rb_ensure(gvl_release_region_run, (VALUE)&region, gvl_release_region_cleanup, (VALUE)&region);
+}
+
+// Installing a JS→Ruby bridge (define_function, module_loader=,
+// on_unhandled_rejection) invalidates the can_eval_gvl_free decision an
+// in-flight GVL-released eval was started under: after e.g. an on_log
+// listener returns, the still-running JS could reach the new bridge and
+// call Ruby APIs without holding the GVL. Refuse loudly — register
+// bridges before evaluating. Registration during GVL-held evals stays
+// allowed, as it always was: gvl_release_regions only counts released
+// regions.
+static void check_no_gvl_release_in_flight(VMData *data)
+{
+  if (data->gvl_release_regions > 0)
+    rb_raise(rb_eThreadError, "cannot install a JS-to-Ruby bridge on a Quickjs::VM while it is evaluating with the GVL released");
+}
+
+static VALUE evals_in_flight_release(VALUE p)
+{
+  ((VMData *)p)->evals_in_flight--;
+  return Qnil;
+}
+
+// Counterpart of run_gvl_release_region for the GVL-held entry points:
+// bridge callbacks (define_function procs, setTimeout's rb_thread_wait_for,
+// on_log listeners) yield the GVL mid-execution, so every JS execution must
+// elevate evals_in_flight for dispose! to refuse — and the decrement must
+// survive every raise exit: JS exceptions, type errors, conversion
+// failures, and async interrupts (Thread#raise / Timeout) delivered inside
+// a bridge callback. A stranded counter would make dispose! refuse forever,
+// so the check + increment + rb_ensure discipline lives here structurally
+// rather than being repeated at each call site. Entry points may have run
+// argument parsing that yields the GVL since their own entry check, hence
+// the disposed re-check immediately before counting. (The interrupt longjmp
+// still rips through QuickJS frames — a pre-existing hazard; whether the
+// bridge should rb_protect and convert instead is a semantics decision
+// deferred in the #56 review.)
+static VALUE run_held_js_entry(VMData *data, VALUE (*body)(VALUE), VALUE arg)
+{
+  check_disposed(data);
+  data->evals_in_flight++;
+  return rb_ensure(body, arg, evals_in_flight_release, (VALUE)data);
+}
+
+static VALUE eval_code_job_run_body(VALUE p)
+{
+  eval_code_job_run((struct eval_code_job *)p);
+  return Qnil;
+}
+
+// rb_ensure bodies over the shared bytecode core, for the GVL-held call
+// sites: vm_m_loadPolyfillBytecode's held fallback loads without awaiting
+// (matching its release path), vm_m_evalBytecode awaits the result. These
+// can take RSTRING_PTR without a copy: JS_ReadObject consumes the buffer
+// before any bridge can fire, so the GVL is provably held (no compaction)
+// for as long as the pointer is read.
+static VALUE bytecode_load_body(VALUE p)
+{
+  bytecode_load_job_run((struct bytecode_load_job *)p);
+  return Qnil;
+}
+
+static VALUE bytecode_eval_await_body(VALUE p)
+{
+  struct bytecode_load_job *job = (struct bytecode_load_job *)p;
+  bytecode_load_job_run(job);
+  // js_std_await passes a non-promise — including an exception preserved by
+  // the JS_ReadObject short-circuit — through untouched.
+  job->result = js_std_await(job->ctx, job->result);
+  return Qnil;
+}
+
+// Copy a Ruby String to a malloc'd buffer that outlives a GVL release —
+// RSTRING_PTR is GC-movable, so a released region must not read the
+// String's own storage. Ownership passes to the caller (the release
+// regions free it on every exit path). nul_terminate preserves the
+// sentinel NUL QuickJS's parser reads past the length: Ruby strings carry
+// one past RSTRING_LEN, so GVL-held paths get it for free, and a copy
+// must add it back. Allocates at least one byte either way — malloc(0)
+// may return NULL on success, and an empty String (e.g. empty bytecode)
+// must still reach the JS-level diagnostic instead of a spurious
+// NoMemError.
+static char *copy_rstring_to_owned_buffer(VALUE r_str, size_t *out_len, bool nul_terminate)
+{
+  size_t len = (size_t)RSTRING_LEN(r_str);
+  char *buf = malloc(nul_terminate ? len + 1 : (len > 0 ? len : 1));
+  if (buf == NULL)
+    rb_raise(rb_eNoMemError, "failed to allocate a GVL-release copy of a Ruby String");
+  memcpy(buf, RSTRING_PTR(r_str), len);
+  if (nul_terminate)
+    buf[len] = '\0';
+  *out_len = len;
+  return buf;
+}
+
+// Run the eval core without the GVL. Inputs are copied to malloc'd buffers
+// because RSTRING_PTR can be invalidated by GC compaction while we're
+// released.
+static VALUE eval_code_release_gvl(VMData *data, VALUE r_code, const char *filename, bool async_mode)
+{
+  size_t code_len;
+  char *code_buf = copy_rstring_to_owned_buffer(r_code, &code_len, true);
+
+  char *filename_buf = strdup(filename);
+  if (filename_buf == NULL)
+  {
+    free(code_buf);
+    rb_raise(rb_eNoMemError, "failed to allocate eval filename buffer");
+  }
+
+  struct eval_code_job job = {
+      .ctx = data->context,
+      .code = code_buf,
+      .code_len = code_len,
+      .filename = filename_buf,
+      .async_mode = async_mode,
+      .result = JS_UNDEFINED,
+  };
+  run_gvl_release_region(data, eval_code_job_run, &job, &job.result, code_buf, filename_buf);
+
+  return to_rb_return_value(data->context, job.result);
+}
+
 static VALUE vm_m_evalCode(int argc, VALUE *argv, VALUE r_self)
 {
   VMData *data;
@@ -1218,19 +1594,23 @@ static VALUE vm_m_evalCode(int argc, VALUE *argv, VALUE r_self)
 
   StringValue(r_code);
 
-  if (!async_mode)
-  {
-    JSValue j_codeResult = JS_Eval(data->context, RSTRING_PTR(r_code), RSTRING_LEN(r_code), filename, JS_EVAL_TYPE_GLOBAL);
-    return to_rb_return_value(data->context, j_codeResult);
-  }
-
-  JSValue j_codeResult = JS_Eval(data->context, RSTRING_PTR(r_code), RSTRING_LEN(r_code), filename, JS_EVAL_TYPE_GLOBAL | JS_EVAL_FLAG_ASYNC);
-  JSValue j_awaitedResult = js_std_await(data->context, j_codeResult); // This frees j_codeResult
-  // JS_EVAL_FLAG_ASYNC wraps the result in {value, done} — extract the actual value
-  // Free j_awaitedResult before to_rb_return_value because it may raise (longjmp), which would skip cleanup
-  JSValue j_returnedValue = JS_GetPropertyStr(data->context, j_awaitedResult, "value");
-  JS_FreeValue(data->context, j_awaitedResult);
-  return to_rb_return_value(data->context, j_returnedValue);
+  if (can_eval_gvl_free(data))
+    return eval_code_release_gvl(data, r_code, filename, async_mode);
+
+  // Bridged path: a JS→Ruby bridge (define_function / module loader /
+  // setTimeout / File / crypto) may fire mid-eval, so keep the GVL held and
+  // run the shared eval core directly. With the GVL held there's no
+  // compaction risk, so RSTRING_PTR is usable without a malloc'd copy.
+  struct eval_code_job job = {
+      .ctx = data->context,
+      .code = RSTRING_PTR(r_code),
+      .code_len = (size_t)RSTRING_LEN(r_code),
+      .filename = filename,
+      .async_mode = async_mode,
+      .result = JS_UNDEFINED,
+  };
+  run_held_js_entry(data, eval_code_job_run_body, (VALUE)&job);
+  return to_rb_return_value(data->context, job.result);
 }
 
 static VALUE vm_m_compile(int argc, VALUE *argv, VALUE r_self)
@@ -1275,6 +1655,7 @@ static VALUE vm_m_evalBytecode(VALUE r_self, VALUE r_bytecode)
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
 
   check_disposed(data);
+  check_oom_poisoned(data);
 
   if (!RB_TYPE_P(r_bytecode, T_STRING))
   {
@@ -1286,22 +1667,21 @@ static VALUE vm_m_evalBytecode(VALUE r_self, VALUE r_bytecode)
 
   arm_eval_timer(data);
 
-  // GVL intentionally held here: user bytecode may invoke Ruby-bridged
-  // callbacks registered via define_function, which call Ruby APIs.
-  // Unlike polyfill_load_no_gvl, this path cannot release the GVL safely.
-  JSValue j_func = JS_ReadObject(data->context,
-                                 (const uint8_t *)RSTRING_PTR(r_bytecode),
-                                 (size_t)RSTRING_LEN(r_bytecode),
-                                 JS_READ_OBJ_BYTECODE);
-  if (JS_IsException(j_func))
-  {
-    return to_rb_value(data->context, j_func); // raises
-  }
-
-  JSValue j_codeResult = JS_EvalFunction(data->context, j_func); // frees j_func
-  JSValue j_awaitedResult = js_std_await(data->context, j_codeResult);
-  JSValue j_returnedValue = JS_GetPropertyStr(data->context, j_awaitedResult, "value");
-  JS_FreeValue(data->context, j_awaitedResult);
+  // GVL held: user bytecode may invoke Ruby-bridged callbacks registered
+  // via define_function, which call Ruby APIs. A pure VM could release
+  // here with the same can_eval_gvl_free gate + buffer copy eval_code
+  // uses — left GVL-held deliberately until bytecode eval shows up as a
+  // parallelism bottleneck.
+  struct bytecode_load_job job = {data->context,
+                                  (const uint8_t *)RSTRING_PTR(r_bytecode),
+                                  (size_t)RSTRING_LEN(r_bytecode),
+                                  JS_UNDEFINED};
+  run_held_js_entry(data, bytecode_eval_await_body, (VALUE)&job);
+  if (JS_IsException(job.result))
+    return to_rb_value(data->context, job.result); // raises
+
+  JSValue j_returnedValue = JS_GetPropertyStr(data->context, job.result, "value");
+  JS_FreeValue(data->context, job.result);
   return to_rb_return_value(data->context, j_returnedValue);
 }
 
@@ -1309,29 +1689,87 @@ static VALUE vm_m_evalBytecode(VALUE r_self, VALUE r_bytecode)
 // The user's `timeout_msec` is a budget for *their* code; running a
 // multi-MB polyfill bundle (e.g. the companion `quickjs-polyfill-intl`
 // gem registered via Quickjs.register_polyfill) under that budget would
-// interrupt the load on tight defaults. Unlike load_polyfill_bytecode
-// above we hold the GVL through JS_ReadObject + JS_EvalFunction: the
-// bytecode buffer is a Ruby String, so releasing would let GC compact
-// the backing storage out from under us. The static-symbol path can
-// release safely; this path cannot.
+// interrupt the load on tight defaults.
+//
+// Picks the GVL-released or GVL-held path based on can_eval_gvl_free
+// (same gate vm_m_evalCode uses): if POLYFILL_FILE / POLYFILL_CRYPTO is
+// enabled, the polyfill's top-level code could reach a Ruby-bridged C
+// function that calls rb_funcall directly — those bridges don't honor
+// gvl_released_js, so we must keep the GVL. Otherwise, csim and similar
+// warmer-thread VM pools recover multi-core scaling: without the release
+// every warmer's polyfill load serializes through the GVL, collapsing
+// 4-way warmer parallelism to 1.
+//
+// The GVL-released path copies the Ruby String to a malloc'd buffer
+// because RSTRING_PTR can be invalidated by GC compaction while the GVL
+// is released. The memcpy cost is microseconds vs hundreds of ms of
+// bytecode eval, so it's negligible.
 static VALUE vm_m_loadPolyfillBytecode(VALUE r_self, VALUE r_bytecode)
 {
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
 
-  check_disposed(data);
+  // StringValue can invoke a non-String argument's to_str, which may
+  // yield the GVL — run it before the disposed check so nothing below
+  // touches a context freed by a concurrent dispose! in that window.
   StringValue(r_bytecode);
 
-  JSValue j_func = JS_ReadObject(data->context,
-                                 (const uint8_t *)RSTRING_PTR(r_bytecode),
-                                 (size_t)RSTRING_LEN(r_bytecode),
-                                 JS_READ_OBJ_BYTECODE);
-  if (JS_IsException(j_func))
-    return to_rb_value(data->context, j_func); // raises
+  check_disposed(data);
+  check_oom_poisoned(data);
+
+  // "Unbudgeted" needs enforcing, not just skipping arm_eval_timer: the
+  // interrupt handler installed by a previous eval stays armed with that
+  // eval's started_at, so a load after the budget lapsed would be
+  // interrupted on its first check — and because the bytecode is
+  // async-wrapped, the interruption surfaces as a rejected promise the
+  // old code never looked at: the load "succeeded" with the polyfill
+  // silently missing. Disarm for the load; the next eval re-arms. Only
+  // when this load is the outermost JS activity, though: a load issued
+  // from inside a bridge callback (e.g. an on_log listener) must stay
+  // under the in-flight eval's budget, not erase it.
+  if (data->evals_in_flight == 0)
+    JS_SetInterruptHandler(JS_GetRuntime(data->context), NULL, NULL);
+
+  size_t buf_len = (size_t)RSTRING_LEN(r_bytecode);
+  JSValue j_result;
+  if (can_eval_gvl_free(data))
+  {
+    uint8_t *buf = (uint8_t *)copy_rstring_to_owned_buffer(r_bytecode, &buf_len, false);
+    j_result = load_polyfill_bytecode(data, buf, buf_len, true);
+  }
+  else
+  {
+    // This branch runs exactly when a Ruby bridge (crypto, File, …) is
+    // installed, and every rb_funcall inside one is an interrupt
+    // checkpoint — run_held_js_entry keeps the counter unwind (and the
+    // stale-dispose re-check the released branch gets from its region)
+    // on this path too.
+    struct bytecode_load_job job = {data->context,
+                                    (const uint8_t *)RSTRING_PTR(r_bytecode),
+                                    buf_len,
+                                    JS_UNDEFINED};
+    run_held_js_entry(data, bytecode_load_body, (VALUE)&job);
+    j_result = job.result;
+  }
 
-  JSValue j_result = JS_EvalFunction(data->context, j_func); // frees j_func
   if (JS_IsException(j_result))
     return to_rb_value(data->context, j_result); // raises
+
+  // The compiled bytecode is async-wrapped (JS_EVAL_FLAG_ASYNC), so a
+  // top-level throw doesn't come back as JS_EXCEPTION — it comes back as
+  // a rejected promise. Surface it instead of silently shipping a VM
+  // whose polyfill half-ran. Re-throwing the reason routes it through
+  // to_rb_value's standard exception path, so interrupted/OOM mapping,
+  // oom_poisoned latching, and the on_log error dispatch all behave
+  // exactly as for a synchronous throw.
+  if (JS_PromiseState(data->context, j_result) == JS_PROMISE_REJECTED)
+  {
+    JSValue j_reason = JS_PromiseResult(data->context, j_result);
+    JS_FreeValue(data->context, j_result);
+    JS_Throw(data->context, j_reason); // consumes j_reason
+    return to_rb_value(data->context, JS_EXCEPTION); // raises
+  }
+
   JS_FreeValue(data->context, j_result);
   return Qnil;
 }
@@ -1349,6 +1787,7 @@ static VALUE vm_m_defineGlobalFunction(int argc, VALUE *argv, VALUE r_self)
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
 
   check_disposed(data);
+  check_no_gvl_release_in_flight(data);
 
   if (RB_TYPE_P(r_name, T_ARRAY))
   {
@@ -1393,6 +1832,10 @@ static VALUE vm_m_defineGlobalFunction(int argc, VALUE *argv, VALUE r_self)
     {
       VALUE r_first_str = rb_funcall(RARRAY_AREF(r_name, 0), rb_intern("to_s"), 0);
       const char *first_seg = StringValueCStr(r_first_str);
+      // This lookup eval runs under whatever interrupt handler the
+      // previous eval left armed; refresh the clock so a lapsed budget
+      // can't misfire here and masquerade as "'%s' is not an object".
+      arm_eval_timer(data);
       j_parent = JS_Eval(data->context, first_seg, strlen(first_seg), vmInternalFilename, JS_EVAL_TYPE_GLOBAL);
 
       if (JS_IsException(j_parent) || !JS_IsObject(j_parent))
@@ -1460,18 +1903,20 @@ static VALUE vm_m_defineGlobalFunction(int argc, VALUE *argv, VALUE r_self)
   }
 }
 
-static VALUE vm_m_callGlobalFunction(int argc, VALUE *argv, VALUE r_self)
+struct js_entry_call
 {
-  if (argc < 1)
-    rb_raise(rb_eArgError, "wrong number of arguments (given 0, expected 1+)");
-
-  VALUE r_name = argv[0];
-
+  int argc;
+  VALUE *argv;
   VMData *data;
-  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+};
 
-  check_disposed(data);
-  check_oom_poisoned(data);
+static VALUE call_global_function_body(VALUE p)
+{
+  struct js_entry_call *call = (struct js_entry_call *)p;
+  int argc = call->argc;
+  VALUE *argv = call->argv;
+  VMData *data = call->data;
+  VALUE r_name = argv[0];
 
   JSValue j_this = JS_UNDEFINED;
   JSValue j_func;
@@ -1599,6 +2044,26 @@ static VALUE vm_m_callGlobalFunction(int argc, VALUE *argv, VALUE r_self)
   return to_rb_return_value(data->context, js_std_await(data->context, j_result));
 }
 
+static VALUE vm_m_callGlobalFunction(int argc, VALUE *argv, VALUE r_self)
+{
+  if (argc < 1)
+    rb_raise(rb_eArgError, "wrong number of arguments (given 0, expected 1+)");
+
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+
+  check_disposed(data);
+  check_oom_poisoned(data);
+
+  // evals_in_flight stays elevated for the whole call, not just the
+  // JS_Eval / JS_Call moments: the body holds live JSValues across Ruby
+  // calls that can yield the GVL (path-segment to_s, argument
+  // conversion), and a concurrent dispose! landing in such a gap would
+  // free the runtime out from under them.
+  struct js_entry_call call = {argc, argv, data};
+  return run_held_js_entry(data, call_global_function_body, (VALUE)&call);
+}
+
 static VALUE vm_m_set_module_loader(VALUE r_self, VALUE r_loader)
 {
   VMData *data;
@@ -1607,6 +2072,7 @@ static VALUE vm_m_set_module_loader(VALUE r_self, VALUE r_loader)
   if (!NIL_P(r_loader) && !rb_obj_is_kind_of(r_loader, rb_cProc))
     rb_raise(rb_eTypeError, "module_loader must be a Proc or nil");
 
+  check_no_gvl_release_in_flight(data);
   data->module_loader = r_loader;
   // Stale entries from the previous loader's policy would survive the
   // swap and silently shadow the new behavior.
@@ -1630,12 +2096,18 @@ static VALUE vm_m_on_unhandled_rejection(VALUE r_self)
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
 
+  check_no_gvl_release_in_flight(data);
   data->on_unhandled_rejection = rb_block_proc();
   return Qnil;
 }
 
-static VALUE vm_m_import(int argc, VALUE *argv, VALUE r_self)
+static VALUE import_body(VALUE p)
 {
+  struct js_entry_call *call = (struct js_entry_call *)p;
+  int argc = call->argc;
+  VALUE *argv = call->argv;
+  VMData *data = call->data;
+
   VALUE r_import_string, r_opts;
   rb_scan_args(argc, argv, "10:", &r_import_string, &r_opts);
   if (NIL_P(r_opts))
@@ -1652,11 +2124,6 @@ static VALUE vm_m_import(int argc, VALUE *argv, VALUE r_self)
     rb_raise(rb_eArgError, "pass either from: (inline source) or filename: (loader-resolved), not both");
   VALUE r_custom_exposure = rb_hash_aref(r_opts, ID2SYM(rb_intern("code_to_expose")));
 
-  VMData *data;
-  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
-
-  check_disposed(data);
-
   char *filename;
   VALUE r_seeded_key = Qnil;
   if (!NIL_P(r_filename))
@@ -1732,6 +2199,29 @@ static VALUE vm_m_import(int argc, VALUE *argv, VALUE r_self)
   return Qtrue;
 }
 
+static VALUE vm_m_import(int argc, VALUE *argv, VALUE r_self)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+
+  check_disposed(data);
+  check_oom_poisoned(data);
+
+  // Module top-level code is user JS like any eval — budget it. Without
+  // this, import ran under whatever handler the previous entry point
+  // left behind: a lapsed armed one (spurious interrupt) or none at all
+  // after a polyfill load's disarm (unbounded).
+  arm_eval_timer(data);
+
+  // Like vm_m_callGlobalFunction: the body registers a module in the
+  // context and then runs Ruby code (_build_import, StringValueCStr on
+  // user values) that can yield the GVL before the bridge eval — keep
+  // evals_in_flight elevated for the whole call so a concurrent dispose!
+  // can't free the runtime in those gaps.
+  struct js_entry_call call = {argc, argv, data};
+  return run_held_js_entry(data, import_body, (VALUE)&call);
+}
+
 RUBY_FUNC_EXPORTED void Init_quickjsrb(void)
 {
   rb_require("json");
@@ -1796,19 +2286,10 @@ static VALUE vm_m_runGC(VALUE r_self)
   return Qnil;
 }
 
-static VALUE vm_m_drainJobs(VALUE r_self)
+static VALUE drain_jobs_body(VALUE p)
 {
-  VMData *data;
-  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
-
-  check_oom_poisoned(data);
-
+  VMData *data = (VMData *)p;
   JSRuntime *runtime = JS_GetRuntime(data->context);
-  if (!JS_IsJobPending(runtime))
-    return INT2NUM(0);
-
-  arm_eval_timer(data);
-
   int executed = 0;
   for (;;)
   {
@@ -1822,6 +2303,22 @@ static VALUE vm_m_drainJobs(VALUE r_self)
   return INT2NUM(executed);
 }
 
+static VALUE vm_m_drainJobs(VALUE r_self)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+
+  check_disposed(data);
+  check_oom_poisoned(data);
+
+  if (!JS_IsJobPending(JS_GetRuntime(data->context)))
+    return INT2NUM(0);
+
+  arm_eval_timer(data);
+
+  return run_held_js_entry(data, drain_jobs_body, (VALUE)data);
+}
+
 static VALUE vm_m_memoryPoisoned(VALUE r_self)
 {
   VMData *data;
@@ -1849,6 +2346,15 @@ static VALUE vm_m_dispose(VALUE r_self)
   if (data->disposed)
     return Qnil;
 
+  // Freeing the runtime under live JS is a use-after-free. The overlap is
+  // reachable both through the GVL release (pure-path evals) and through
+  // GVL-yielding bridge callbacks (setTimeout's rb_thread_wait_for,
+  // define_function procs, on_log listeners) — including the README's
+  // `Thread.new { vm.dispose! }` pattern and a listener calling dispose!
+  // mid-eval. Fail loudly instead of corrupting the heap.
+  if (data->evals_in_flight > 0)
+    rb_raise(rb_eThreadError, "cannot dispose a Quickjs::VM while it is evaluating");
+
   if (!JS_IsUndefined(data->j_file_proxy_creator))
   {
     JS_FreeValue(data->context, data->j_file_proxy_creator);

data/ext/quickjsrb/quickjsrb.h

@@ -75,8 +75,60 @@ typedef struct VMData
   // enough pressure to collect the wrapper. Doubles as a double-free guard
   // for the dfree handler.
   bool disposed;
+  // Set while JS is executing with the GVL released so JS→Ruby bridges
+  // (currently js_quickjsrb_log) can re-acquire the GVL before touching
+  // Ruby APIs. Covers both vm_m_evalCode and vm_m_loadPolyfillBytecode;
+  // reset before to_rb_return_value or other Ruby-touching code runs.
+  // Saved/restored (not blindly cleared) so a region nested through an
+  // on_log listener doesn't clear the outer region's flag.
+  bool gvl_released_js;
+  // Number of JS executions currently in flight on this VM — eval_code
+  // (both the GVL-released and GVL-held paths), call, bytecode runs,
+  // polyfill bytecode loads, import, and job drains. vm_m_dispose refuses
+  // (ThreadError) while nonzero: freeing the runtime under live JS is a
+  // use-after-free, and both the GVL release and GVL-yielding bridge
+  // callbacks (setTimeout's rb_thread_wait_for, define_function procs,
+  // on_log listeners) make that overlap reachable — e.g. the README's
+  // `Thread.new { vm.dispose! }` pattern, or a listener calling dispose!
+  // mid-eval. Only mutated while holding the GVL, so plain int accesses
+  // are race-free.
+  int evals_in_flight;
+  // Number of GVL-release regions currently open on this VM (a subset of
+  // evals_in_flight). Bridge-registration APIs (define_function,
+  // module_loader=, on_unhandled_rejection) refuse (ThreadError) while
+  // nonzero: the running JS was allowed to release the GVL because
+  // can_eval_gvl_free held at eval start, and installing a bridge
+  // mid-flight — e.g. from an on_log listener, whose callback runs with
+  // the GVL re-acquired — would hand the still-released JS a path into
+  // Ruby APIs without the GVL. Only mutated while holding the GVL.
+  int gvl_release_regions;
+  // Latched by quickjsrb_new_ruby_bridge whenever a C function that calls
+  // into Ruby synchronously (rb_funcall & friends) WITHOUT honoring
+  // gvl_released_js is installed into this context. While true,
+  // can_eval_gvl_free fails and eval keeps the GVL held. Register every
+  // such function through that helper — a bridge registered with plain
+  // JS_NewCFunction would run against Ruby under a released GVL and
+  // silently corrupt the interpreter.
+  bool has_native_ruby_bridge;
 } VMData;
 
+// Drop-in replacement for JS_NewCFunction for C functions that call into
+// Ruby synchronously without honoring gvl_released_js (crypto.*, File
+// proxy helpers, setTimeout's job). Latching has_native_ruby_bridge here
+// makes the "keep the GVL held" contract structural instead of relying on
+// each feature-init site to remember a flag assignment. Requires
+// JS_SetContextOpaque(ctx, data) to have run (vm_m_initialize does this
+// before any feature setup). console.log intentionally does NOT go through
+// this: js_quickjsrb_log re-acquires the GVL itself, and Proc-backed
+// bridges (define_function / module_loader / on_unhandled_rejection) are
+// excluded structurally by can_eval_gvl_free's own checks.
+static inline JSValue quickjsrb_new_ruby_bridge(JSContext *ctx, JSCFunction *func, const char *name, int length)
+{
+  VMData *data = JS_GetContextOpaque(ctx);
+  data->has_native_ruby_bridge = true;
+  return JS_NewCFunction(ctx, func, name, length);
+}
+
 static void vm_teardown_context(JSContext *ctx)
 {
   JSRuntime *runtime = JS_GetRuntime(ctx);
@@ -168,6 +220,10 @@ static VALUE vm_alloc(VALUE r_self)
   data->j_file_proxy_creator = JS_UNDEFINED;
   data->oom_poisoned = false;
   data->disposed = false;
+  data->gvl_released_js = false;
+  data->evals_in_flight = 0;
+  data->gvl_release_regions = 0;
+  data->has_native_ruby_bridge = false;
 
   EvalTime *eval_time = malloc(sizeof(EvalTime));
   data->eval_time = eval_time;

data/ext/quickjsrb/quickjsrb_crypto.c

@@ -63,9 +63,9 @@ void quickjsrb_init_crypto(JSContext *ctx, JSValue j_global)
 {
   JSValue j_crypto = JS_NewObject(ctx);
   JS_SetPropertyStr(ctx, j_crypto, "getRandomValues",
-                    JS_NewCFunction(ctx, js_crypto_get_random_values, "getRandomValues", 1));
+                    quickjsrb_new_ruby_bridge(ctx, js_crypto_get_random_values, "getRandomValues", 1));
   JS_SetPropertyStr(ctx, j_crypto, "randomUUID",
-                    JS_NewCFunction(ctx, js_crypto_random_uuid, "randomUUID", 0));
+                    quickjsrb_new_ruby_bridge(ctx, js_crypto_random_uuid, "randomUUID", 0));
   quickjsrb_init_crypto_subtle(ctx, j_crypto);
   JS_SetPropertyStr(ctx, j_global, "crypto", j_crypto);
 }

data/ext/quickjsrb/quickjsrb_crypto_subtle.c

@@ -65,6 +65,7 @@ static VALUE js_usages_to_ruby_array(JSContext *ctx, JSValueConst j_usages)
 static void js_reject_with_ruby_error(JSContext *ctx, JSValueConst *resolving_funcs)
 {
   VALUE r_error = rb_errinfo();
+  rb_set_errinfo(Qnil);
   VALUE r_message = rb_funcall(r_error, rb_intern("message"), 0);
   JSValue j_err = JS_NewError(ctx);
   JS_SetPropertyStr(ctx, j_err, "message", JS_NewString(ctx, StringValueCStr(r_message)));
@@ -974,28 +975,28 @@ void quickjsrb_init_crypto_subtle(JSContext *ctx, JSValueConst j_crypto)
 {
   JSValue j_subtle = JS_NewObject(ctx);
   JS_SetPropertyStr(ctx, j_subtle, "digest",
-                    JS_NewCFunction(ctx, js_subtle_digest, "digest", 2));
+                    quickjsrb_new_ruby_bridge(ctx, js_subtle_digest, "digest", 2));
   JS_SetPropertyStr(ctx, j_subtle, "generateKey",
-                    JS_NewCFunction(ctx, js_subtle_generate_key, "generateKey", 3));
+                    quickjsrb_new_ruby_bridge(ctx, js_subtle_generate_key, "generateKey", 3));
   JS_SetPropertyStr(ctx, j_subtle, "importKey",
-                    JS_NewCFunction(ctx, js_subtle_import_key, "importKey", 5));
+                    quickjsrb_new_ruby_bridge(ctx, js_subtle_import_key, "importKey", 5));
   JS_SetPropertyStr(ctx, j_subtle, "exportKey",
-                    JS_NewCFunction(ctx, js_subtle_export_key, "exportKey", 2));
+                    quickjsrb_new_ruby_bridge(ctx, js_subtle_export_key, "exportKey", 2));
   JS_SetPropertyStr(ctx, j_subtle, "encrypt",
-                    JS_NewCFunction(ctx, js_subtle_encrypt, "encrypt", 3));
+                    quickjsrb_new_ruby_bridge(ctx, js_subtle_encrypt, "encrypt", 3));
   JS_SetPropertyStr(ctx, j_subtle, "decrypt",
-                    JS_NewCFunction(ctx, js_subtle_decrypt, "decrypt", 3));
+                    quickjsrb_new_ruby_bridge(ctx, js_subtle_decrypt, "decrypt", 3));
   JS_SetPropertyStr(ctx, j_subtle, "sign",
-                    JS_NewCFunction(ctx, js_subtle_sign, "sign", 3));
+                    quickjsrb_new_ruby_bridge(ctx, js_subtle_sign, "sign", 3));
   JS_SetPropertyStr(ctx, j_subtle, "verify",
-                    JS_NewCFunction(ctx, js_subtle_verify, "verify", 4));
+                    quickjsrb_new_ruby_bridge(ctx, js_subtle_verify, "verify", 4));
   JS_SetPropertyStr(ctx, j_subtle, "deriveBits",
-                    JS_NewCFunction(ctx, js_subtle_derive_bits, "deriveBits", 3));
+                    quickjsrb_new_ruby_bridge(ctx, js_subtle_derive_bits, "deriveBits", 3));
   JS_SetPropertyStr(ctx, j_subtle, "deriveKey",
-                    JS_NewCFunction(ctx, js_subtle_derive_key, "deriveKey", 5));
+                    quickjsrb_new_ruby_bridge(ctx, js_subtle_derive_key, "deriveKey", 5));
   JS_SetPropertyStr(ctx, j_subtle, "wrapKey",
-                    JS_NewCFunction(ctx, js_subtle_wrap_key, "wrapKey", 4));
+                    quickjsrb_new_ruby_bridge(ctx, js_subtle_wrap_key, "wrapKey", 4));
   JS_SetPropertyStr(ctx, j_subtle, "unwrapKey",
-                    JS_NewCFunction(ctx, js_subtle_unwrap_key, "unwrapKey", 7));
+                    quickjsrb_new_ruby_bridge(ctx, js_subtle_unwrap_key, "unwrapKey", 7));
   JS_SetPropertyStr(ctx, j_crypto, "subtle", j_subtle);
 }

data/ext/quickjsrb/quickjsrb_file.c

@@ -203,13 +203,13 @@ void quickjsrb_init_file_proxy(VMData *data)
   JSValue j_factory_fn = JS_Eval(data->context, factory_src, strlen(factory_src), "<file-proxy>", JS_EVAL_TYPE_GLOBAL);
 
   JSValue j_helpers[7];
-  j_helpers[0] = JS_NewCFunction(data->context, js_ruby_file_name, "__rb_file_name", 1);
-  j_helpers[1] = JS_NewCFunction(data->context, js_ruby_file_size, "__rb_file_size", 1);
-  j_helpers[2] = JS_NewCFunction(data->context, js_ruby_file_type, "__rb_file_type", 1);
-  j_helpers[3] = JS_NewCFunction(data->context, js_ruby_file_last_modified, "__rb_file_last_modified", 1);
-  j_helpers[4] = JS_NewCFunction(data->context, js_ruby_file_text, "__rb_file_text", 1);
-  j_helpers[5] = JS_NewCFunction(data->context, js_ruby_file_array_buffer, "__rb_file_array_buffer", 1);
-  j_helpers[6] = JS_NewCFunction(data->context, js_ruby_file_slice, "__rb_file_slice", 4);
+  j_helpers[0] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_name, "__rb_file_name", 1);
+  j_helpers[1] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_size, "__rb_file_size", 1);
+  j_helpers[2] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_type, "__rb_file_type", 1);
+  j_helpers[3] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_last_modified, "__rb_file_last_modified", 1);
+  j_helpers[4] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_text, "__rb_file_text", 1);
+  j_helpers[5] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_array_buffer, "__rb_file_array_buffer", 1);
+  j_helpers[6] = quickjsrb_new_ruby_bridge(data->context, js_ruby_file_slice, "__rb_file_slice", 4);
 
   data->j_file_proxy_creator = JS_Call(data->context, j_factory_fn, JS_UNDEFINED, 7, j_helpers);
 

data/lib/quickjs/polyfills.rb

@@ -8,13 +8,21 @@ module Quickjs
   # `source:` accepts either a `String` (eager) or a `Proc` returning one
   # (lazy). The lazy form lets a companion gem call `register_polyfill`
   # at require time without paying the file-read cost unless a VM
-  # actually opts into the feature.
+  # actually opts into the feature. The Proc must not itself construct a
+  # VM with the same feature: compilation is locked per entry, so that
+  # recursion raises ThreadError instead of deadlocking silently.
+  #
+  # Re-registering a name replaces the entry wholesale, lock included: a
+  # VM construction already compiling under the old entry finishes
+  # against it (and loads the old bytecode) while the first construction
+  # under the new entry compiles the new source independently. Each
+  # registration compiles at most once; the two compiles can overlap.
   def self.register_polyfill(name, source:, init: nil)
     raise ::TypeError, "name must be a Symbol, got #{name.class}" unless name.is_a?(Symbol)
     raise ::TypeError, "source: must be a String or Proc, got #{source.class}" unless source.is_a?(String) || source.is_a?(Proc)
     raise ::TypeError, "init: must be a String or nil, got #{init.class}" unless init.nil? || init.is_a?(String)
 
-    @_polyfills[name] = {source: source, init: init&.freeze, bytecode: nil}
+    @_polyfills[name] = {source: source, init: init&.freeze, bytecode: nil, mutex: Mutex.new}
     nil
   end
 
@@ -30,15 +38,26 @@ module Quickjs
   def self._apply_registered_polyfills(vm, features)
     features.each do |feature|
       next unless (entry = @_polyfills[feature])
-      # `||=` isn't atomic — `_precompile_polyfill` releases the GVL inside
-      # `Quickjs.compile`, so two threads racing to construct VMs with the
-      # same polyfill can both see nil and both compile. The bytecode write
-      # is harmless because both threads produce identical bytes; the only
-      # observable cost is wasted compile work, and (for `source: Proc`) a
-      # second Proc invocation — so register Procs that are safe to call
-      # more than once.
-      entry[:bytecode] ||= _precompile_polyfill(entry, feature)
-      vm.send(:_load_polyfill_bytecode, entry[:bytecode])
+      # The per-entry mutex makes first-use compilation happen exactly once
+      # even when threads race to construct VMs with the same polyfill —
+      # `||=` alone isn't atomic (`_precompile_polyfill` yields the GVL
+      # inside `Quickjs.compile`), and a losing thread could otherwise
+      # double-compile or read entry[:source] after the winner cleared it.
+      # A compile failure leaves bytecode nil and source intact, so a later
+      # attempt can retry. The unlocked first read keeps the post-compile
+      # hot path (warmer pools constructing VMs concurrently) off the lock;
+      # a stale nil just falls into the synchronize.
+      bytecode = entry[:bytecode] || entry[:mutex].synchronize {
+        entry[:bytecode] ||= begin
+          compiled = _precompile_polyfill(entry, feature)
+          # The Proc / String source isn't needed again once the bytecode
+          # is cached — drop it so its captured scope can be GC'd.
+          entry[:source] = nil
+          entry[:init]   = nil
+          compiled
+        end
+      }
+      vm.send(:_load_polyfill_bytecode, bytecode)
     end
   end
 

data/lib/quickjs/subtle_crypto.rb

@@ -351,6 +351,8 @@ module Quickjs
       cipher = OpenSSL::Cipher.new("aes-#{key.algorithm["length"]}-gcm")
       cipher.encrypt
       cipher.key = key.key_data
+      # WebCrypto allows any nonzero IV length for AES-GCM; OpenSSL defaults to 12 bytes
+      cipher.iv_len = iv.bytesize
       cipher.iv = iv
       cipher.auth_data = additional_data || ""
       ciphertext = cipher.update(data) + cipher.final
@@ -365,12 +367,16 @@ module Quickjs
       additional_data = params[:additional_data]
 
       tag_bytes = tag_length / 8
+      if data.bytesize < tag_bytes
+        raise ArgumentError, "SubtleCrypto: AES-GCM data is shorter than the #{tag_bytes}-byte authentication tag"
+      end
       ciphertext = data[0, data.bytesize - tag_bytes]
       tag = data[-tag_bytes, tag_bytes]
 
       decipher = OpenSSL::Cipher.new("aes-#{key.algorithm["length"]}-gcm")
       decipher.decrypt
       decipher.key = key.key_data
+      decipher.iv_len = iv.bytesize
       decipher.iv = iv
       decipher.auth_tag = tag
       decipher.auth_data = additional_data || ""

data/lib/quickjs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Quickjs
-  VERSION = "0.20.0"
+  VERSION = "0.21.0.rc1"
 end

data/polyfills/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "quickjs-rb-polyfills",
-  "version": "0.20.0",
+  "version": "0.21.0.rc1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "quickjs-rb-polyfills",
-      "version": "0.20.0",
+      "version": "0.21.0.rc1",
       "devDependencies": {
         "rolldown": "^1.0.0-rc.14"
       }

data/polyfills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quickjs-rb-polyfills",
-  "version": "0.20.0",
+  "version": "0.21.0.rc1",
   "private": true,
   "scripts": {
     "build": "rolldown -c rolldown.config.mjs"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quickjs
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0.rc1
 platform: ruby
 authors:
 - hmsk