node-gtk 4.0.1 → 4.1.1

package/binding.gyp

@@ -36,6 +36,7 @@
                 "src/gobject.cc",
                 "src/loop.cc",
                 "src/param_spec.cc",
+                "src/toggle_queue.cc",
                 "src/type.cc",
                 "src/util.cc",
                 "src/value.cc",

package/lib/bootstrap.js

@@ -2,9 +2,21 @@
  * bootstrap.js
  */
 
-const camelCase = require('lodash.camelcase')
+const camelCaseRaw = require('lodash.camelcase')
 const internal = require('./native.js')
 
+// Method/field/property names repeat heavily across classes (get_name,
+// set_visible, ...): memoize the case conversion.
+const camelCaseCache = new Map()
+function camelCase(name) {
+  let result = camelCaseCache.get(name)
+  if (result === undefined) {
+    result = camelCaseRaw(name)
+    camelCaseCache.set(name, result)
+  }
+  return result
+}
+
 // The bootstrap from C here contains functions and methods for each object,
 // namespaced with underscores. See gi.cc for more information.
 const GI = internal.Bootstrap();
@@ -15,6 +27,7 @@ module.exports = {
   GI,
   makeInfo,
   getInfoName,
+  defineLazyInfos,
 }
 
 // The GIRepository API is fairly poor, and contains methods on classes,
