quickjs 0.16.0 → 0.17.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8f0513a5e0a54c24bdc8c20000f8cf9d1611e394683a710a2260ebedb57913a
-  data.tar.gz: 335ab02e13a0b8b137342f5895bc821641ac33d6f8370e05b9c24f0ca3ce7416
+  metadata.gz: 7b233c0e106654a50f4af274fef6a4dd77f0b53cc0a703473cda844da6ba3763
+  data.tar.gz: 50dfeaf56422ee74e8cb8711a58e1678c8141ac4bb7256a4d8861fa1a9415c93
 SHA512:
-  metadata.gz: f6e975069d7b77adf0d2e4ca7d6459c6499e1465155cae563ff3fb87d7f1f8aefe9f3b26191d9736a2c398ee13df48d5ded389b17f54aec56dc2bf4e4ac580a8
-  data.tar.gz: b1341d5c2e0ba51e6891752bc6c203fe7c2bfc8e1d76beafaf93129f3fb0bb600c64e786beec42ec6a9cc95336562de739d32f02711422b1f9930dd4b57cbb93
+  metadata.gz: 9f77f8b802055b1ec67ad9b4f45fb54cbdb1349a473457572c1c1b72115283bed9b99b15029e101256147ce0bbc72b64371fcbdd0ede6e8e9ba5e8d4a0bb0376
+  data.tar.gz: 9387e82c41c0242caa67c16a67b48a204c32512b116c5e4cc61d83e892bec053393facaf7ac2553642b876cacecb3622ddb37a846fd1eea959c21ea7df70b569

data/README.md

@@ -85,6 +85,21 @@ vm.eval_code('a.b = "d";')
 vm.eval_code('a.b;') #=> "d"
 ```
 
+#### `Quickjs::VM#compile`: 🚀 Cache parsed bundles as a `Quickjs::Runnable`
+
+Parsing large JS bundles is the dominant cost of a fresh evaluation. `compile` parses once and returns a `Quickjs::Runnable` wrapping the serialized bytecode; `run(on:)` executes it on any VM of the same QuickJS build, skipping the parser. Useful when the same bundle is evaluated repeatedly across short-lived VMs (test environments, page-per-VM web emulators).
+
+```rb
+runnable = Quickjs::VM.new.compile(File.read('big_bundle.js'), filename: 'big_bundle.js')
+
+vm = Quickjs::VM.new
+runnable.run(on: vm)                                     # use the given VM (no parse cost)
+runnable.run                                             # spin up a fresh VM with default options
+runnable.run(on: { features: [::Quickjs::POLYFILL_INTL] }) # ad-hoc VM with options
+```
+
+`Runnable#to_s` returns the underlying bytecode as a frozen ASCII-8BIT `String`, suitable for caching to memory or disk. `Quickjs::Runnable.new(bytecode_string)` reconstructs a `Runnable` from that blob — validation happens lazily at `run` time, so a corrupt or wrong-build blob surfaces as `Quickjs::RuntimeError` when executed. The bytecode format is tied to the QuickJS build, so include the gem version in your cache key if you persist across upgrades.
+
 #### `Quickjs::VM#call`: ⚡ Call a JS function directly with Ruby arguments
 
 ```rb
@@ -213,6 +228,37 @@ vm.eval_code('console.log("hello", 42)')
 # log.raw      #=> Array of raw Ruby values
 ```
 
+#### Memory management: 🔍 Inspect and control VM memory
+
+```rb
+vm = Quickjs::VM.new
+
+vm.memory_usage
+# => { malloc_size: Integer, malloc_limit: Integer, memory_used_size: Integer,
+#      atom_count: Integer, str_count: Integer, obj_count: Integer,
+#      prop_count: Integer, shape_count: Integer,
+#      js_func_count: Integer, js_func_code_size: Integer,
+#      c_func_count: Integer, array_count: Integer }
+
+vm.gc!             # trigger a QuickJS GC cycle; returns nil
+
+vm.memory_poisoned? #=> false (true once the VM has hit out-of-memory)
+```
+
+When the JS heap exhausts its memory limit, QuickJS enters a fragile state where further evaluation can segfault the process. `memory_poisoned?` flips to `true` after such an event, and subsequent `eval_code` / `call` calls raise `Quickjs::RuntimeError` immediately instead of risking a crash. Rescue it and recreate the VM.
+
+```rb
+vm = Quickjs::VM.new(memory_limit: 256 * 1024 * 1024)
+
+begin
+  vm.eval_code(js)
+rescue Quickjs::RuntimeError => e
+  raise unless vm.memory_poisoned?
+  vm = Quickjs::VM.new(memory_limit: 256 * 1024 * 1024)
+  retry
+end
+```
+
 ### Value Conversion
 
 | JavaScript | | Ruby | Note |

