FEATURE: add Context#call_async and Context#eval_async

These work like call and eval, except that when the result is a promise they block until it settles and return the settled value. A rejected promise raises MiniRacer::RuntimeError, like a synchronous throw, and non-promise results are returned as-is.

While waiting, the V8 thread alternates between draining the microtask queue and pumping the platform message loop in wait-for-work mode, so there is no polling: microtask chains settle immediately, and delayed or background work (Atomics.waitAsync timers, async wasm compilation) wakes the loop when its tasks are posted.

TerminateExecution doesn't wake a parked message loop, and when called while no JS is running it only queues a termination for the next JS entry. v8_terminate_execution therefore also sets a flag on the State and posts a no-op wakeup task, so the timeout watchdog, Context#stop and Ruby thread interrupts can all end a pending await. A promise that can never settle blocks like an infinite loop until one of those stops it.

The new methods use two new request opcodes ('D' and 'F') sharing the existing v8_call/v8_eval implementations. Ruby callbacks invoked while waiting go through the usual nested-dispatch path, and exceptions they raise propagate out through the promise rejection. TruffleRuby raises MiniRacer::Error.

Author: davidtaylorhq

CHANGELOG

@@ -1,4 +1,5 @@
 - Unreleased
+  - Add `Context#call_async` and `Context#eval_async`: like `call`/`eval` but block until a returned Promise settles and return the settled value; rejections raise `MiniRacer::RuntimeError`
   - Fix a race introduced in 0.21.4 where a request sent right after a nested dispatch (e.g. `perform_microtask_checkpoint` or a nested `call` from an attached callback) could be dropped, deadlocking the context
 
 - 0.21.4 - 24-06-2026

README.md

@@ -348,6 +348,33 @@ Performance is slightly better than running `context.eval("hello('George')")` si
 * compilation of eval'd string is avoided
 * function arguments don't need to be converted to JSON
 
+### Promises: call_async and eval_async
+
+`call_async` and `eval_async` work like `call` and `eval`, but when the result is a
+Promise they block until it settles and return the settled value. A rejected
+promise raises `MiniRacer::RuntimeError`, just like a synchronous `throw`:
+
+```ruby
+context = MiniRacer::Context.new
+context.eval("async function f(x) { await Promise.resolve(); return x * 2 }")
+context.call_async("f", 21)
+# => 42
+
+context.eval_async("(async () => 6 * 7)()")
+# => 42
+
+context.eval("async function boom() { throw new Error('kaboom') }")
+context.call_async("boom")
+# => raises MiniRacer::RuntimeError (Error: kaboom)
+```
+
+Non-Promise results pass through unchanged, so `call_async` is a drop-in
+superset of `call` (same for `eval_async`/`eval`).
+
+A promise that never settles blocks forever, just like an infinite loop. The
+`timeout:` option and `Context#stop` both interrupt it, raising
+`MiniRacer::ScriptTerminatedError`.
+
 ### Microtask checkpoints
 
 V8 drains its microtask queue (e.g. callbacks queued via `Promise.resolve().then(...)`) automatically when script execution returns to the embedder, so most code "just works":

ext/mini_racer_extension/mini_racer_extension.c

@@ -810,7 +810,9 @@ static void dispatch1(Context *c, const uint8_t *p, size_t n)
     switch (*p) {
     case 'A': return v8_attach(c->pst, p+1, n-1);
     case 'C': return v8_timedwait(c, p+1, n-1, v8_call);
+    case 'D': return v8_timedwait(c, p+1, n-1, v8_call_async);
     case 'E': return v8_timedwait(c, p+1, n-1, v8_eval);
+    case 'F': return v8_timedwait(c, p+1, n-1, v8_eval_async);
     case 'H': return v8_heap_snapshot(c->pst);
     case 'M': return v8_perform_microtask_checkpoint(c->pst);
     case 'P': return v8_pump_message_loop(c->pst);
@@ -888,7 +890,8 @@ void v8_dispatch(Context *c)
     pthread_mutex_unlock(&c->mtx);
 }
 
