node-gtk 4.0.0 → 4.1.0

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/loop.js

@@ -45,10 +45,22 @@ function start() {
  * macrotask lets the module's top-level microtask return first, so the queue
  * drains and the loop integration takes over from a clean (non-nested) state.
  *
+ * We defer with setTimeout, NOT setImmediate. A setImmediate callback runs
+ * *inside* Node's immediate-processing machinery (native CheckImmediate ->
+ * processImmediate). Because `run` never returns (it blocks in the GLib main
+ * loop until the app quits), CheckImmediate never reaches the code that stops
+ * Node's private immediate uv_idle handle, so that handle stays active forever.
+ * An active idle handle pins uv_backend_timeout() at 0, which makes the nested
+ * uv-in-GLib loop busy-spin at 100% CPU (worse on Node 26 / libuv 1.52, where
+ * the immediate's wakeup eventfd also stays signalled). A one-shot timer is
+ * removed from libuv's timer heap before its callback runs, so blocking inside
+ * it leaves no libuv state active and the loop can sleep normally. See #477.
+ *
  * Under CommonJS (and inside signal callbacks) we are not in a microtask, so we
  * run synchronously and preserve the original blocking semantics exactly.
  *
  * https://github.com/romgrk/node-gtk/issues/442
+ * https://github.com/romgrk/node-gtk/issues/477
  *
  * Returns the native call's result when run synchronously (so e.g.
  * `const status = app.run()` keeps working under CommonJS); returns undefined
@@ -64,7 +76,7 @@ function runLoopEntry(run) {
   start()
 
   if (internal.IsRunningMicrotasks()) {
-    setImmediate(run)
+    setTimeout(run, 0)
     return undefined
   }
   return run()

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.0",
+  "version": "4.1.0",
   "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

@@ -220,6 +220,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

@@ -35,6 +35,32 @@ namespace GNodeJS {
     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 +147,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 +509,10 @@ NAN_METHOD(SetInterfaceMethodsApplier) {
     GNodeJS::SetInterfaceMethodsApplier(info);
 }
 
+NAN_METHOD(SetTypeMaterializer) {
+    GNodeJS::SetTypeMaterializerInternal(info[0].As<v8::Function>());
+}
+
 NAN_METHOD(RegisterClass) {
     GNodeJS::ObjectClass::RegisterClass(info);
 }
@@ -438,6 +533,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

@@ -26,6 +26,21 @@ extern Nan::Persistent<Object> moduleCache;
 
 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

@@ -878,6 +878,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 +903,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/value.cc

@@ -1702,6 +1702,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);