data/ext/quickjsrb/quickjsrb.c

@@ -28,6 +28,10 @@ static int dispatch_log(VMData *data, const char *severity, VALUE r_row);
 
 JSValue to_js_value(JSContext *ctx, VALUE r_value);
 VALUE to_rb_value(JSContext *ctx, JSValue j_val);
+static VALUE to_rb_value_inner(JSContext *ctx, JSValue j_val, VALUE r_visited);
+static VALUE vm_m_memoryUsage(VALUE r_self);
+static VALUE vm_m_runGC(VALUE r_self);
+static VALUE vm_m_memoryPoisoned(VALUE r_self);
 
 JSValue j_error_from_ruby_error(JSContext *ctx, VALUE r_error)
 {
@@ -187,12 +191,24 @@ VALUE to_r_json(JSContext *ctx, JSValue j_val)
 {
   JSValue j_stringified = JS_JSONStringify(ctx, j_val, JS_UNDEFINED, JS_UNDEFINED);
 
+  // JSON.stringify throws on circular structures (e.g. jQuery objects'
+  // prevObject chain). Clear the pending exception so it doesn't poison
+  // subsequent eval, and return nil so callers fall through to "couldn't
+  // parse" handling rather than crashing on rb_str_new2(NULL) below.
+  if (JS_IsException(j_stringified))
+  {
+    JS_FreeValue(ctx, j_stringified);
+    JSValue j_pending = JS_GetException(ctx);
+    JS_FreeValue(ctx, j_pending);
+    return Qnil;
+  }
+
   const char *msg = JS_ToCString(ctx, j_stringified);
+  JS_FreeValue(ctx, j_stringified);
+  if (msg == NULL)
+    return Qnil;
   VALUE r_str = rb_str_new2(msg);
   JS_FreeCString(ctx, msg);
-
-  JS_FreeValue(ctx, j_stringified);
-
   return r_str;
 }
 
@@ -212,7 +228,7 @@ static int js_is_plain_object(JSContext *ctx, JSValue j_val)
   return result;
 }
 
-static VALUE js_array_to_rb(JSContext *ctx, JSValue j_val)
+static VALUE js_array_to_rb(JSContext *ctx, JSValue j_val, VALUE r_visited)
 {
   JSValue j_length = JS_GetPropertyStr(ctx, j_val, "length");
   uint32_t length = 0;
@@ -223,13 +239,13 @@ static VALUE js_array_to_rb(JSContext *ctx, JSValue j_val)
   for (uint32_t i = 0; i < length; i++)
   {
     JSValue j_elem = JS_GetPropertyUint32(ctx, j_val, i);
-    rb_ary_push(r_array, to_rb_value(ctx, j_elem));
+    rb_ary_push(r_array, to_rb_value_inner(ctx, j_elem, r_visited));
     JS_FreeValue(ctx, j_elem);
   }
   return r_array;
 }
 
-static VALUE js_plain_object_to_rb(JSContext *ctx, JSValue j_val)
+static VALUE js_plain_object_to_rb(JSContext *ctx, JSValue j_val, VALUE r_visited)
 {
   JSPropertyEnum *ptab;
   uint32_t plen;
@@ -241,7 +257,7 @@ static VALUE js_plain_object_to_rb(JSContext *ctx, JSValue j_val)
   {
     const char *key = JS_AtomToCString(ctx, ptab[i].atom);
     JSValue j_prop = JS_GetProperty(ctx, j_val, ptab[i].atom);
-    rb_hash_aset(r_hash, rb_str_new2(key), to_rb_value(ctx, j_prop));
+    rb_hash_aset(r_hash, rb_str_new2(key), to_rb_value_inner(ctx, j_prop, r_visited));
     JS_FreeCString(ctx, key);
     JS_FreeValue(ctx, j_prop);
   }
@@ -250,6 +266,11 @@ static VALUE js_plain_object_to_rb(JSContext *ctx, JSValue j_val)
 }
 
 VALUE to_rb_value(JSContext *ctx, JSValue j_val)