-// only called when inside v8_call, v8_eval, or v8_pump_message_loop
+// only called when inside v8_call, v8_eval (and their async variants),
+// or v8_pump_message_loop
 void v8_roundtrip(Context *c, const uint8_t **p, size_t *n)
 {
     pthread_mutex_lock(&c->mtx);
@@ -1654,7 +1657,7 @@ static VALUE context_stop(VALUE self)
     return Qnil;
 }
 
-static VALUE context_call(int argc, VALUE *argv, VALUE self)
+static VALUE context_call_common(int argc, VALUE *argv, VALUE self, char op)
 {
     VALUE name, args;
     VALUE a, e;
@@ -1665,8 +1668,8 @@ static VALUE context_call(int argc, VALUE *argv, VALUE self)
     rb_scan_args(argc, argv, "1*", &name, &args);
     Check_Type(name, T_STRING);
     rb_ary_unshift(args, name);
-    // request is (C)all, [name, args...] array
-    ser_init1(&s, 'C');
+    // request is (C)all or async (D) call, [name, args...] array
+    ser_init1(&s, op);
     if (serialize(&s, args)) {
         ser_reset(&s);
         rb_raise(runtime_error, "Context.call: %s", s.err);
@@ -1678,7 +1681,17 @@ static VALUE context_call(int argc, VALUE *argv, VALUE self)
     return rb_ary_pop(a);
 }
 
-static VALUE context_eval(int argc, VALUE *argv, VALUE self)
+static VALUE context_call(int argc, VALUE *argv, VALUE self)
+{
+    return context_call_common(argc, argv, self, 'C');
+}
+
+static VALUE context_call_async(int argc, VALUE *argv, VALUE self)
+{
+    return context_call_common(argc, argv, self, 'D');
+}
+
+static VALUE context_eval_common(int argc, VALUE *argv, VALUE self, char op)
 {
     VALUE a, e, source, filename, kwargs;
     Context *c;
@@ -1693,8 +1706,8 @@ static VALUE context_eval(int argc, VALUE *argv, VALUE self)
     if (NIL_P(filename))
         filename = rb_str_new_cstr("<eval>");
     Check_Type(filename, T_STRING);
-    // request is (E)val, [filename, source] array
-    ser_init1(&s, 'E');
+    // request is (E)val or async (F) eval, [filename, source] array
+    ser_init1(&s, op);
     ser_array_begin(&s, 2);
     add_string(&s, filename);
     add_string(&s, source);
@@ -1706,6 +1719,16 @@ static VALUE context_eval(int argc, VALUE *argv, VALUE self)
     return rb_ary_pop(a);
 }
 
+static VALUE context_eval(int argc, VALUE *argv, VALUE self)
+{
+    return context_eval_common(argc, argv, self, 'E');
+}
+
+static VALUE context_eval_async(int argc, VALUE *argv, VALUE self)
+{
+    return context_eval_common(argc, argv, self, 'F');
+}
+
 static VALUE context_heap_stats(VALUE self)
 {
     VALUE a, h, k, v;
@@ -2146,7 +2169,9 @@ void Init_mini_racer_extension(void)
     rb_define_method(c, "dispose", context_dispose, 0);
     rb_define_method(c, "stop", context_stop, 0);
     rb_define_method(c, "call", context_call, -1);
+    rb_define_method(c, "call_async", context_call_async, -1);
     rb_define_method(c, "eval", context_eval, -1);
+    rb_define_method(c, "eval_async", context_eval_async, -1);
     rb_define_method(c, "heap_stats", context_heap_stats, 0);
     rb_define_method(c, "heap_snapshot", context_heap_snapshot, 0);
     rb_define_method(c, "perform_microtask_checkpoint", context_perform_microtask_checkpoint, 0);

ext/mini_racer_extension/mini_racer_v8.cc

@@ -2,6 +2,7 @@
 #include "v8-profiler.h"
 #include "libplatform/libplatform.h"
 #include "mini_racer_v8.h"
+#include <atomic>
 #include <memory>
 #include <vector>
 #include <cassert>
@@ -91,6 +92,8 @@ struct State
     Context *ruby_context;
     int64_t max_memory;
     int err_reason;
+    // TerminateExecution() while idle doesn't make IsExecutionTerminating() true
+    std::atomic<bool> terminate_requested;
     bool verbose_exceptions;
     std::vector<Callback*> callbacks;
     std::unique_ptr<v8::ArrayBuffer::Allocator> allocator;
@@ -586,8 +589,35 @@ extern "C" void v8_attach(State *pst, const uint8_t *p, size_t n)
     reply_retry(st, err);
 }
 
+// awaits |*result| if it's a promise; false means an exception is pending
+bool await_promise(State& st, v8::Local<v8::Value> *result)
+{
+    if (!(*result)->IsPromise()) return true;
+    auto promise = result->As<v8::Promise>();
+    for (;;) {
+        v8::MicrotasksScope::PerformCheckpoint(st.isolate);
+        switch (promise->State()) {
+        case v8::Promise::kFulfilled:
+            *result = promise->Result();
+            return true;
+        case v8::Promise::kRejected:
+            st.isolate->ThrowException(promise->Result());
+            return false;
+        case v8::Promise::kPending:
+            break;
+        }
+        if (st.terminate_requested.load() || st.isolate->IsExecutionTerminating())
+            return false;
+        // blocks until the next task; v8_terminate_execution posts one to
+        // end the wait on timeout/stop/interrupt
+        v8::platform::PumpMessageLoop(
+            platform, st.isolate,
+            v8::platform::MessageLoopBehavior::kWaitForWork);
+    }
+}
+
 // response is errback [result, err] array
-extern "C" void v8_call(State *pst, const uint8_t *p, size_t n)
+void v8_call_impl(State *pst, const uint8_t *p, size_t n, bool await)
 {
     State& st = *pst;
     v8::TryCatch try_catch(st.isolate);
@@ -645,11 +675,13 @@ extern "C" void v8_call(State *pst, const uint8_t *p, size_t n)
         auto maybe_result_v = function->Call(st.context, obj, args.size(), args.data());
         v8::Local<v8::Value> result_v;
         if (!maybe_result_v.ToLocal(&result_v)) goto fail;
+        if (await && !await_promise(st, &result_v)) goto fail;
         result = sanitize(st, result_v);
     }
     cause = NO_ERROR;
 fail:
-    if (st.isolate->IsExecutionTerminating()) {
+    if (st.terminate_requested.exchange(false) ||
+        st.isolate->IsExecutionTerminating()) {
         st.isolate->CancelTerminateExecution();
         cause = st.err_reason ? st.err_reason : TERMINATED_ERROR;
         st.err_reason = NO_ERROR;
@@ -664,8 +696,18 @@ extern "C" void v8_call(State *pst, const uint8_t *p, size_t n)
     }
 }
 
+extern "C" void v8_call(State *pst, const uint8_t *p, size_t n)
+{
+    v8_call_impl(pst, p, n, false);
+}
+
+extern "C" void v8_call_async(State *pst, const uint8_t *p, size_t n)
+{
+    v8_call_impl(pst, p, n, true);
+}
+
 // response is errback [result, err] array
-extern "C" void v8_eval(State *pst, const uint8_t *p, size_t n)
+void v8_eval_impl(State *pst, const uint8_t *p, size_t n, bool await)
 {
     State& st = *pst;
     v8::TryCatch try_catch(st.isolate);
@@ -694,11 +736,13 @@ extern "C" void v8_eval(State *pst, const uint8_t *p, size_t n)
         cause = RUNTIME_ERROR;
         auto maybe_result_v = script->Run(st.context);
         if (!maybe_result_v.ToLocal(&result_v)) goto fail;
+        if (await && !await_promise(st, &result_v)) goto fail;
         result = sanitize(st, result_v);
     }
     cause = NO_ERROR;
 fail:
-    if (st.isolate->IsExecutionTerminating()) {
+    if (st.terminate_requested.exchange(false) ||
+        st.isolate->IsExecutionTerminating()) {
         st.isolate->CancelTerminateExecution();
         cause = st.err_reason ? st.err_reason : TERMINATED_ERROR;
         st.err_reason = NO_ERROR;
@@ -713,6 +757,16 @@ extern "C" void v8_eval(State *pst, const uint8_t *p, size_t n)
     }
 }
 
+extern "C" void v8_eval(State *pst, const uint8_t *p, size_t n)
+{
+    v8_eval_impl(pst, p, n, false);
+}
+
+extern "C" void v8_eval_async(State *pst, const uint8_t *p, size_t n)
+{
+    v8_eval_impl(pst, p, n, true);
+}
+
 extern "C" void v8_heap_stats(State *pst)
 {
     State& st = *pst;
@@ -800,7 +854,8 @@ extern "C" void v8_pump_message_loop(State *pst)
         if (try_catch.HasCaught()) goto fail;
     }
 fail:
-    if (st.isolate->IsExecutionTerminating()) {
+    if (st.terminate_requested.exchange(false) ||
+        st.isolate->IsExecutionTerminating()) {
         st.isolate->CancelTerminateExecution();
         st.err_reason = NO_ERROR;
     }
@@ -914,7 +969,8 @@ extern "C" void v8_snapshot(State *pst, const uint8_t *p, size_t n)
     }
     cause = NO_ERROR;
 fail:
-    if (st.isolate->IsExecutionTerminating()) {
+    if (st.terminate_requested.exchange(false) ||
+        st.isolate->IsExecutionTerminating()) {
         st.isolate->CancelTerminateExecution();
         cause = st.err_reason ? st.err_reason : TERMINATED_ERROR;
         st.err_reason = NO_ERROR;
@@ -984,7 +1040,8 @@ extern "C" void v8_warmup(State *pst, const uint8_t *p, size_t n)
     }
     cause = NO_ERROR;
 fail:
-    if (st.isolate->IsExecutionTerminating()) {
+    if (st.terminate_requested.exchange(false) ||
+        st.isolate->IsExecutionTerminating()) {
         st.isolate->CancelTerminateExecution();
         cause = st.err_reason ? st.err_reason : TERMINATED_ERROR;
         st.err_reason = NO_ERROR;
@@ -1008,17 +1065,27 @@ extern "C" void v8_low_memory_notification(State *pst)
     pst->isolate->LowMemoryNotification();
 }
 
-// called from ruby thread
+struct WakeupTask : public v8::Task
+{
+    void Run() final {}
+};
+
+// called from ruby or watchdog thread
 extern "C" void v8_terminate_execution(State *pst)
 {
+    pst->terminate_requested.store(true);
     pst->isolate->TerminateExecution();
+    // wake await_promise's message loop pump
+    platform->GetForegroundTaskRunner(pst->isolate)
+        ->PostTask(std::make_unique<WakeupTask>());
 }
 
 // called from ruby thread
 extern "C" void v8_cancel_terminate_execution(State *pst)
 {
     // TerminateExecution can race with V8 completing and queue a termination
     // for the next entry without IsExecutionTerminating() becoming true.
+    pst->terminate_requested.store(false);
     pst->isolate->CancelTerminateExecution();
 }
 

ext/mini_racer_extension/mini_racer_v8.h

@@ -39,7 +39,9 @@ struct State *v8_thread_init(struct Context *c, const uint8_t *snapshot_buf,
                              int verbose_exceptions); // calls v8_thread_main
 void v8_attach(struct State *pst, const uint8_t *p, size_t n);
 void v8_call(struct State *pst, const uint8_t *p, size_t n);
+void v8_call_async(struct State *pst, const uint8_t *p, size_t n);
 void v8_eval(struct State *pst, const uint8_t *p, size_t n);
+void v8_eval_async(struct State *pst, const uint8_t *p, size_t n);
 void v8_heap_stats(struct State *pst);
 void v8_heap_snapshot(struct State *pst);
 void v8_perform_microtask_checkpoint(struct State *pst);

lib/mini_racer/shared.rb

@@ -188,6 +188,14 @@ def call(function_name, *arguments)
       ensure_gc_thread if @ensure_gc_after_idle
     end
 
+    def eval_async(*)
+      raise MiniRacer::Error, "eval_async is not supported on TruffleRuby"
+    end
+
+    def call_async(*)
+      raise MiniRacer::Error, "call_async is not supported on TruffleRuby"
+    end
+
     def dispose
       return if @disposed
       isolate_mutex.synchronize do