quickjs 0.15.1 → 0.17.0.pre

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);
@@ -470,6 +511,59 @@ VALUE to_rb_value(JSContext *ctx, JSValue j_val)
   }
 }
 
+struct module_loader_call_args
+{
+  VALUE proc;
+  VALUE r_module_name;
+};
+
+static VALUE r_module_loader_call(VALUE r_args_val)
+{
+  struct module_loader_call_args *args = (struct module_loader_call_args *)r_args_val;
+  return rb_funcall(args->proc, rb_intern("call"), 1, args->r_module_name);
+}
+
+static JSModuleDef *quickjsrb_module_loader(JSContext *ctx, const char *module_name, void *opaque, JSValueConst attributes)
+{
+  VMData *data = JS_GetContextOpaque(ctx);
+  if (NIL_P(data->module_loader))
+    return js_module_loader(ctx, module_name, opaque, attributes);
+
+  struct module_loader_call_args args = {data->module_loader, rb_str_new_cstr(module_name)};
+  int state;
+  VALUE r_source = rb_protect(r_module_loader_call, (VALUE)&args, &state);
+  if (state)
+  {
+    VALUE r_error = rb_errinfo();
+    rb_set_errinfo(Qnil);
+    JSValue j_error = j_error_from_ruby_error(ctx, r_error);
+    JS_Throw(ctx, j_error);
+    return NULL;
+  }
+
+  if (NIL_P(r_source) || r_source == Qfalse)
+  {
+    JS_ThrowReferenceError(ctx, "module loader returned no source for '%s'", module_name);
+    return NULL;
+  }
+
+  if (!RB_TYPE_P(r_source, T_STRING))
+  {
+    JS_ThrowTypeError(ctx, "module loader must return a String or nil, got %s", rb_obj_classname(r_source));
+    return NULL;
+  }
+
+  JSValue j_func = JS_Eval(ctx, RSTRING_PTR(r_source), RSTRING_LEN(r_source), module_name,
+                           JS_EVAL_TYPE_MODULE | JS_EVAL_FLAG_COMPILE_ONLY);
+  if (JS_IsException(j_func))
+    return NULL;
+
+  js_module_set_import_meta(ctx, j_func, FALSE, FALSE);
+  JSModuleDef *m = JS_VALUE_GET_PTR(j_func);
+  JS_FreeValue(ctx, j_func);
+  return m;
+}
+
 static VALUE r_try_call_proc(VALUE r_try_args)
 {
   return rb_funcall(
@@ -702,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;
@@ -732,7 +860,7 @@ static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
   JS_SetMemoryLimit(runtime, NUM2UINT(r_memory_limit));
   JS_SetMaxStackSize(runtime, NUM2UINT(r_max_stack_size));
 
-  JS_SetModuleLoaderFunc2(runtime, NULL, js_module_loader, js_module_check_attributes, NULL);
+  JS_SetModuleLoaderFunc2(runtime, NULL, quickjsrb_module_loader, js_module_check_attributes, NULL);
   js_std_init_handlers(runtime);
 
   JSValue j_global = JS_GetGlobalObject(data->context);
@@ -767,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);
@@ -783,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);
   }
 
@@ -800,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",
@@ -847,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);
 
-  const char *filename = "<code>";
+  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);
+
+  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
@@ -885,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();
@@ -1017,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;
 
@@ -1143,6 +1375,25 @@ 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_set_module_loader(VALUE r_self, VALUE r_loader)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+
+  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");
+
+  data->module_loader = r_loader;
+  return r_loader;
+}
+
+static VALUE vm_m_get_module_loader(VALUE r_self)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+  return data->module_loader;
+}
+
 static VALUE vm_m_import(int argc, VALUE *argv, VALUE r_self)
 {
   VALUE r_import_string, r_opts;
@@ -1150,7 +1401,8 @@ static VALUE vm_m_import(int argc, VALUE *argv, VALUE r_self)
   if (NIL_P(r_opts))
     r_opts = rb_hash_new();
   VALUE r_from = rb_hash_aref(r_opts, ID2SYM(rb_intern("from")));
-  if (NIL_P(r_from))
+  VALUE r_filename = rb_hash_aref(r_opts, ID2SYM(rb_intern("filename")));
+  if (NIL_P(r_from) && NIL_P(r_filename))
   {
     VALUE r_error_message = rb_str_new2("missing import source");
     rb_exc_raise(rb_funcall(QUICKJSRB_ERROR_FOR(QUICKJSRB_ROOT_RUNTIME_ERROR), rb_intern("new"), 2, r_error_message, Qnil));
@@ -1161,16 +1413,24 @@ static VALUE vm_m_import(int argc, VALUE *argv, VALUE r_self)
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
 
-  char *filename = random_string();
-  char *source = StringValueCStr(r_from);
-  JSValue module = JS_Eval(data->context, source, strlen(source), filename, JS_EVAL_TYPE_MODULE | JS_EVAL_FLAG_COMPILE_ONLY);
-  if (JS_IsException(module))
+  char *filename;
+  if (!NIL_P(r_filename))
+  {
+    filename = StringValueCStr(r_filename);
+  }
+  else
   {
+    filename = random_string();
+    char *source = StringValueCStr(r_from);
+    JSValue module = JS_Eval(data->context, source, strlen(source), filename, JS_EVAL_TYPE_MODULE | JS_EVAL_FLAG_COMPILE_ONLY);
+    if (JS_IsException(module))
+    {
+      JS_FreeValue(data->context, module);
+      return to_rb_value(data->context, module);
+    }
+    js_module_set_import_meta(data->context, module, TRUE, FALSE);
     JS_FreeValue(data->context, module);
-    return to_rb_value(data->context, module);
   }
-  js_module_set_import_meta(data->context, module, TRUE, FALSE);
-  JS_FreeValue(data->context, module);
 
   VALUE r_import_settings = rb_funcall(
       rb_const_get(rb_cClass, rb_intern("Quickjs")),
@@ -1216,9 +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"
@@ -54,7 +56,14 @@ typedef struct VMData
   struct EvalTime *eval_time;
   VALUE log_listener;
   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)
@@ -85,6 +94,7 @@ static void vm_mark(void *ptr)
   rb_gc_mark_movable(data->defined_functions);
   rb_gc_mark_movable(data->log_listener);
   rb_gc_mark_movable(data->alive_objects);
+  rb_gc_mark_movable(data->module_loader);
 }
 
 static void vm_compact(void *ptr)
@@ -93,6 +103,7 @@ static void vm_compact(void *ptr)
   data->defined_functions = rb_gc_location(data->defined_functions);
   data->log_listener = rb_gc_location(data->log_listener);
   data->alive_objects = rb_gc_location(data->alive_objects);
+  data->module_loader = rb_gc_location(data->module_loader);
 }
 
 static const rb_data_type_t vm_type = {
@@ -106,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;
@@ -113,13 +136,19 @@ static VALUE vm_alloc(VALUE r_self)
   data->defined_functions = rb_hash_new();
   data->log_listener = Qnil;
   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;
 }