+{
+  return to_rb_value_inner(ctx, j_val, Qnil);
+}
+
+static VALUE to_rb_value_inner(JSContext *ctx, JSValue j_val, VALUE r_visited)
 {
   switch (JS_VALUE_GET_NORM_TAG(j_val))
   {
@@ -270,7 +291,11 @@ VALUE to_rb_value(JSContext *ctx, JSValue j_val)
     return JS_ToBool(ctx, j_val) > 0 ? Qtrue : Qfalse;
   }
   case JS_TAG_STRING:
+  case JS_TAG_STRING_ROPE:
   {
+    // QuickJS keeps long `s += chunk` chains as a rope (JS_TAG_STRING_ROPE)
+    // until something materialises them. JS_ToCStringLen flattens ropes
+    // transparently, so both tags share the same conversion path.
     size_t len;
     const char *str = JS_ToCStringLen(ctx, &len, j_val);
     if (str == NULL)
@@ -340,30 +365,38 @@ VALUE to_rb_value(JSContext *ctx, JSValue j_val)
         return r_maybe_file;
     }
 
+    // Below this point, conversion recurses into own properties / elements
+    // via to_rb_value_inner. Track JS object pointers to break cycles —
+    // re-entering the same object returns nil instead of blowing the stack.
+    if (NIL_P(r_visited))
+      r_visited = rb_hash_new();
+    VALUE r_visit_key = ULL2NUM((uintptr_t)JS_VALUE_GET_PTR(j_val));
+    if (RTEST(rb_hash_lookup(r_visited, r_visit_key)))
+      return Qnil;
+    rb_hash_aset(r_visited, r_visit_key, Qtrue);
+
     if (JS_IsArray(ctx, j_val))
-      return js_array_to_rb(ctx, j_val);
+      return js_array_to_rb(ctx, j_val, r_visited);
 
     if (js_is_plain_object(ctx, j_val))
-      return js_plain_object_to_rb(ctx, j_val);
-
-    // Fallback: non-plain objects (Date, RegExp, Map, class instances, functions, etc.)
-    VALUE r_str = to_r_json(ctx, j_val);
-
-    if (rb_funcall(r_str, rb_intern("=="), 1, rb_str_new2("undefined")))
-    {
-      return QUICKJSRB_SYM(undefinedId);
-    }
-
-    int couldntParse;
-    VALUE r_result = rb_protect(r_try_json_parse, r_str, &couldntParse);
-    if (couldntParse)
-    {
-      return Qnil;
-    }
-    else
+      return js_plain_object_to_rb(ctx, j_val, r_visited);
+
+    // Non-plain objects (Date, RegExp, Map, class instances, etc.).
+    // If the object opts in to a JSON representation via toJSON (e.g. Date),
+    // honour it — recurse on the returned value. Otherwise dump own enumerable
+    // string-keyed properties; this is faster than the JSON round-trip and
+    // preserves `undefined` values nested inside class instances.
+    JSValue j_toJSON = JS_GetPropertyStr(ctx, j_val, "toJSON");
+    if (JS_IsFunction(ctx, j_toJSON))
     {
+      JSValue j_jsonValue = JS_Call(ctx, j_toJSON, j_val, 0, NULL);
+      JS_FreeValue(ctx, j_toJSON);
+      VALUE r_result = to_rb_value_inner(ctx, j_jsonValue, r_visited);
+      JS_FreeValue(ctx, j_jsonValue);
       return r_result;
     }
+    JS_FreeValue(ctx, j_toJSON);
+    return js_plain_object_to_rb(ctx, j_val, r_visited);
   }
   case JS_TAG_NULL:
     return Qnil;
