native C modules have no cleanup hook that runs while the JSContext is still usable

[engsr6982]

Native C modules have no teardown hook that runs while their JSContext is still usable — module cleanup is deferred to JS_FreeRuntime (or never runs), leaking addon C++ state

Environment

• quickjs-ng master (2026-08): 5cbbc67 docs: add Vayu to projects (verified on v0.13.0 too)
• Verified on Windows/clang-cl; behavior is platform-independent
• Local measurement: JS_NewContext returns a context with reference count 551

Problem / current state

A native C module created with JS_NewCModule owns context-scoped resources that must be released at a well-defined point while the context is still usable — e.g. a C++ binding layer (jspp, Rust/nim bindings, plugin systems) that keeps class constructors, Global-style JSValues and callbacks bound to a per-context engine.

Today there is no such point:

1. Attaching a JSClassFinalizer object to the module's private_value only runs during JS_FreeRuntime's GC — after the embedder has already called JS_FreeContext; the context is no longer usable there (its global object is unreachable), so context JS APIs cannot be called safely.
2. Worse, if any JSValue is still referenced from C++ (a stored callback, a registered class ctor/proto, a Global<T>-equivalent), that finalizer never runs at all: debug builds end in assert(list_empty(&rt->gc_obj_list)), release builds silently leak every engine/bound JSValue for the host process lifetime.

Minimal observation (see repro below):

case-1: plain C module
  after host JS_FreeContext : module-finalizer=0     <-- the point where cleanup SHOULD run
  after JS_FreeRuntime      : module-finalizer=1     <-- actually runs here (context gone)

case-2: module + one JSValue pinned from C++
  after host JS_FreeContext : module-finalizer=0
  after JS_FreeRuntime      : module-finalizer=0     <-- never runs

Essence of the problem

Module teardown is gated on actual JSContext destruction, but a context created with JS_NewContext is effectively never destroyed by the embedder's JS_FreeContext:

• Every C function object holds JS_DupContext(ctx) as its realm — see p->u.cfunc.realm = JS_DupContext(ctx) in js_new_c_function. JS_NewContext therefore returns with a reference count of ~550 (measured 551), i.e. 1 (embedder) + all builtin C functions.
• A host's single JS_FreeContext only decrements (551 → 550) and early-returns; js_free_modules() is not reached, so module finalizers do not run.
• The context finally reaches 0 references only inside JS_FreeRuntime's GC as the builtin realm references are released — at which point the context (its global object, atoms, …) is already being torn down.
• With any C++-held JSValue the GC cannot collect that object, the context never reaches 0 references, and module teardown (and the leak check) never completes.

Because every C function stores a raw reference to the context, and JSValue after JS_FreeContext is a dangling pointer (unlike V8 handles there is no safe Reset), the only safe cleanup point is while the context is still alive — which currently never exists.

What was attempted