@@ -341,6 +354,84 @@ function applyInterfaceMethods(constructor, interfaceRefs) {
 
 internal.SetInterfaceMethodsApplier(applyInterfaceMethods)
 
+/*
+ * Lazy type materialization. Namespaces expose thousands of top-level infos
+ * (6,600+ for Gtk-4.0 with its dependencies) but an app touches a few dozen:
+ * giRequire() defines one lazy accessor per info instead of building every
+ * class eagerly, and the first access runs makeInfo() and replaces the
+ * accessor with the result. Types reached from C before JS ever names them (a
+ * method return value, a signal argument) are materialized through the C++
+ * template-creation hook (SetTypeMaterializer below), so their prototypes are
+ * decorated before any wrapper is handed out.
+ */
+
+const materializing = new Set()
+
+function defineLazyInfos(module, ns) {
+  // One native call per namespace: a flat [name, infoType, index, ...] array
+  // of the infos makeInfo() can handle (enumerating via GI.* costs ~3 FFI
+  // round-trips per info, 48ms for Gtk-4.0 + dependencies).
+  const entries = internal.GetInfoEntries(ns)
+
+  for (let i = 0; i < entries.length; i += 3) {
+    const type = entries[i + 1]
+    const name = type === GI.InfoType.FUNCTION ? camelCase(entries[i]) : entries[i]
+    defineLazyInfo(module, ns, name, entries[i + 2])
+  }
+}
+
+function defineLazyInfo(module, ns, name, index) {
+  const key = ns + '.' + name
+
+  Object.defineProperty(module, name, {
+    configurable: true,
+    enumerable: true,
+    get() {
+      /* Re-entered while materializing: the C++ hook fires for the class
+       * makeInfo() is currently building, and MakeBoxedClass() consults the
+       * module cache for the G_TYPE_NONE struct it is building. Report
+       * undefined; the outer call installs the final value. */
+      if (materializing.has(key))
+        return undefined
+      materializing.add(key)
+      try {
+        const repo = GI.Repository_get_default()
+        const info = GI.Repository_get_info.call(repo, ns, index)
+        const value = makeInfo(info)
+        Object.defineProperty(module, name, {
+          configurable: true, enumerable: true, writable: true, value,
+        })
+        return value
+      } finally {
+        materializing.delete(key)
+      }
+    },
+    /* Plain assignments must keep working (getInterface() and the overrides
+     * write straight into the module). */
+    set(value) {
+      Object.defineProperty(module, name, {
+        configurable: true, enumerable: true, writable: true, value,
+      })
+    },
+  })
+}
+
+/*
+ * Called from C++ when a class template is first created for an
+ * introspectable type (GetClassTemplate/GetBoxedFunction/
+ * GetFundamentalTemplate), so that a type reached from C first has its
+ * prototype decorated. Triggering the accessor is enough; the accessor makes
+ * this idempotent and re-entrancy-safe.
+ */
+function materializeType(ns, name) {
+  const module = moduleCache[ns]
+  if (module === undefined)
+    return
+  void module[name]
+}
+
+internal.SetTypeMaterializer(materializeType)
+
 function makeBoxed(info) {
   if (getType(info) == GI.InfoType.UNION) {
     return makeUnion(info)

package/lib/module.js

@@ -7,7 +7,7 @@ const util = require('util')
 const readdir = util.promisify(fs.readdir)
 
 const internal = require('./native.js')
-const { GI, makeInfo, getInfoName } = require('./bootstrap.js')
+const { GI, defineLazyInfos } = require('./bootstrap.js')
 
 const moduleCache = internal.GetModuleCache();
 
@@ -37,14 +37,11 @@ function giRequire(ns, version) {
 
   loadDependencies(ns, version)
 
-  const nInfos = GI.Repository_get_n_infos.call(repo, ns);
-  for (let i = 0; i < nInfos; i++) {
-    const info = GI.Repository_get_info.call(repo, ns, i);
-    const item = makeInfo(info);
-
-    if (item !== undefined)
-      module[getInfoName(info)] = item
-  }
+  // Top-level infos materialize on first access (see defineLazyInfos in
+  // bootstrap.js): building every class of a namespace and its dependencies
+  // eagerly used to cost ~160ms for Gtk-4.0, for the few dozen classes a
+  // typical app touches.
+  defineLazyInfos(module, ns)
 
   // Apply overrides, if present
   let override

package/lib/native.js

@@ -2,12 +2,22 @@
  * native.js
  */
 
-const binary = require('@mapbox/node-pre-gyp')
 const path = require('path')
 const fs = require('fs')
 
-const packagePath = path.resolve(path.join(__dirname,'../package.json'))
-const bindingPath = binary.find(packagePath)
+// Resolve the compiled addon directly rather than through node-pre-gyp:
+// requiring node-pre-gyp costs ~16ms of startup for what amounts to
+// evaluating the module_path template of package.json (`binary.find`). Keep
+// it as a fallback for any layout the shorthand doesn't cover (e.g. a
+// non-node runtime with a different ABI naming scheme).
+const bindingName = `node-v${process.versions.modules}-${process.platform}-${process.arch}`
+let bindingPath = path.join(__dirname, 'binding', bindingName, 'node_gtk.node')
+
+if (!fs.existsSync(bindingPath)) {
+  const binary = require('@mapbox/node-pre-gyp')
+  const packagePath = path.resolve(path.join(__dirname, '../package.json'))
+  bindingPath = binary.find(packagePath)
+}
 
 // On Windows, the prebuilt binary ships with its whole GTK runtime bundled in
 // the same directory as the .node (DLLs, GObject-Introspection typelibs, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-gtk",
-  "version": "4.0.1",
+  "version": "4.1.1",
   "description": "GNOME Gtk+ bindings for NodeJS",
   "main": "lib/index.js",
   "exports": {
@@ -51,7 +51,7 @@
   },
   "homepage": "https://github.com/romgrk/node-gtk#readme",
   "dependencies": {
-    "@mapbox/node-pre-gyp": "^1.0.10",
+    "@mapbox/node-pre-gyp": "^2.0.3",
     "lodash.camelcase": "4.3.0",
     "lodash.isequal": "4.5.0",
     "lodash.snakecase": "^4.1.1",
@@ -62,11 +62,26 @@
   },
   "devDependencies": {
     "assert": "^1.5.0",
-    "aws-sdk": "^2.452.0",
+    "aws-sdk": "^2.1692.0",
     "chalk": "^2.4.2",
-    "mocha": "^7.1.0",
-    "nid-parser": "0.0.5",
-    "node-pre-gyp-github": "^1.4.5"
+    "mocha": "^11.7.0",
+    "nid-parser": "0.0.5"
+  },
+  "overrides": {
+    "nid-parser": {
+      "js-yaml": "^3.15.0",
+      "extend": "^3.0.2"
+    },
+    "optimist": {
+      "minimist": "^1.2.8"
+    },
+    "aws-sdk": {
+      "uuid": "^11.1.1"
+    },
+    "mocha": {
+      "diff": "^8.0.3",
+      "serialize-javascript": "^7.0.5"
+    }
   },
   "files": [
     "/bin",
@@ -74,7 +89,9 @@
     "/src",
     "/scripts",
     "/tools",
-    "binding.gyp"
+    "binding.gyp",
+    "!lib/binding",
+    "!**/*.node"
   ],
   "binary": {
     "module_name": "node_gtk",

package/scripts/ci.sh

@@ -46,12 +46,9 @@ function npm_test() {
         # fixture build does not run automatically; do it here. Best-effort:
         # marshalling tests skip if fixtures cannot be produced on macOS.
         npm run build:test-fixtures || true;
-        npx mocha                                 \
-                  --skip=callback                 \
-                  tests/__run__.js
+        NODE_GTK_TEST_SKIP=callback npx mocha tests/__run__.js
     else
-        xvfb-run -a npm test --                   \
-                  --skip=callback;
+        NODE_GTK_TEST_SKIP=callback xvfb-run -a npm test;
     fi;
 }
 

package/src/boxed.cc

@@ -409,6 +409,14 @@ Local<Function> GetBoxedFunction(GIBaseInfo *info, GType gtype) {
 
     g_type_set_qdata(gtype, GNodeJS::function_quark(), persistent);
 
+    /* Modules hold lazy accessors: a registered boxed type reached from C
+     * first (method return value, signal argument) must be materialized so
+     * makeBoxed() in JS attaches its methods/fields before a wrapper is
+     * handed out. Fired after the qdata above so the re-entrant
+     * MakeBoxedClass() from JS finds this same function. Idempotent and
+     * re-entrancy-safe on the JS side. */
+    GNodeJS::MaterializeType(info);
+
     return fn;
 }
 
@@ -430,10 +438,12 @@ Local<Function> MakeBoxedClass(GIBaseInfo *info) {
         if (Nan::HasOwnProperty(moduleCache, ns).FromMaybe(false)) {
             auto module = TO_OBJECT (Nan::Get(moduleCache, ns).ToLocalChecked());
 
-            if (Nan::HasOwnProperty(module, name).FromMaybe(false)) {
-                auto constructor = TO_OBJECT (Nan::Get(module, name).ToLocalChecked());
+            /* The Get can run a lazy accessor. It returns the materialized
+             * class, or undefined when re-entered from the accessor's own
+             * makeBoxed() call — fall through and build the class then. */
+            auto constructor = Nan::Get(module, name).ToLocalChecked();
+            if (constructor->IsFunction())
                 return Local<Function>::Cast (constructor);
-            }
         }
     }
 

package/src/callback.cc

@@ -23,6 +23,9 @@ namespace GNodeJS {
 
 static guint callbackLevel = 0;
 static GSList* notifiedCallbacks = NULL;
+/* DestroyNotify can fire on any thread (e.g. a GTask freeing its callback
+ * data on a pool thread); the list must not race the JS thread's AsyncFree. */
+static GMutex notifiedCallbacksLock;
 
 static Local<Object> GetSelfInstance(GIArgument **args) {
     return WrapperFromGObject((GObject *)args[0]->v_pointer).As<Object>();
@@ -66,26 +69,27 @@ Callback::~Callback() {
  * we can't free the resources here. They'll be freed in Callback::AsyncFree.
  */
 void Callback::DestroyNotify (void* user_data) {
+    g_mutex_lock (&notifiedCallbacksLock);
     notifiedCallbacks = g_slist_prepend (notifiedCallbacks, user_data);
+    g_mutex_unlock (&notifiedCallbacksLock);
 }
 
 /**
  * Frees the callbacks that have been destroy-notified
  */
 void Callback::AsyncFree () {
-    if (notifiedCallbacks == NULL || callbackLevel > 0)
+    if (callbackLevel > 0)
         return;
 
-    GSList* current = notifiedCallbacks;
-
-    while (current != NULL) {
-        Callback* callback = static_cast<Callback*>(current->data);
-        delete callback;
+    g_mutex_lock (&notifiedCallbacksLock);
+    GSList* list = notifiedCallbacks;
+    notifiedCallbacks = NULL;
+    g_mutex_unlock (&notifiedCallbacksLock);
 
-        current = current->next;
-    }
+    for (GSList* current = list; current != NULL; current = current->next)
+        delete static_cast<Callback*>(current->data);
 
-    notifiedCallbacks = NULL;
+    g_slist_free (list);
 }
 
 /**
@@ -220,6 +224,18 @@ void Callback::Execute (GIArgument *result, GIArgument **args, Callback *callbac
             Throw::InvalidReturnValue (&return_type_info, jsReturnValue);
             goto out;
         }
+
+        // When the callback's return value is transfer-full, the C caller takes
+        // ownership of it (e.g. GtkTreeListModelCreateModelFunc → GListModel).
+        // V8ToGIArgument only unwrapped the pointer, leaving node-gtk holding
+        // just its toggle ref; without the owning reference the caller "owns"
+        // that toggle ref, so no toggle-up fires, the wrapper stays weak, and
+        // once GC collects it the object is finalized while the caller still
+        // uses it — a use-after-free (e.g. gtk_tree_list_model_finalize
+        // disconnecting its items-changed handler from a freed child model).
+        // This is the return counterpart of the transfer-full IN argument.
+        if (g_callable_info_get_caller_owns(callback->info) == GI_TRANSFER_EVERYTHING)
+            TakeOwnershipForTransferFull(&return_type_info, result, -1);
     }
 
     // TODO: assess transferness of arguments & check if we need to free them

package/src/function.cc

@@ -527,10 +527,7 @@ Local<Value> FunctionCall (
                 // GskRenderNode): add the reference the callee will own (#468).
                 else if (direction == GI_DIRECTION_IN
                         && g_arg_info_get_ownership_transfer(&arg_info) == GI_TRANSFER_EVERYTHING) {
-                    CopyBoxedForTransferFullIn(&type_info, &callable_arg_values[i], param.length);
-                    RefObjectForTransferFullIn(&type_info, &callable_arg_values[i]);
-                    RefFundamentalForTransferFullIn(&type_info, &callable_arg_values[i]);
-                    RefVariantForTransferFullIn(&type_info, &callable_arg_values[i]);
+                    TakeOwnershipForTransferFull(&type_info, &callable_arg_values[i], param.length);
                 }
             }
 

package/src/fundamental.cc

@@ -239,6 +239,16 @@ static Local<FunctionTemplate> GetFundamentalTemplate (GIObjectInfo *info, GType
         }
     }
 
+    /* The parent recursion above runs JS (each ancestor's template fires the
+     * type materializer below), so JS may have re-entered here and created
+     * this very template already. Keep that one: its function is the one JS
+     * has started decorating. */
+    data = g_type_get_qdata (gtype, GNodeJS::template_quark ());
+    if (data) {
+        auto *persistent = (Persistent<FunctionTemplate> *) data;
+        return New<FunctionTemplate> (*persistent);
+    }
+
     auto *persistentTpl = new Persistent<FunctionTemplate> (tpl);
     auto *persistentFn  = new Persistent<Function> (Nan::GetFunction (tpl).ToLocalChecked ());
     persistentTpl->SetWeak (
@@ -247,6 +257,11 @@ static Local<FunctionTemplate> GetFundamentalTemplate (GIObjectInfo *info, GType
     g_type_set_qdata (gtype, GNodeJS::template_quark (), persistentTpl);
     g_type_set_qdata (gtype, GNodeJS::function_quark (), persistentFn);
 
+    /* Modules hold lazy accessors: a fundamental type reached from C first
+     * must be materialized so makeObject() in JS attaches its methods before
+     * a wrapper is handed out (see gi.h). */
+    GNodeJS::MaterializeType (info);
+
     return tpl;
 }
 
@@ -405,6 +420,17 @@ static Local<FunctionTemplate> GetVariantTemplate () {
     g_type_set_qdata (gtype, GNodeJS::template_quark (), persistentTpl);
     g_type_set_qdata (gtype, GNodeJS::function_quark (), persistentFn);
 
+    /* Modules hold lazy accessors: a variant reached from C first (e.g. a
+     * signal argument, #465) must have GLib.Variant materialized so
+     * makeBoxed() in JS attaches its methods before a wrapper is handed out. */
+    if (g_irepository_is_registered (NULL, "GLib", NULL)) {
+        GIBaseInfo *variant_info = g_irepository_find_by_name (NULL, "GLib", "Variant");
+        if (variant_info) {
+            GNodeJS::MaterializeType (variant_info);
+            g_base_info_unref (variant_info);
+        }
+    }
+
     return tpl;
 }
 

package/src/gi.cc

@@ -32,9 +32,37 @@ namespace GNodeJS {
 
     Nan::Persistent<Object> moduleCache(Nan::New<Object>());
 
+    GThread *js_thread = NULL;
+
     Local<Object> GetModuleCache() {
         return Nan::New<Object>(GNodeJS::moduleCache);
     }
+
+    static Nan::Persistent<v8::Function> typeMaterializer;
+
+    void SetTypeMaterializerInternal(Local<v8::Function> fn) {
+        typeMaterializer.Reset(fn);
+    }
+
+    void MaterializeType(GIBaseInfo *info) {
+        if (typeMaterializer.IsEmpty() || info == NULL)
+            return;
+
+        Local<v8::Function> fn = Nan::New<v8::Function>(typeMaterializer);
+        Local<Value> argv[] = {
+            UTF8(g_base_info_get_namespace(info)),
+            UTF8(g_base_info_get_name(info)),
+        };
+        Nan::TryCatch tryCatch;
+        Nan::Call(fn, Nan::GetCurrentContext()->Global(), 2, argv);
+        if (tryCatch.HasCaught()) {
+            Nan::Utf8String message(tryCatch.Exception());
+            g_warning("node-gtk: could not materialize type %s.%s: %s",
+                      g_base_info_get_namespace(info),
+                      g_base_info_get_name(info),
+                      *message);
+        }
+    }
 }
 
 
@@ -121,6 +149,71 @@ NAN_METHOD(Bootstrap) {
     info.GetReturnValue().Set(module_obj);
 }
 
+/*
+ * Enumerate a loaded namespace's top-level infos in one native call, so that
+ * lib/module.js can define lazy accessors without paying ~3 FFI round-trips
+ * per info (48ms for Gtk-4.0 + dependencies, vs ~1ms here). Returns a flat
+ * array of [name, infoType, index, ...] triplets. Infos that makeInfo() cannot
+ * handle (callbacks, gtype structs, etc.) are filtered out here, mirroring the
+ * `item !== undefined` check the eager loop used to do.
+ */
+NAN_METHOD(GetInfoEntries) {
+    Nan::Utf8String ns(info[0]);
+    GIRepository *repo = g_irepository_get_default();
+
+    int n = g_irepository_get_n_infos(repo, *ns);
+    Local<Array> result = Nan::New<Array>();
+    uint32_t position = 0;
+
+    for (int i = 0; i < n; i++) {
+        BaseInfo baseInfo(g_irepository_get_info(repo, *ns, i));
+        GIInfoType type = baseInfo.type();
+
+        switch (type) {
+        case GI_INFO_TYPE_FUNCTION:
+        case GI_INFO_TYPE_BOXED:
+        case GI_INFO_TYPE_ENUM:
+        case GI_INFO_TYPE_FLAGS:
+        case GI_INFO_TYPE_OBJECT:
+        case GI_INFO_TYPE_INTERFACE:
+        case GI_INFO_TYPE_CONSTANT:
+        case GI_INFO_TYPE_UNION:
+            break;
+        case GI_INFO_TYPE_STRUCT:
+            if (g_struct_info_is_gtype_struct(baseInfo.info()))
+                continue;
+            break;
+        default:
+            continue;
+        }
+
+        /* Register the GType with the GObject runtime NOW, even though the JS
+         * class stays lazy. The eager loop did this as a side effect
+         * (MakeObjectClass/MakeBoxedClass call get_g_type() for every class)
+         * and code depends on it: by-name lookups such as
+         * GObject.typeFromName('GFileInfo') or type names in GtkBuilder XML
+         * must resolve without JS ever touching the class. Registration is a
+         * few µs per type; class initialization stays lazy either way. */
+        switch (type) {
+        case GI_INFO_TYPE_STRUCT:
+        case GI_INFO_TYPE_BOXED:
+        case GI_INFO_TYPE_UNION:
+        case GI_INFO_TYPE_OBJECT:
+        case GI_INFO_TYPE_INTERFACE:
+            g_registered_type_info_get_g_type((GIRegisteredTypeInfo *) baseInfo.info());
+            break;
+        default:
+            break;
+        }
+
+        Nan::Set(result, position++, UTF8(baseInfo.name()));
+        Nan::Set(result, position++, Nan::New<v8::Int32>(type));
+        Nan::Set(result, position++, Nan::New<v8::Int32>(i));
+    }
+
+    info.GetReturnValue().Set(result);
+}
+
 NAN_METHOD(GetConstantValue) {
     GIBaseInfo *gi_info = (GIBaseInfo *) GNodeJS::PointerFromWrapper (info[0]);
     GITypeInfo *type_info = g_constant_info_get_type(gi_info);
@@ -418,6 +511,10 @@ NAN_METHOD(SetInterfaceMethodsApplier) {
     GNodeJS::SetInterfaceMethodsApplier(info);
 }
 
+NAN_METHOD(SetTypeMaterializer) {
+    GNodeJS::SetTypeMaterializerInternal(info[0].As<v8::Function>());
+}
+
 NAN_METHOD(RegisterClass) {
     GNodeJS::ObjectClass::RegisterClass(info);
 }
@@ -431,6 +528,8 @@ NAN_METHOD(CallVFunc) {
 }
 
 void InitModule(Local<Object> exports, Local<Value> module, void *priv) {
+    GNodeJS::js_thread = g_thread_self();
+
     GNodeJS::AsyncCallEnvironment::Initialize();
 
     Nan::Export(exports, "Bootstrap",            Bootstrap);
@@ -438,6 +537,8 @@ void InitModule(Local<Object> exports, Local<Value> module, void *priv) {
     Nan::Export(exports, "GetBaseClass",         GetBaseClass);
     Nan::Export(exports, "GetTypeSize",          GetTypeSize);
     Nan::Export(exports, "GetConstantValue",     GetConstantValue);
+    Nan::Export(exports, "GetInfoEntries",       GetInfoEntries);
+    Nan::Export(exports, "SetTypeMaterializer",  SetTypeMaterializer);
     Nan::Export(exports, "MakeBoxedClass",       MakeBoxedClass);
     Nan::Export(exports, "MakeObjectClass",      MakeObjectClass);
     Nan::Export(exports, "MakeFunction",         MakeFunction);

package/src/gi.h

@@ -24,8 +24,29 @@ namespace GNodeJS {
 
 extern Nan::Persistent<Object> moduleCache;
 
+/*
+ * The thread running V8/libuv (recorded at module init). V8 objects — global
+ * handles in particular — may only be touched from this thread.
+ */
+extern GThread *js_thread;
+
 Local<Object> GetModuleCache();
 
+/*
+ * Lazy type materialization: modules are populated with lazy accessors
+ * (lib/module.js), and prototypes only get their methods/properties when a
+ * class is first touched. Types can also be reached from C first (a method
+ * return value, a signal argument): the template-creation paths in
+ * gobject.cc/boxed.cc/fundamental.cc call MaterializeType so the JS side
+ * decorates the prototype before any wrapper is handed out. The callback is
+ * installed from bootstrap.js via SetTypeMaterializer and is idempotent and
+ * re-entrancy-safe on the JS side.
+ */
+
+void MaterializeType(GIBaseInfo *info);
+
+void SetTypeMaterializerInternal(Local<v8::Function> fn);
+
 
 
 /*

package/src/gobject.cc

@@ -11,6 +11,7 @@
 #include "gi.h"
 #include "gobject.h"
 #include "macros.h"
+#include "toggle_queue.h"
 #include "util.h"
 #include "value.h"
 
@@ -133,10 +134,28 @@ struct GObjectWrapper {
     bool collected = false;
 };
 
-static void ToggleNotify(gpointer user_data, GObject *gobject, gboolean toggle_down) {
+/* Reconcile the wrapper's persistent with the state the object's current
+ * refcount calls for. Main thread only — called inline by ToggleNotify on the
+ * JS thread, and by toggleQueue's drain for deferred off-thread notifications.
+ *
+ * Weak when the toggle ref is the only reference left: we are the last
+ * holder, so the wrapper may be collected. The two-pass weak callback's first
+ * pass runs *during* GC (before any JS/GTK code resumes) and only flips a
+ * flag, so WrapperFromGObject can tell a reclaimed wrapper from a live one
+ * and never marshals a dead handle to JS. All GObject teardown happens in the
+ * second pass — a first-pass callback may not call into GObject.
+ *
+ * Strong otherwise: something other than us holds the object, so the wrapper
+ * must stay alive until that ref is dropped again. Reviving is essential —
+ * without it a wrapper that went weak once (e.g. a freshly constructed object
+ * at refcount 1) would never become strong again when GTK takes ownership,
+ * and GC could then collect a wrapper whose GObject is still in use (notably
+ * a subclassed widget owned by GTK, losing its overridden vfuncs and instance
+ * state). */
+void SynchronizeToggleState(GObject *gobject) {
     void *data = g_object_get_qdata (gobject, GNodeJS::object_quark());
-
-    g_assert (data != NULL);
+    if (data == NULL)
+        return;
 
     auto *wrapper = (GObjectWrapper *) data;
 
@@ -146,34 +165,37 @@ static void ToggleNotify(gpointer user_data, GObject *gobject, gboolean toggle_d
     if (wrapper->collected)
         return;
 
-    if (toggle_down) {
-        /* We're dropping from 2 refs to 1 ref: we are the last holder, so the
-         * wrapper may be collected. Install the weak ref (unless it already is). */
-        if (wrapper->dying)
-            return;
+    bool only_toggle_ref =
+        g_atomic_int_get ((const gint *) &gobject->ref_count) <= 1;
+
+    if (only_toggle_ref && !wrapper->dying) {
         wrapper->dying = true;
-        /* Two-pass weak callback: the first pass runs *during* GC (before any
-         * JS/GTK code resumes) and only flips a flag, so WrapperFromGObject can
-         * tell a reclaimed wrapper from a live one and never marshals a dead
-         * handle to JS. All GObject teardown happens in the second pass — a
-         * first-pass callback may not call into GObject. */
         wrapper->persistent.v8::PersistentBase<Object>::SetWeak (
             wrapper, GObjectDestroyedFirstPass, v8::WeakCallbackType::kParameter);
-    } else {
-        /* We're going from 1 ref to 2 refs: something other than us now holds
-         * the object, so the wrapper must stay alive (strong) until that ref is
-         * dropped again. Reviving here is essential — without it a wrapper that
-         * went weak once (e.g. a freshly constructed object at refcount 1) would
-         * never become strong again when GTK takes ownership, and GC could then
-         * collect a wrapper whose GObject is still in use (notably a subclassed
-         * widget owned by GTK, losing its overridden vfuncs and instance state). */
-        if (!wrapper->dying)
-            return;
+    } else if (!only_toggle_ref && wrapper->dying) {
         wrapper->dying = false;
         wrapper->persistent.ClearWeak ();
     }
 }
 
+/* Fires synchronously on whatever thread crosses the 1<->2 refcount boundary
+ * — e.g. GLib's worker thread dropping the ref it held on a GSubprocess while
+ * waiting for the child to exit. V8 global handles may only be touched from
+ * the JS thread: a SetWeak/ClearWeak from a worker raced the scavenger's
+ * weak-handle processing and corrupted the global-handle list (fatal "Check
+ * failed: Heap::InFromPage(heap_object)" in a later scavenge, or random
+ * SIGSEGV). Off-thread notifications are deferred to the main context; the
+ * notified direction is not forwarded because the deferred reconciliation
+ * re-derives it from the refcount (see toggle_queue.h). */
+static void ToggleNotify(gpointer user_data, GObject *gobject, gboolean toggle_down) {
+    if (G_UNLIKELY (g_thread_self () != GNodeJS::js_thread)) {
+        toggleQueue.Synchronize (gobject);
+        return;
+    }
+
+    SynchronizeToggleState (gobject);
+}
+
 static void AssociateGObject(Local<Object> object, GObject *gobject, GType gtype) {
     Nan::SetInternalFieldPointer(object, 0, gobject);
 
@@ -202,6 +224,9 @@ static void AssociateGObject(Local<Object> object, GObject *gobject, GType gtype
 static void GObjectFinalized(gpointer data, GObject *where_the_object_was) {
     auto *wrapper = (GObjectWrapper *) data;
     wrapper->gobject = NULL;
+    /* A deferred off-thread toggle may still be queued for this object; the
+     * drain must not touch freed memory. */
+    toggleQueue.Cancel (where_the_object_was);
 }
 
 static void GObjectConstructor(const FunctionCallbackInfo<Value> &info) {
@@ -308,6 +333,11 @@ static gboolean GObjectTeardownIdle(gpointer data) {
     /* If the GObject was already finalized out from under us, GObjectFinalized
      * cleared the pointer; there is nothing left to detach or unref. */
     if (gobject != NULL) {
+        /* The weak ref that would cancel a queued off-thread toggle on
+         * finalize is removed below, so cancel any pending entry now — the
+         * toggle ref drop at the end may be the object's last reference. */
+        toggleQueue.Cancel (gobject);
+
         /* Drop the weak ref first so removing the toggle ref (which may finalize
          * the object) doesn't re-enter GObjectFinalized. */
         g_object_weak_unref (gobject, GObjectFinalized, wrapper);
@@ -878,6 +908,17 @@ static MaybeLocal<FunctionTemplate> GetClassTemplate(GType gtype) {
     if (maybeTpl.IsEmpty())
         return MaybeLocal<FunctionTemplate> ();
 
+    /* NewClassTemplate() runs JS while building the parent chain (each
+     * ancestor's template fires the type materializer below), so JS may have
+     * re-entered here and created this very template already. Keep that one:
+     * its function is the one JS has started decorating. */
+    data = g_type_get_qdata (gtype, GNodeJS::template_quark());
+    if (data) {
+        auto *persistent = (Nan::Persistent<FunctionTemplate> *) data;
+        auto existingTpl = New<FunctionTemplate> (*persistent);
+        return existingTpl;
+    }
+
     auto tpl = maybeTpl.ToLocalChecked();
     auto fn = Nan::GetFunction (tpl).ToLocalChecked();
     auto persistentTpl = new Nan::Persistent<FunctionTemplate>(tpl);
@@ -892,14 +933,19 @@ static MaybeLocal<FunctionTemplate> GetClassTemplate(GType gtype) {
     g_type_set_qdata(gtype, GNodeJS::template_quark(), persistentTpl);
     g_type_set_qdata(gtype, GNodeJS::function_quark(), persistentFn);
 
-    // Introspectable object types have their interface methods installed by
-    // makeObject() in JS. Private concrete types are never seen there, so mix
-    // in their interface methods now (issue #441).
+    // Introspectable object types have their methods/properties installed by
+    // makeObject() in JS. Modules hold lazy accessors, so a type reached from
+    // C first (method return value, signal argument) must be materialized here
+    // or its wrappers would expose a bare prototype. Private concrete types
+    // are invisible to makeObject(), so mix in their interface methods
+    // instead (issue #441).
     GIBaseInfo *own_info = g_irepository_find_by_gtype(NULL, gtype);
-    if (own_info == NULL)
+    if (own_info == NULL) {
         ApplyInterfaceMethods(fn, gtype);
-    else
+    } else {
+        GNodeJS::MaterializeType(own_info);
         g_base_info_unref(own_info);
+    }
 
     return MaybeLocal<FunctionTemplate> (tpl);
 }

package/src/gobject.h

@@ -18,6 +18,11 @@ namespace GNodeJS {
 MaybeLocal<Function>    MakeClass            (GIBaseInfo *info);
 Local<Value>            WrapperFromGObject   (GObject *object);
 GObject *               GObjectFromWrapper   (Local<Value> value);
+
+/* Reconcile the wrapper's V8 persistent (weak or strong) with the GObject's
+ * current refcount. Main thread only; called inline by ToggleNotify on the JS
+ * thread and by toggleQueue's drain for deferred off-thread notifications. */
+void                    SynchronizeToggleState (GObject *gobject);
 Local<Value>            GetSignalHandler     (GObject *gobject, guint index);
 Local<FunctionTemplate> GetBaseClassTemplate ();
 MaybeLocal<Value>       GetGObjectProperty   (GObject * gobject, const char *prop_name);

package/src/toggle_queue.cc

@@ -0,0 +1,44 @@
+
+#include "toggle_queue.h"
+#include "gobject.h"
+
+namespace GNodeJS {
+
+ToggleQueue toggleQueue;
+
+void ToggleQueue::Synchronize (GObject *gobject) {
+    g_mutex_lock (&lock);
+    if (g_slist_find (objects, gobject) == NULL)
+        objects = g_slist_prepend (objects, gobject);
+    if (source == 0)
+        source = g_idle_add (ToggleQueue::Drain, this);
+    g_mutex_unlock (&lock);
+}
+
+void ToggleQueue::Cancel (GObject *gobject) {
+    g_mutex_lock (&lock);
+    objects = g_slist_remove (objects, gobject);
+    g_mutex_unlock (&lock);
+}
+
+/* Runs on the main context. The lock is held across the drain so a (buggy,
+ * over-unreffed) off-thread finalize cancelling its entry cannot race the
+ * entry being processed. SynchronizeToggleState never re-enters the queue,
+ * so this cannot deadlock. */
+gboolean ToggleQueue::Drain (gpointer user_data) {
+    auto *self = static_cast<ToggleQueue *> (user_data);
+
+    g_mutex_lock (&self->lock);
+    GSList *objects = self->objects;
+    self->objects = NULL;
+    self->source = 0;
+
+    for (GSList *l = objects; l != NULL; l = l->next)
+        SynchronizeToggleState ((GObject *) l->data);
+
+    g_slist_free (objects);
+    g_mutex_unlock (&self->lock);
+    return G_SOURCE_REMOVE;
+}
+
+}; /* GNodeJS */

package/src/toggle_queue.h

@@ -0,0 +1,53 @@
+
+#pragma once
+
+#include <glib-object.h>
+
+namespace GNodeJS {
+
+/*
+ * Defers toggle-state synchronization to the main context.
+ *
+ * "Synchronize" is meant as reconcile — bring the wrapper's V8 persistent
+ * (weak or strong) in line with the GObject's current refcount — not as
+ * synchronous execution: requests may come from any thread, and the
+ * reconciliation itself always runs later, from an idle on the main context.
+ *
+ * A toggle notification runs on whatever thread crosses the 1<->2 refcount
+ * boundary, but V8 global handles may only be touched from the JS thread
+ * (see ToggleNotify in gobject.cc). Off-thread notifications land here.
+ *
+ * The queue stores no direction: by the time the idle runs, the notified
+ * direction is stale (the refcount may have crossed the boundary again, in
+ * either order). Each drained object is instead reconciled from its current
+ * refcount (SynchronizeToggleState), which makes the deferral idempotent and
+ * ordering-insensitive.
+ *
+ * Entries hold no reference (taking one from inside a toggle handler would
+ * recursively fire the opposite toggle). A live wrapper's toggle ref keeps
+ * the object's refcount >= 1, so a queued object cannot be finalized under
+ * normal operation; as a safety net the GObjectFinalized weak callback and
+ * the wrapper teardown Cancel() any pending entry.
+ */
+class ToggleQueue {
+public:
+    /* Request a deferred synchronization of the object's toggle state.
+     * Callable from any thread. */
+    void Synchronize (GObject *gobject);
+
+    /* Drop the object's pending synchronization, if any. Callable from any
+     * thread. Must be called before the object can be finalized, so the
+     * drain never touches freed memory. */
+    void Cancel (GObject *gobject);
+
+private:
+    static gboolean Drain (gpointer user_data);
+
+    GMutex  lock;
+    GSList *objects;
+    guint   source;
+};
+
+extern ToggleQueue toggleQueue;
+
+}; /* GNodeJS */

package/src/value.cc

@@ -1293,15 +1293,24 @@ void FreeGIArgument(GITypeInfo *type_info, GIArgument *arg, GITransfer transfer,
         if (free_elements) {
             GITypeInfo *element_info = g_type_info_get_param_type(type_info, 0);
 
-            GITransfer  element_transfer  = GI_TRANSFER_EVERYTHING;
-            GIDirection element_direction = GI_DIRECTION_OUT;
+            /* Free elements in the direction they were allocated: an
+             * OUT/EVERYTHING list transferred us one reference per element,
+             * released here (the wrappers hold their own). An IN list was
+             * built by V8ToGIArgument, which allocates strings but borrows
+             * GObject/boxed pointers straight from their wrappers — freeing
+             * with IN/NOTHING releases the strings and leaves the borrowed
+             * pointers alone (mirrors FreeGIArgumentArray). Unreffing IN
+             * elements stole a reference per element from their real owners
+             * (e.g. Gdk.FileList.newFromList: the GFiles were finalized while
+             * the GdkFileList's deep copy still pointed at them). */
+            GITransfer  element_transfer  = is_in ? GI_TRANSFER_NOTHING : GI_TRANSFER_EVERYTHING;
             GIArgument  element_arg;
 
             GSList* list = (GSList *)arg->v_pointer;
 
             for (; list != NULL; list = list->next) {
                 element_arg.v_pointer = list->data;
-                FreeGIArgument(element_info, &element_arg, element_transfer, element_direction);
+                FreeGIArgument(element_info, &element_arg, element_transfer, direction);
             }
 
             g_base_info_unref(element_info);
@@ -1702,6 +1711,14 @@ void RefObjectForTransferFullIn (GITypeInfo *type_info, GIArgument *arg) {
     g_base_info_unref(iface);
 }
 
+// Documented on the declaration in value.h.
+void TakeOwnershipForTransferFull (GITypeInfo *type_info, GIArgument *arg, long length) {
+    CopyBoxedForTransferFullIn(type_info, arg, length);
+    RefObjectForTransferFullIn(type_info, arg);
+    RefFundamentalForTransferFullIn(type_info, arg);
+    RefVariantForTransferFullIn(type_info, arg);
+}
+
 
 /*
  * GValue conversion functions

package/src/value.h

@@ -52,6 +52,16 @@ void         CopyBoxedForTransferFullIn (GITypeInfo *type_info, GIArgument *arg,
 // under the callee once the wrapper is GC'd. See #439.
 void         RefObjectForTransferFullIn (GITypeInfo *type_info, GIArgument *arg);
 
+// Hand a transfer-full value its own reference for its new owner. A value whose
+// ownership transfers full — a transfer-full IN argument, or a transfer-full
+// callable return — is exactly one of boxed / GObject / fundamental / GVariant,
+// and the four per-kind helpers (CopyBoxedForTransferFullIn / RefObjectFor... /
+// RefFundamentalFor... / RefVariantFor...) each no-op for the other kinds. Runs
+// them all so the single call covers every kind. `length` is the element count
+// for a transfer-full C array of boxed pointers (-1 when not such an array).
+// See #439/#409/#468.
+void         TakeOwnershipForTransferFull (GITypeInfo *type_info, GIArgument *arg, long length);
+
 bool         CanConvertV8ToGIArgument (GITypeInfo *type_info, Local<Value> value, bool may_be_null);
 
 bool         V8ToGValue(GValue *gvalue, Local<Value> value, ResourceOwnership ownership = kNone);