@@ -419,6 +452,14 @@ VALUE to_rb_value(JSContext *ctx, JSValue j_val)
       {
         r_error_class = QUICKJSRB_ERROR_FOR(QUICKJSRB_INTERRUPTED_ERROR);
       }
+      else if (strcmp(errorClassName, "InternalError") == 0 && strstr(errorClassMessage, "out of memory") != NULL)
+      {
+        // Once OOM has fired, the QuickJS heap is in a state where another
+        // throw inside the parser-error path can corrupt the shape table and
+        // segfault. Mark the VM so further eval/call calls refuse cleanly.
+        data->oom_poisoned = true;
+        r_error_class = QUICKJSRB_ERROR_FOR(QUICKJSRB_ROOT_RUNTIME_ERROR);
+      }
       else
       {
         r_error_class = QUICKJSRB_ERROR_FOR(QUICKJSRB_ROOT_RUNTIME_ERROR);
@@ -755,6 +796,40 @@ static JSValue js_console_error(JSContext *ctx, JSValueConst this, int argc, JSV
   return js_quickjsrb_log(ctx, this, argc, argv, "error");
 }
 
+// Polyfill bytecode load + eval is the heavy part of VM construction
+// (POLYFILL_INTL alone is ~140ms — FormatJS locale data + IANA TZ tables).
+// Run it 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 polyfills are pure JS
+// (FormatJS / file / encoding / URL bundles) 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
+{
+  JSContext *ctx;
+  const uint8_t *buf;
+  size_t buf_len;
+  JSValue result;
+};
+
+static void *polyfill_load_no_gvl(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
+  return NULL;
+}
+
+static JSValue load_polyfill_bytecode(JSContext *ctx, const uint8_t *buf, size_t buf_len)
+{
+  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;
+}
+
 static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
 {
   VALUE r_opts;
@@ -820,15 +895,13 @@ static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
     JSValue j_defineIntl = JS_Eval(data->context, defineIntl, strlen(defineIntl), "<vm>", JS_EVAL_TYPE_GLOBAL);
     JS_FreeValue(data->context, j_defineIntl);
 
-    JSValue j_polyfillIntlObject = JS_ReadObject(data->context, &qjsc_polyfill_intl_en_min, qjsc_polyfill_intl_en_min_size, JS_READ_OBJ_BYTECODE);
-    JSValue j_polyfillIntlResult = JS_EvalFunction(data->context, j_polyfillIntlObject); // Frees polyfillIntlObject
+    JSValue j_polyfillIntlResult = load_polyfill_bytecode(data->context, &qjsc_polyfill_intl_en_min, qjsc_polyfill_intl_en_min_size);
     JS_FreeValue(data->context, j_polyfillIntlResult);
   }
 
   if (RTEST(rb_funcall(r_features, rb_intern("include?"), 1, QUICKJSRB_SYM(featurePolyfillFileId))))
   {
-    JSValue j_polyfillFileObject = JS_ReadObject(data->context, &qjsc_polyfill_file_min, qjsc_polyfill_file_min_size, JS_READ_OBJ_BYTECODE);
-    JSValue j_polyfillFileResult = JS_EvalFunction(data->context, j_polyfillFileObject);
+    JSValue j_polyfillFileResult = load_polyfill_bytecode(data->context, &qjsc_polyfill_file_min, qjsc_polyfill_file_min_size);
     JS_FreeValue(data->context, j_polyfillFileResult);
 
     quickjsrb_init_file_proxy(data);
@@ -836,15 +909,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_polyfillEncodingObject = JS_ReadObject(data->context, &qjsc_polyfill_encoding_min, qjsc_polyfill_encoding_min_size, JS_READ_OBJ_BYTECODE);
-    JSValue j_polyfillEncodingResult = JS_EvalFunction(data->context, j_polyfillEncodingObject);
+    JSValue j_polyfillEncodingResult = load_polyfill_bytecode(data->context, &qjsc_polyfill_encoding_min, qjsc_polyfill_encoding_min_size);
     JS_FreeValue(data->context, j_polyfillEncodingResult);
   }
 
   if (RTEST(rb_funcall(r_features, rb_intern("include?"), 1, QUICKJSRB_SYM(featurePolyfillUrlId))))
   {
-    JSValue j_polyfillUrlObject = JS_ReadObject(data->context, &qjsc_polyfill_url_min, qjsc_polyfill_url_min_size, JS_READ_OBJ_BYTECODE);
-    JSValue j_polyfillUrlResult = JS_EvalFunction(data->context, j_polyfillUrlObject);
+    JSValue j_polyfillUrlResult = load_polyfill_bytecode(data->context, &qjsc_polyfill_url_min, qjsc_polyfill_url_min_size);
     JS_FreeValue(data->context, j_polyfillUrlResult);
   }
 
@@ -853,6 +924,10 @@ 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.
   JSValue j_console = JS_NewObject(data->context);
   JS_SetPropertyStr(
       data->context, j_console, "log",
@@ -900,35 +975,69 @@ static VALUE to_rb_return_value(JSContext *ctx, JSValue j_val)
   return result;
 }
 
-static VALUE vm_m_evalCode(int argc, VALUE *argv, VALUE r_self)
+static void check_oom_poisoned(VMData *data)
 {
-  VMData *data;
-  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
-
-  VALUE r_code, r_opts;
-  rb_scan_args(argc, argv, "1:", &r_code, &r_opts);
+  if (data->oom_poisoned)
+  {
+    VALUE r_msg = rb_str_new2("VM is poisoned: a previous evaluation hit out-of-memory; further evaluation may segfault. Recreate the Quickjs::VM.");
+    rb_exc_raise(rb_funcall(QUICKJSRB_ERROR_FOR(QUICKJSRB_ROOT_RUNTIME_ERROR), rb_intern("new"), 2, r_msg, Qnil));
+  }
+}
 
+// Validate that r_code is a String and resolve the :filename option (default "<code>")
+// from the keyword-args hash that rb_scan_args(... "1:") collects. Both eval_code and
+// compile share this argument shape.
+static const char *parse_code_and_filename(VALUE r_code, VALUE r_opts)
+{
   if (!RB_TYPE_P(r_code, T_STRING))
   {
     VALUE r_code_class = rb_class_name(CLASS_OF(r_code));
     rb_raise(rb_eTypeError, "JavaScript code must be a String, got %s", StringValueCStr(r_code_class));
   }
+  if (NIL_P(r_opts))
+    return "<code>";
+  VALUE r_filename = rb_hash_aref(r_opts, ID2SYM(rb_intern("filename")));
+  if (NIL_P(r_filename))
+    return "<code>";
+  Check_Type(r_filename, T_STRING);
+  return StringValueCStr(r_filename);
+}
+
+static void arm_eval_timer(VMData *data)
+{
+  clock_gettime(CLOCK_MONOTONIC, &data->eval_time->started_at);
+  JS_SetInterruptHandler(JS_GetRuntime(data->context), interrupt_handler, data->eval_time);
+}
+
+static VALUE vm_m_evalCode(int argc, VALUE *argv, VALUE r_self)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+
+  check_oom_poisoned(data);
+
+  VALUE r_code, r_opts;
+  rb_scan_args(argc, argv, "1:", &r_code, &r_opts);
+  const char *filename = parse_code_and_filename(r_code, r_opts);
 
-  const char *filename = "<code>";
+  bool async_mode = true;
   if (!NIL_P(r_opts))
   {
-    VALUE r_filename = rb_hash_aref(r_opts, ID2SYM(rb_intern("filename")));
-    if (!NIL_P(r_filename))
-    {
-      Check_Type(r_filename, T_STRING);
-      filename = StringValueCStr(r_filename);
-    }
+    VALUE r_async = rb_hash_aref(r_opts, ID2SYM(rb_intern("async")));
+    if (r_async == Qfalse)
+      async_mode = false;
   }
 
-  clock_gettime(CLOCK_MONOTONIC, &data->eval_time->started_at);
-  JS_SetInterruptHandler(JS_GetRuntime(data->context), interrupt_handler, data->eval_time);
+  arm_eval_timer(data);
 
   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
@@ -938,6 +1047,74 @@ static VALUE vm_m_evalCode(int argc, VALUE *argv, VALUE r_self)
   return to_rb_return_value(data->context, j_returnedValue);
 }
 