1. Addon-side hook via private_value class finalizer (no quickjs change) — too late (runtime GC) or never (pins); validated by repro.
2. Addon-side: stop C++ from pinning its own class objects (keep class ctor/proto owned by JS-side module refs; C++ keeps raw pointers) — fixes the engine-owned objects, verified, but provides no release point for user-held Global<T>/callback JSValues, and leaks between commits in a long-lived runtime.
3. JS_SetModuleFinalizer(m, fn) fired from js_free_module_def — the right hook shape (context-parameter finalizer, like Node's napi_add_env_cleanup_hook), no regression on api-test/lre-test/unit JS, ASan-clean, but its trigger is module-def destruction, which per the essence above is gated on real context destruction → still fires too late or never for the pinned case.
4. Eagerly running module teardown from JS_FreeContext when the embedder drops its reference — internal realm releases also call JS_FreeContext (hundreds per context), so module teardown would over-trigger and break normal evaluation (verified: api-test fails). Distinguishing the embedder call requires routing internal realm-release sites away from the public teardown path, which changes internal accounting semantics.

Difficulty / open design questions

• The embedder's JS_FreeContext is indistinguishable from an internal realm release by reference count, because realms inflate it. So "fire module cleanup when the host drops its last own reference" is not expressible with the current refcount alone.
• QuickJS deliberately lets functions live beyond the context via realms; contexts therefore intentionally survive the embedder's JS_FreeContext. Any change to realm accounting (e.g. not dup-ing the context into every C function realm) must preserve function-outlives-context semantics, or it will break real embedders.
• A clean fix should give native modules a "context teardown" notification that runs while the context is still usable, independent of how many internal realm references happen to be outstanding.

Impact scope

• Affected: every embedder that hosts native C modules (JS_NewCModule) whose modules keep context-scoped resources — JS binding layers (jspp, …), plugin systems, multi-context servers.
• Long-lived runtimes: every context that imports a native module leaks the module's C++ state for the runtime's lifetime (no finalizer ever runs). Debug builds assert; release builds leak silently; ASan does not report it (it is a never-free C++ leak, not an invalid access).
• Benign case: the qjs CLI and other short-lived processes — process exit reclaims everything, so the leak is harmless there. This is why the issue has gone unnoticed.

Proposed direction

Give native modules a deterministic teardown callback with a usable context, fired when the embedder releases the context — e.g.:

typedef int JSModuleFinalizerFunc(JSContext *ctx, JSModuleDef *m);
void JS_SetModuleFinalizer(JSModuleDef *m, JSModuleFinalizerFunc *finalizer);

with the open question of exactly when it fires, given that the context object legitimately survives the embedder's JS_FreeContext because of realm references. Candidate triggers:

1. Current: fire when the module def is destroyed (real context destruction) — minimal, but fires late/never per this report.
2. Fire when the embedder calls JS_FreeContext (the context may still be usable) — matches Node semantics; requires distinguishing the embedder call from internal realm releases.
3. Fix the realm accounting so a context is actually destroyed by the embedder's JS_FreeContext — the largest semantic change.

Related prior art: Node napi_add_env_cleanup_hook / napi_add_env_cleanup_hook runs the addon cleanup while the environment is still alive.

[engsr6982]

Minimal repro

// repro_cmodule_cleanup.c — standalone minimal repro.
//
// Problem: a native C module (JS_NewCModule) has no cleanup hook that runs
// while its JSContext is still usable. JS bindings must release
// context-scoped C++ resources at the ONE moment they can still touch the
// context. Without a hook, module teardown is deferred to JS_FreeRuntime's
// GC (the context reference count is inflated by every C function's realm
// dup), and — worse — if any JSValue is still referenced from C++ (a
// Global<T>, a stored callback), teardown never happens and quickjs ends in
// `assert(list_empty(&rt->gc_obj_list))` = a real C++ leak.
//
// Fix verified here: (1) JS_SetModuleFinalizer(m, fn) provides the hook;
// (2) JS_FreeContext now tears down the module graph as soon as the embedder
// drops its own context reference (context still alive) instead of waiting
// for the runtime GC — so the finalizer runs with a usable context and can
// release the addon's pinned JSValues deterministically.
//
// Build / run (run in Debug, Release AND ASan — case-2 must not assert):
//   cmake -S . -B _build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DQJS_BUILD_LIBC=ON
//   cmake --build _build --target qjs
//   clang-cl /TC /MD /Z7 -I. repro_cmodule_cleanup.c _build/qjs.lib /link /DEBUG /PDB:repro.pdb /OUT:repro.exe
//   ./repro.exe            -> expected: both cases "PASS"
#include "quickjs.h"

#include <stdio.h>

static long g_module_fin = 0; /* JS_SetModuleFinalizer finalizer calls */
static JSValue g_cpp_pin  = JS_UNDEFINED;

static int module_finalizer(JSContext* ctx, JSModuleDef* m) {
    /* The addon's real cleanup: release context-scoped C++ resources. Here we
       release the "Global<T>" equivalent — the whole point is that this runs
       while the context is still alive. */
    (void)m;
    if (!JS_IsUndefined(g_cpp_pin)) {
        JS_FreeValue(ctx, g_cpp_pin);
        g_cpp_pin = JS_UNDEFINED;
    }
    g_module_fin++;
    return 0;
}

static int dummy_init(JSContext* ctx, JSModuleDef* m) { (void)ctx; (void)m; return 0; }

static void build_module(JSContext* ctx, const char* name, int attach_pin) {
    JSModuleDef* m = JS_NewCModule(ctx, name, dummy_init);
    JS_SetModuleFinalizer(m, module_finalizer);

    if (attach_pin) { /* a strongly-held JSValue from a binding (Global<T>) */
        JSValue plain = JS_NewObject(ctx);
        g_cpp_pin = JS_DupValue(ctx, plain);
        JS_FreeValue(ctx, plain);
    }
}

static int run_case(const char* tag, int attach_pin) {
    fprintf(stderr, "\n===== %s =====\n", tag);
    g_module_fin = 0;
    g_cpp_pin = JS_UNDEFINED;

    JSRuntime* rt  = JS_NewRuntime();
    JS_SetDumpFlags(rt, JS_DUMP_LEAKS | JS_DUMP_ATOM_LEAKS);

    JSContext* ctx = JS_NewContext(rt);
    build_module(ctx, "mod", attach_pin);

    JS_FreeContext(ctx); /* host is done with the context */
    int fired_early = (g_module_fin == 1);
    fprintf(stderr, "  [after host JS_FreeContext] module-finalizer=%ld (want 1)\n",
            g_module_fin);

    JS_FreeRuntime(rt);
    int pin_released = (JS_IsUndefined(g_cpp_pin));
    fprintf(stderr, "  [after JS_FreeRuntime] pin_released=%d no-assert (Debug ok)\n",
            pin_released);

    int pass = fired_early && pin_released;
    fprintf(stderr, "  RESULT: %s\n", pass ? "PASS" : "FAIL");
    return pass ? 0 : 1;
}

int main(void) {
    int rc = 0;
    rc |= run_case("case-1: plain C module (no pinned JSValue)", 0);
    rc |= run_case("case-2: module + JSValue pinned from C++        ", 1);
    return rc;
}

Add-JS_SetModuleFinalizer.patch

Note: the repro uses a proposed JS_SetModuleFinalizer API (a hook fired from js_free_module_def). It is used only to make the firing point observable; the underlying behavior it exposes — that module teardown is deferred to JS_FreeRuntime and blocked by C++-held JSValues — is independent of that API and reproducible without it (e.g. by attaching a JSClassFinalizer to the module private_value, which is the current public mechanism).

Run result:

PS D:\Project\jspp\deps\quickjs-ng> clang-cl /TC /MD /Z7 -I. repro_cmodule_cleanup.c _build/qjs.lib /link /DEBUG /PDB:repro.pdb /OUT:repro.exe
PS D:\Project\jspp\deps\quickjs-ng> .\repro.exe

===== case-1: plain C module (no pinned JSValue) =====
  [after host JS_FreeContext] module-finalizer=0 (want 1)
  [after JS_FreeRuntime] pin_released=1 no-assert (Debug ok)
  RESULT: FAIL

===== case-2: module + JSValue pinned from C++         =====
  [after host JS_FreeContext] module-finalizer=0 (want 1)
Object leaks:
       ADDRESS REFS SHRF          PROTO      CLASS PROPS
0000020117FF5930    1   0* 0000020117FE3B30     Object {  }
Assertion failed: list_empty(&rt->gc_obj_list), file D:/Project/jspp/deps/quickjs-ng/quickjs.c, line 2705

[bnoordhuis]

Full disclosure: I didn't read that wall of LLM-generated text.

If the problem is you need something that runs before JS_FreeContext, then why not call a cleanup function manually before calling JS_FreeContext? I don't immediately see why this is something that would need fixing in quickjs.

[engsr6982]

Sorry about the LLM-generated wall of text earlier—let me keep it short.

I'm providing a C module extension for a host QuickJS instance, exposing some business interfaces. The host uses the module loader from quickjs-libc. After initializing the module with the native js_init_module flow, I have no way to know when the host calls JS_FreeContext, so I can't safely release JSValue references held on the C++ side. QuickJS internally asserts on un-freed JSValue references at JS_FreeRuntime (debug builds), which causes a crash.

Currently, a C module can only expose pure computation functions—it cannot hold any JSValue or JSAtom because there's no safe point to call JS_Free* for them.

But for real modular business logic, it's almost unavoidable for the C module to hold JSValues and also to need a cleanup notification to release C/C++ resources.

In contrast, Node.js handles this safely with node::AddEnvironmentCleanupHook (and its N-API counterpart), which lets C++ addons release resources before the host environment is destroyed. I think QuickJS could benefit from a similar mechanism.

[bnoordhuis]

It's a superficially simple addition, see diff, but I'm somewhat worried about the interaction between the shutdown hooks and the JSContext itself.

The patch partially handles it by checking the JSContext's reference count afterwards (in case something resurrects it) but that's just what I could think up in five minutes; there are probably more gotchas lurking.

As a side note: if your module keeps references to JS functions, then a shutdown hook won't help. Functions retain a reference to their JSContext (their realm), creating a cyclical dependency that the built-in GC won't be able to break. Modules are not regular GC objects.

Details

diff --git a/quickjs.c b/quickjs.c
index 4dc2ef2..1800979 100644
--- a/quickjs.c
+++ b/quickjs.c
@@ -1045,6 +1045,7 @@ struct JSModuleDef {
     JSValue module_ns;
     JSValue func_obj; /* only used for JS modules */
     JSModuleInitFunc *init_func; /* only used for C modules */
+    JSModuleInitFunc *fini_func; /* only used for C modules */
     bool has_tla; /* true if func_obj contains await */
     bool resolved;
     bool func_created;
@@ -3039,6 +3040,7 @@ static void JS_MarkContext(JSRuntime *rt, JSContext *ctx,
 
 void JS_FreeContext(JSContext *ctx)
 {
+    struct list_head *el, *el1;
     JSRuntime *rt = ctx->rt;
     int i;
 
@@ -3046,6 +3048,15 @@ void JS_FreeContext(JSContext *ctx)
         return;
     assert(JS_REF_COUNT(ctx) == 0);
 
+    list_for_each_safe(el, el1, &ctx->loaded_modules) {
+        JSModuleDef *m = list_entry(el, JSModuleDef, link);
+        if (m->fini_func)
+            m->fini_func(ctx, m);
+    }
+
+    if (JS_REF_COUNT(ctx)) // in case shutdown hook revived the JSContext
+        return;
+
 #ifdef ENABLE_DUMPS // JS_DUMP_ATOMS
     if (check_dump_flag(rt, JS_DUMP_ATOMS))
         JS_DumpAtoms(ctx->rt);

[engsr6982]

Yeah, exactly as we thought! The fundamental issue is that JSContext's lifecycle is tied purely to reference counting, while every C function holds a strong reference to JSContext as its realm. When the host calls JS_FreeContext, --JS_REF_COUNT(ctx) > 0 hits immediately and returns, so the context is never actually torn down at that moment.

Walking through the debugger, I noticed that JS_RunGC also internally triggers JS_FreeContext as objects are cleaned up.

For regular JS objects, we could break cycles using JSClassDef's gc_mark. But because JSContext itself does not participate in the GC's mark-and-sweep, there is no way for a native module to break this circular reference from the outside.

I was wondering: if JS_FreeContext could distinguish an explicit host release call from an internal GC cleanup call—so that the host's call first triggers module cleanup (allowing modules to drop pinned JSValues and unbind realm references) before proceeding with GC—would that bridge the gap?

Though I'm not sure if separating those paths might break existing internal API semantics. Perhaps you have a cleaner architectural vision for this?

[bnoordhuis]

I don't think that could work. As long as the context's reference count > 0, it's not safe to free anything because we don't know who or what holds the references.

My hunch is that, as an embedder, you won't be able to escape running cleanup code manually before JS_FreeContext.

[engsr6982]

I hear you, and that makes sense from a strict memory-safety design view.
Realistically, if this isn't solvable in the upstream engine due to the refcounting model, binding layer authors are left with only two choices:

Disable standard C module loading, or Enforce a custom Native Module contract (e.g., dual init/fini lifecycle hooks explicitly registered with a custom host) to bypass the issue.

From the perspective of a third-party C module author:

Under the standard QuickJS C module spec, we can now only safely author purely computational modules (stateless utility libraries). We cannot safely bind engine-level state (like stored callbacks, class constructors, or global singletons) to the runtime script context.
To support rich, stateful bindings, we are forced to break away from the standard C module spec and require a customized host that manually drives cleanup hooks before JS_FreeContext.

It's unfortunate that standard QuickJS C modules have this implicit limit, but I completely understand the architectural constraints around JSContext refcounting now. I don't see a better workaround without changing the engine's lifecycle model either. :(
Thanks again for the detailed discussion and for walking through the mechanics with me!