+static VALUE vm_m_compile(int argc, VALUE *argv, VALUE r_self)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+
+  VALUE r_code, r_opts;
+  rb_scan_args(argc, argv, "1:", &r_code, &r_opts);
+  const char *filename = parse_code_and_filename(r_code, r_opts);
+
+  arm_eval_timer(data);
+
+  StringValue(r_code);
+  JSValue j_func = JS_Eval(data->context, RSTRING_PTR(r_code), RSTRING_LEN(r_code), filename,
+                           JS_EVAL_TYPE_GLOBAL | JS_EVAL_FLAG_ASYNC | JS_EVAL_FLAG_COMPILE_ONLY);
+  if (JS_IsException(j_func))
+  {
+    return to_rb_value(data->context, j_func); // raises Ruby exception
+  }
+
+  size_t out_len;
+  uint8_t *out_buf = JS_WriteObject(data->context, &out_len, j_func, JS_WRITE_OBJ_BYTECODE);
+  JS_FreeValue(data->context, j_func);
+  if (out_buf == NULL)
+  {
+    VALUE r_msg = rb_str_new2("failed to serialize compiled bytecode");
+    rb_exc_raise(rb_funcall(QUICKJSRB_ERROR_FOR(QUICKJSRB_ROOT_RUNTIME_ERROR), rb_intern("new"), 2, r_msg, Qnil));
+  }
+
+  VALUE r_bytecode = rb_str_new((const char *)out_buf, (long)out_len);
+  rb_enc_associate(r_bytecode, rb_ascii8bit_encoding());
+  js_free(data->context, out_buf);
+  return rb_obj_freeze(r_bytecode);
+}
+
+static VALUE vm_m_evalBytecode(VALUE r_self, VALUE r_bytecode)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+
+  if (!RB_TYPE_P(r_bytecode, T_STRING))
+  {
+    VALUE r_class = rb_class_name(CLASS_OF(r_bytecode));
+    rb_raise(rb_eTypeError, "Bytecode must be a String, got %s", StringValueCStr(r_class));
+  }
+
+  StringValue(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);
+  return to_rb_return_value(data->context, j_returnedValue);
+}
+
 static VALUE vm_m_defineGlobalFunction(int argc, VALUE *argv, VALUE r_self)
 {
   rb_need_block();
@@ -1070,6 +1247,8 @@ static VALUE vm_m_callGlobalFunction(int argc, VALUE *argv, VALUE r_self)
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
 
+  check_oom_poisoned(data);
+
   JSValue j_this = JS_UNDEFINED;
   JSValue j_func;
 
@@ -1297,11 +1476,53 @@ RUBY_FUNC_EXPORTED void Init_quickjsrb(void)
   rb_define_alloc_func(r_class_vm, vm_alloc);
   rb_define_method(r_class_vm, "initialize", vm_m_initialize, -1);
   rb_define_method(r_class_vm, "eval_code", vm_m_evalCode, -1);
+  rb_define_private_method(r_class_vm, "_compile_to_bytecode", vm_m_compile, -1);
+  rb_define_private_method(r_class_vm, "_run_bytecode", vm_m_evalBytecode, 1);
   rb_define_method(r_class_vm, "call", vm_m_callGlobalFunction, -1);
   rb_define_method(r_class_vm, "define_function", vm_m_defineGlobalFunction, -1);
   rb_define_method(r_class_vm, "import", vm_m_import, -1);
   rb_define_method(r_class_vm, "module_loader", vm_m_get_module_loader, 0);
   rb_define_method(r_class_vm, "module_loader=", vm_m_set_module_loader, 1);
   rb_define_method(r_class_vm, "on_log", vm_m_on_log, 0);
+  rb_define_method(r_class_vm, "memory_usage", vm_m_memoryUsage, 0);
+  rb_define_method(r_class_vm, "gc!", vm_m_runGC, 0);
+  rb_define_method(r_class_vm, "memory_poisoned?", vm_m_memoryPoisoned, 0);
   r_define_log_class(r_class_vm);
 }
+
+static VALUE vm_m_memoryUsage(VALUE r_self)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+  JSMemoryUsage s;
+  JS_ComputeMemoryUsage(JS_GetRuntime(data->context), &s);
+  VALUE h = rb_hash_new();
+  rb_hash_aset(h, ID2SYM(rb_intern("malloc_size")), LL2NUM(s.malloc_size));
+  rb_hash_aset(h, ID2SYM(rb_intern("malloc_limit")), LL2NUM(s.malloc_limit));
+  rb_hash_aset(h, ID2SYM(rb_intern("memory_used_size")), LL2NUM(s.memory_used_size));
+  rb_hash_aset(h, ID2SYM(rb_intern("atom_count")), LL2NUM(s.atom_count));
+  rb_hash_aset(h, ID2SYM(rb_intern("str_count")), LL2NUM(s.str_count));
+  rb_hash_aset(h, ID2SYM(rb_intern("obj_count")), LL2NUM(s.obj_count));
+  rb_hash_aset(h, ID2SYM(rb_intern("prop_count")), LL2NUM(s.prop_count));
+  rb_hash_aset(h, ID2SYM(rb_intern("shape_count")), LL2NUM(s.shape_count));
+  rb_hash_aset(h, ID2SYM(rb_intern("js_func_count")), LL2NUM(s.js_func_count));
+  rb_hash_aset(h, ID2SYM(rb_intern("js_func_code_size")), LL2NUM(s.js_func_code_size));
+  rb_hash_aset(h, ID2SYM(rb_intern("c_func_count")), LL2NUM(s.c_func_count));
+  rb_hash_aset(h, ID2SYM(rb_intern("array_count")), LL2NUM(s.array_count));
+  return h;
+}
+
+static VALUE vm_m_runGC(VALUE r_self)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+  JS_RunGC(JS_GetRuntime(data->context));
+  return Qnil;
+}
+
+static VALUE vm_m_memoryPoisoned(VALUE r_self)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+  return data->oom_poisoned ? Qtrue : Qfalse;
+}

data/ext/quickjsrb/quickjsrb.h

@@ -2,6 +2,8 @@
 #define QUICKJSRB_H 1
 
 #include "ruby.h"
+#include "ruby/encoding.h"
+#include "ruby/thread.h"
 
 #include "quickjs.h"
 #include "quickjs-libc.h"
@@ -56,6 +58,12 @@ typedef struct VMData
   VALUE alive_objects;
   VALUE module_loader;
   JSValue j_file_proxy_creator;
+  // Once the runtime has hit JS-level "out of memory", the QuickJS heap is in
+  // a fragile state where further evaluation can trigger a use-after-free in
+  // the parser-error-during-OOM cascade (segfault inside js_shape_hash_unlink).
+  // Trip this flag so subsequent eval_code/call calls refuse cleanly with a
+  // Ruby exception instead of risking a process crash.
+  bool oom_poisoned;
 } VMData;
 
 static void vm_free(void *ptr)
@@ -109,6 +117,18 @@ static const rb_data_type_t vm_type = {
     .flags = RUBY_TYPED_FREE_IMMEDIATELY,
 };
 
+struct vm_create_args
+{
+  JSContext *context;
+};
+
+static void *vm_create_no_gvl(void *p)
+{
+  struct vm_create_args *args = p;
+  args->context = JS_NewContext(JS_NewRuntime());
+  return NULL;
+}
+
 static VALUE vm_alloc(VALUE r_self)
 {
   VMData *data;
@@ -118,12 +138,17 @@ static VALUE vm_alloc(VALUE r_self)
   data->alive_objects = rb_hash_new();
   data->module_loader = Qnil;
   data->j_file_proxy_creator = JS_UNDEFINED;
+  data->oom_poisoned = false;
 
   EvalTime *eval_time = malloc(sizeof(EvalTime));
   data->eval_time = eval_time;
 
-  JSRuntime *runtime = JS_NewRuntime();
-  data->context = JS_NewContext(runtime);
+  // JSRuntime / JSContext creation is pure QuickJS C work — no Ruby state
+  // touched. Release the GVL so a background warmer thread can run this in
+  // parallel with the main thread on multi-core hosts.
+  struct vm_create_args args = {NULL};
+  rb_thread_call_without_gvl(vm_create_no_gvl, &args, NULL, NULL);
+  data->context = args.context;
 
   return obj;
 }