@gtkx/runtime 1.0.0-rc.4 → 1.0.0

package/dist/vfunc.d.ts

@@ -0,0 +1,8 @@
+import { type AnyClass } from "@gtkx/utils";
+import type { Arg } from "./arg.js";
+import { type VfuncDescriptor } from "./registry.js";
+declare function findClassVfuncDescriptor(klass: AnyClass, methodName: string): VfuncDescriptor | null;
+declare function findInterfaceVfuncDescriptor(interfaceGtype: bigint, methodName: string): VfuncDescriptor | undefined;
+declare function vfuncArgs(descriptor: VfuncDescriptor): Arg[];
+export { findClassVfuncDescriptor, findInterfaceVfuncDescriptor, vfuncArgs };
+//# sourceMappingURL=vfunc.d.ts.map

package/dist/vfunc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfunc.d.ts","sourceRoot":"","sources":["../src/vfunc.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,QAAQ,EAAkC,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEpC,OAAO,EAA+C,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAElG,iBAAS,wBAAwB,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAE7F;AAED,iBAAS,4BAA4B,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAE7G;AAcD,iBAAS,SAAS,CAAC,UAAU,EAAE,eAAe,GAAG,GAAG,EAAE,CAErD;AAED,OAAO,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,SAAS,EAAE,CAAC"}

package/dist/vfunc.js

@@ -0,0 +1,23 @@
+import { getParentClass, walkClassChain } from "@gtkx/utils";
+import { isCallerAllocatedOut } from "./callback.js";
+import { getInterfaceVfuncRegistry, getVfuncRegistry } from "./registry.js";
+function findClassVfuncDescriptor(klass, methodName) {
+    return walkClassChain(getParentClass(klass), (cls) => getVfuncRegistry(cls)?.[methodName]) ?? null;
+}
+function findInterfaceVfuncDescriptor(interfaceGtype, methodName) {
+    return getInterfaceVfuncRegistry(interfaceGtype)?.[methodName];
+}
+function vfuncArg(descriptor) {
+    if (descriptor.kind === "ref") {
+        return { type: descriptor.innerDescriptor, direction: descriptor.inout === true ? "inout" : "out" };
+    }
+    if (isCallerAllocatedOut(descriptor)) {
+        return { type: descriptor, direction: "out", isCallerAllocated: true };
+    }
+    return { type: descriptor };
+}
+function vfuncArgs(descriptor) {
+    return descriptor.argDescriptors.map((argDescriptor) => vfuncArg(argDescriptor));
+}
+export { findClassVfuncDescriptor, findInterfaceVfuncDescriptor, vfuncArgs };
+//# sourceMappingURL=vfunc.js.map

package/dist/vfunc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfunc.js","sourceRoot":"","sources":["../src/vfunc.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,yBAAyB,EAAE,gBAAgB,EAAwB,MAAM,eAAe,CAAC;AAElG,SAAS,wBAAwB,CAAC,KAAe,EAAE,UAAkB;IACjE,OAAO,cAAc,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,IAAI,IAAI,CAAC;AACvG,CAAC;AAED,SAAS,4BAA4B,CAAC,cAAsB,EAAE,UAAkB;IAC5E,OAAO,yBAAyB,CAAC,cAAc,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC;AACnE,CAAC;AAED,SAAS,QAAQ,CAAC,UAAsB;IACpC,IAAI,UAAU,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,eAAe,EAAE,SAAS,EAAE,UAAU,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;IACxG,CAAC;IAED,IAAI,oBAAoB,CAAC,UAAU,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC;IAC3E,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAChC,CAAC;AAED,SAAS,SAAS,CAAC,UAA2B;IAC1C,OAAO,UAAU,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,aAAa,EAAE,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AACrF,CAAC;AAED,OAAO,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,SAAS,EAAE,CAAC","sourcesContent":["import type { Descriptor } from \"@gtkx/native\";\nimport { type AnyClass, getParentClass, walkClassChain } from \"@gtkx/utils\";\nimport type { Arg } from \"./arg.js\";\nimport { isCallerAllocatedOut } from \"./callback.js\";\nimport { getInterfaceVfuncRegistry, getVfuncRegistry, type VfuncDescriptor } from \"./registry.js\";\n\nfunction findClassVfuncDescriptor(klass: AnyClass, methodName: string): VfuncDescriptor | null {\n    return walkClassChain(getParentClass(klass), (cls) => getVfuncRegistry(cls)?.[methodName]) ?? null;\n}\n\nfunction findInterfaceVfuncDescriptor(interfaceGtype: bigint, methodName: string): VfuncDescriptor | undefined {\n    return getInterfaceVfuncRegistry(interfaceGtype)?.[methodName];\n}\n\nfunction vfuncArg(descriptor: Descriptor): Arg {\n    if (descriptor.kind === \"ref\") {\n        return { type: descriptor.innerDescriptor, direction: descriptor.inout === true ? \"inout\" : \"out\" };\n    }\n\n    if (isCallerAllocatedOut(descriptor)) {\n        return { type: descriptor, direction: \"out\", isCallerAllocated: true };\n    }\n\n    return { type: descriptor };\n}\n\nfunction vfuncArgs(descriptor: VfuncDescriptor): Arg[] {\n    return descriptor.argDescriptors.map((argDescriptor) => vfuncArg(argDescriptor));\n}\n\nexport { findClassVfuncDescriptor, findInterfaceVfuncDescriptor, vfuncArgs };\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/runtime",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0",
   "description": "FFI runtime the generated GTKX bindings call into: type descriptors, GValue marshalling, signals, GObject lifecycle",
   "keywords": [
     "gtkx",
@@ -45,11 +45,11 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@gtkx/native": "1.0.0-rc.4",
-    "@gtkx/utils": "1.0.0-rc.4"
+    "@gtkx/native": "1.0.0",
+    "@gtkx/utils": "1.0.0"
   },
   "devDependencies": {
-    "@gtkx/vitest": "1.0.0-rc.4"
+    "@gtkx/vitest": "1.0.0"
   },
   "scripts": {
     "release": "tsx ../../scripts/release-package.ts"

package/src/application-class.ts

@@ -0,0 +1,116 @@
+import { type AnyClass, getOrInsert } from "@gtkx/utils";
+import { registerClass } from "./register-class.js";
+import { getClassType } from "./registry.js";
+import { typeName } from "./type.js";
+import { callParent } from "./vfunc-call.js";
+
+type CommandLineResult = [boolean, string[], number];
+
+/**
+ * The GIO application surface {@link createApplication} builds on, which `Gio.Application` and
+ * every subclass of it satisfies structurally.
+ */
+type CommandLineApplication = {
+    /** Marks the application as quitting, so GLib's own `run` returns without driving a main loop. */
+    quit(): void;
+};
+
+type LocalCommandLineApplication = {
+    runLocalCommandLine(argv: string[]): CommandLineResult;
+};
+
+type ShutdownApplication = {
+    run(argv: string[]): number;
+};
+
+/** An application class together with the construct properties it accepts. */
+type ApplicationClass<T extends CommandLineApplication, P> = AnyClass<T> & (new (props: P) => T);
+
+const derivedClasses: WeakMap<AnyClass, AnyClass> = new WeakMap();
+const derivedApplicationClasses: Set<AnyClass> = new Set();
+const quitApplications: WeakSet<object> = new WeakSet();
+const shuttingDownApplications: WeakSet<object> = new WeakSet();
+
+const derivedTypeName = (base: AnyClass): string => `Gtkx${typeName(getClassType(base)) ?? base.name}`;
+
+const buildApplicationClass = (base: AnyClass<CommandLineApplication>): AnyClass<CommandLineApplication> => {
+    class DerivedApplication extends base {
+        runLocalCommandLine(argv: string[]): CommandLineResult {
+            return this.vfuncLocalCommandLine(argv);
+        }
+
+        protected vfuncLocalCommandLine(argv: string[]): CommandLineResult {
+            if (shuttingDownApplications.has(this)) {
+                this.quit();
+
+                return [true, argv, 0];
+            }
+
+            return callParent(DerivedApplication, "vfuncLocalCommandLine", this, argv) as CommandLineResult;
+        }
+
+        protected vfuncNameLost(): boolean {
+            quitApplications.add(this);
+
+            return callParent(DerivedApplication, "vfuncNameLost", this) as boolean;
+        }
+
+        override quit(): void {
+            quitApplications.add(this);
+            super.quit();
+        }
+    }
+
+    const derived = registerClass(DerivedApplication, { typeName: derivedTypeName(base) });
+    derivedApplicationClasses.add(derived);
+
+    return derived;
+};
+
+const isDerivedApplication = (application: object): application is LocalCommandLineApplication => {
+    for (const derived of derivedApplicationClasses) {
+        if (application instanceof derived) {
+            return true;
+        }
+    }
+
+    return false;
+};
+
+const shutDownThroughRun = (application: ShutdownApplication): void => {
+    if (!isDerivedApplication(application) || quitApplications.has(application)) {
+        return;
+    }
+
+    shuttingDownApplications.add(application);
+
+    try {
+        application.run([]);
+    } finally {
+        shuttingDownApplications.delete(application);
+    }
+};
+
+const deriveApplicationClass = <T extends CommandLineApplication>(base: AnyClass<T>): AnyClass<T> =>
+    getOrInsert(derivedClasses, base, () => buildApplicationClass(base)) as AnyClass<T>;
+
+/**
+ * Constructs an application GTKX can shut down. GLib parses an application's command line at most
+ * once per instance and crashes on a second parse, so {@link runApplication} and
+ * {@link quitApplication} only accept an application built here.
+ *
+ * @param base The application class to construct, such as `Gtk.Application`.
+ * @param props Construct properties, passed through unchanged.
+ * @returns An instance of a class derived from `base`, registered once per base class as its own GType.
+ */
+const createApplication = <T extends CommandLineApplication, P>(base: ApplicationClass<T, P>, props: P): T =>
+    new (deriveApplicationClass(base) as new (props: P) => T)(props);
+
+export {
+    createApplication,
+    isDerivedApplication,
+    shutDownThroughRun,
+    type ApplicationClass,
+    type CommandLineApplication,
+    type LocalCommandLineApplication,
+};

package/src/arg.ts

@@ -16,5 +16,6 @@ const isOutputArg = (arg: Arg): boolean => arg.direction !== undefined;
 const isInoutArg = (arg: Arg): boolean => arg.direction === "inout";
 const isCallerAllocatedArg = (arg: Arg): boolean => arg.isCallerAllocated === true;
 const isRefArg = (arg: Arg): boolean => arg.direction !== undefined && arg.isCallerAllocated !== true;
+const requiresInputArg = (arg: Arg): boolean => !isRefArg(arg) || isInoutArg(arg);
 
-export { isOutputArg, isInoutArg, isCallerAllocatedArg, isRefArg, type Arg };
+export { isOutputArg, isInoutArg, isCallerAllocatedArg, isRefArg, requiresInputArg, type Arg };

package/src/bind.ts

@@ -1,5 +1,16 @@
 import { call, type Descriptor, bind as nativeBind } from "@gtkx/native";
 
+/**
+ * Precompiles a call to a C function, marshalling the values it is given through the argument
+ * descriptors and the result through the return one. The symbol is resolved in the shared library
+ * on the first call.
+ *
+ * @param sharedLibrary The shared library to resolve the symbol in.
+ * @param symbol The name of the C function to bind.
+ * @param argDescriptors Describe the C arguments, in declaration order.
+ * @param returnDescriptor Describes the C return value.
+ * @returns A function calling the bound symbol.
+ */
 function bind(
     sharedLibrary: string,
     symbol: string,

package/src/callback.ts

@@ -4,10 +4,13 @@ import { fromNative, toNative } from "./native-value.js";
 import { getHandle } from "./registry.js";
 import { splitTupleResult } from "./tuple.js";
 import { copyValue } from "./value.js";
+import { popSeedFrame, pushSeedFrame, type RefSeeds } from "./vfunc-seeds.js";
 
 type Callback = (...args: unknown[]) => unknown;
 type CallbackReceiver = "this" | "emitter" | "none";
-type OutParam = { value: unknown; descriptor: Descriptor };
+type OutParam = { value: unknown; descriptor: Descriptor; argIndex: number };
+type LengthLink = { target: OutParam; sourceIndex: number };
+type OutParamGroups = { lengthLinks: LengthLink[]; valueParams: OutParam[] };
 
 type CallbackSpec = {
     argDescriptors: Descriptor[];
@@ -21,6 +24,8 @@ type CallbackPlan = {
     returnDescriptor: Descriptor;
     start: number;
     receiver: CallbackReceiver;
+    hasOutParams: boolean;
+    hasRefOutParams: boolean;
 };
 
 const fillCallerAllocatedBuffer = (descriptor: Descriptor, target: object, source: object): void => {
@@ -46,23 +51,23 @@ const collectRefArg = (
     descriptor: RefDescriptor,
     wrappedValue: unknown,
     inputs: unknown[],
-    outParams: OutParam[],
+    out: { params: OutParam[]; argIndex: number },
 ): void => {
     if (descriptor.inout === true) {
         inputs.push((wrappedValue as { value: unknown }).value);
     }
 
-    outParams.push({ value: wrappedValue, descriptor });
+    out.params.push({ value: wrappedValue, descriptor, argIndex: out.argIndex });
 };
 
 const collectCallbackArg = (
     descriptor: Descriptor | undefined,
     wrappedValue: unknown,
     inputs: unknown[],
-    outParams: OutParam[],
+    out: { params: OutParam[]; argIndex: number },
 ): void => {
     if (descriptor?.kind === "ref") {
-        collectRefArg(descriptor, wrappedValue, inputs, outParams);
+        collectRefArg(descriptor, wrappedValue, inputs, out);
 
         return;
     }
@@ -70,7 +75,7 @@ const collectCallbackArg = (
     inputs.push(wrappedValue);
 
     if (descriptor !== undefined && isCallerAllocatedOut(descriptor)) {
-        outParams.push({ value: wrappedValue, descriptor });
+        out.params.push({ value: wrappedValue, descriptor, argIndex: out.argIndex });
     }
 };
 
@@ -80,43 +85,173 @@ const partitionCallbackArgs = (
     start: number,
 ): { inputs: unknown[]; outParams: OutParam[] } => {
     const inputs: unknown[] = [];
-    const outParams: OutParam[] = [];
+    const params: OutParam[] = [];
+    const collected = { params, argIndex: start };
 
     for (let i = start; i < effectiveTypes.length; i++) {
-        collectCallbackArg(effectiveTypes[i], wrapped[i], inputs, outParams);
+        collected.argIndex = i;
+        collectCallbackArg(effectiveTypes[i], wrapped[i], inputs, collected);
     }
 
-    return { inputs, outParams };
+    return { inputs, outParams: params };
 };
 
-const writeOutParams = (outParams: OutParam[], outValues: unknown[]): void => {
+const hasOutParamArg = (descriptor: Descriptor | undefined): boolean =>
+    descriptor !== undefined && (descriptor.kind === "ref" || isCallerAllocatedOut(descriptor));
+
+const hasRefOutParamArg = (descriptor: Descriptor | undefined): boolean =>
+    descriptor?.kind === "ref" && descriptor.inout !== true;
+
+const haveOutParamArgs = (effectiveTypes: Descriptor[], start: number): boolean =>
+    effectiveTypes.slice(start).some((descriptor) => hasOutParamArg(descriptor));
+
+const haveRefOutParamArgs = (effectiveTypes: Descriptor[], start: number): boolean =>
+    effectiveTypes.slice(start).some((descriptor) => hasRefOutParamArg(descriptor));
+
+const sizeParamIndexFor = (descriptor: Descriptor): number | undefined => {
+    if (descriptor.kind !== "ref") {
+        return undefined;
+    }
+
+    const { innerDescriptor } = descriptor;
+
+    return innerDescriptor.kind === "array" ? innerDescriptor.sizeParamIndex : undefined;
+};
+
+const lengthOutParamIndices = (outParams: OutParam[]): Map<number, number> => {
+    const indices: Map<number, number> = new Map();
+
+    for (const outParam of outParams) {
+        const sizeParamIndex = sizeParamIndexFor(outParam.descriptor);
+
+        if (sizeParamIndex !== undefined) {
+            indices.set(sizeParamIndex, outParam.argIndex);
+        }
+    }
+
+    return indices;
+};
+
+const writeOutParams = (outParams: OutParam[], outValues: unknown[]): Map<number, unknown> => {
+    const written: Map<number, unknown> = new Map();
+
     for (const [position, outParam] of outParams.entries()) {
         const outValue = outValues[position];
+        const { descriptor } = outParam;
+        written.set(outParam.argIndex, outValue);
 
-        if (outParam.descriptor.kind === "ref") {
-            (outParam.value as { value: unknown }).value = outValue;
+        if (descriptor.kind === "ref") {
+            (outParam.value as { value: unknown }).value = toNative(descriptor.innerDescriptor, outValue);
         } else if (outValue != null && outParam.value != null) {
-            fillCallerAllocatedBuffer(outParam.descriptor, outParam.value, outValue);
+            fillCallerAllocatedBuffer(descriptor, outParam.value, outValue);
         }
     }
+
+    return written;
+};
+
+const groupOutParams = (outParams: OutParam[]): OutParamGroups => {
+    const lengths = lengthOutParamIndices(outParams);
+    const groups: OutParamGroups = { lengthLinks: [], valueParams: [] };
+
+    for (const outParam of outParams) {
+        const sourceIndex = lengths.get(outParam.argIndex);
+
+        if (sourceIndex === undefined) {
+            groups.valueParams.push(outParam);
+        } else {
+            groups.lengthLinks.push({ target: outParam, sourceIndex });
+        }
+    }
+
+    return groups;
+};
+
+const getFoldedLength = (source: unknown): number => {
+    const length = (source as { length?: unknown } | null | undefined)?.length;
+
+    return typeof length === "number" ? length : 0;
+};
+
+const writeFoldedLengths = (lengthLinks: LengthLink[], written: Map<number, unknown>): void => {
+    for (const link of lengthLinks) {
+        (link.target.value as { value: unknown }).value = getFoldedLength(written.get(link.sourceIndex));
+    }
+};
+
+const collectRefSeeds = (outParams: OutParam[]): RefSeeds => {
+    const seeds: RefSeeds = new Map();
+
+    for (const outParam of outParams) {
+        const seed = (outParam.value as { value?: unknown } | null)?.value;
+
+        if (seed != null && hasRefOutParamArg(outParam.descriptor)) {
+            seeds.set(outParam.argIndex, seed);
+        }
+    }
+
+    return seeds;
+};
+
+const applyCallback = (plan: CallbackPlan, thisArg: unknown, inputs: unknown[], outParams: OutParam[]): unknown => {
+    if (!plan.hasRefOutParams) {
+        return plan.fn.apply(thisArg, inputs);
+    }
+
+    pushSeedFrame({ argDescriptors: plan.effectiveTypes, instance: thisArg, seeds: collectRefSeeds(outParams) });
+
+    try {
+        return plan.fn.apply(thisArg, inputs);
+    } finally {
+        popSeedFrame();
+    }
 };
 
 const getThisArg = (receiver: CallbackReceiver, wrapped: unknown[]): unknown =>
     receiver === "this" ? (wrapped[0] ?? null) : null;
 
+const wrapCallbackArgs = (effectiveTypes: Descriptor[], rawArgs: unknown[]): void => {
+    let index = 0;
+
+    for (const descriptor of effectiveTypes) {
+        rawArgs[index] = fromNative(descriptor, rawArgs[index]);
+        index += 1;
+    }
+};
+
+const trimCallbackInputs = (plan: CallbackPlan, wrapped: unknown[]): unknown[] => {
+    const count = plan.effectiveTypes.length;
+
+    if (wrapped.length > count) {
+        wrapped.length = count;
+    }
+
+    for (let index = 0; index < plan.start; index++) {
+        wrapped.shift();
+    }
+
+    return wrapped;
+};
+
 const runCallback = (plan: CallbackPlan, rawArgs: unknown[]): unknown => {
     const { effectiveTypes, returnDescriptor } = plan;
-    const wrapped = effectiveTypes.map((descriptor, i) => fromNative(descriptor, rawArgs[i]));
-    const thisArg = getThisArg(plan.receiver, wrapped);
-    const { inputs, outParams } = partitionCallbackArgs(effectiveTypes, wrapped, plan.start);
-    const result = plan.fn.apply(thisArg, inputs);
+    wrapCallbackArgs(effectiveTypes, rawArgs);
+    const thisArg = getThisArg(plan.receiver, rawArgs);
+
+    if (!plan.hasOutParams) {
+        return toNative(returnDescriptor, plan.fn.apply(thisArg, trimCallbackInputs(plan, rawArgs)));
+    }
+
+    const { inputs, outParams } = partitionCallbackArgs(effectiveTypes, rawArgs, plan.start);
+    const result = applyCallback(plan, thisArg, inputs, outParams);
 
     if (outParams.length === 0) {
         return toNative(returnDescriptor, result);
     }
 
-    const { primary, outValues } = splitTupleResult(result, returnDescriptor.kind !== "void", outParams.length);
-    writeOutParams(outParams, outValues);
+    const { lengthLinks, valueParams } = groupOutParams(outParams);
+    const { primary, outValues } = splitTupleResult(result, returnDescriptor.kind !== "void", valueParams.length);
+    writeFoldedLengths(lengthLinks, writeOutParams(valueParams, outValues));
 
     return toNative(returnDescriptor, primary);
 };
@@ -135,15 +270,20 @@ const wrapCallbackValue = (spec: CallbackDescriptor, callback: unknown): unknown
     callback == null ? callback : wrapCallback(callback as Callback, spec, "none");
 
 function wrapCallback(fn: Callback, spec: CallbackSpec, receiver: CallbackReceiver): Callback {
+    const effectiveTypes = getEffectiveTypes(spec);
+    const start = receiver === "none" ? 0 : 1;
+
     const plan: CallbackPlan = {
         fn,
-        effectiveTypes: getEffectiveTypes(spec),
+        effectiveTypes,
         returnDescriptor: spec.returnDescriptor,
-        start: receiver === "none" ? 0 : 1,
+        start,
         receiver,
+        hasOutParams: haveOutParamArgs(effectiveTypes, start),
+        hasRefOutParams: haveRefOutParamArgs(effectiveTypes, start),
     };
 
     return (...rawArgs: unknown[]): unknown => runCallback(plan, rawArgs);
 }
 
-export { wrapCallbackValue, wrapCallback };
+export { isCallerAllocatedOut, wrapCallbackValue, wrapCallback };

package/src/closure.ts

@@ -0,0 +1,136 @@
+import { type ExternalObject, type Handle, read } from "@gtkx/native";
+import { type AnyClass } from "@gtkx/utils";
+import { bind } from "./bind.js";
+import { boxedT, callbackT, sizedArrayT, structT, uint32T, uint64T, voidT } from "./descriptors.js";
+import { CLOSURE_SIZE, LIB, VALUE_SIZE, VALUE_T } from "./library.js";
+import { getClassType, getHandle, getWrapperClass, instanceClassName, wrapHandle } from "./registry.js";
+import { resolveBoxedType, typeIsA } from "./type.js";
+import { fromValue, getValueType, intoValue } from "./value.js";
+
+/**
+ * Handler backing a `GClosure`. It receives the closure's parameters already converted from their
+ * `GValue`s, and its result is written back into the closure's return `GValue` when it has one.
+ *
+ * A parameter that is itself a `GValue`, such as the target a property binding transform fills in,
+ * arrives as the caller's own `GObject.Value` rather than a copy, so writing to it is how the
+ * handler produces that parameter's value. It stops being valid once the handler returns.
+ */
+type ClosureCallback = (...args: never[]) => unknown;
+
+const CCLOSURE_CALLBACK_OFFSET = CLOSURE_SIZE;
+const N_PARAM_VALUES_INDEX = 2;
+const MARSHAL_DATA_INDEX = 5;
+const CLOSURE_T = boxedT("GClosure", { sharedLibrary: LIB, getTypeFnName: "g_closure_get_type" });
+
+const OWNED_CLOSURE_T = boxedT("GClosure", {
+    ownership: "full",
+    sharedLibrary: LIB,
+    getTypeFnName: "g_closure_get_type",
+});
+
+const MARSHAL_VALUE_T = boxedT("GValue", {
+    sharedLibrary: LIB,
+    getTypeFnName: "g_value_get_type",
+    size: VALUE_SIZE,
+    isCallerAllocated: true,
+});
+
+const MARSHAL_T = callbackT(
+    [
+        CLOSURE_T,
+        MARSHAL_VALUE_T,
+        uint32T,
+        sizedArrayT(MARSHAL_VALUE_T, N_PARAM_VALUES_INDEX, "borrowed", VALUE_SIZE),
+        uint64T,
+        uint64T,
+    ],
+    voidT,
+    {
+        hasUserData: true,
+        userDataIndex: MARSHAL_DATA_INDEX,
+        hasDestroy: true,
+        destroyKind: "closureNotify",
+        scope: "notified",
+    },
+);
+
+const NESTED_VALUE_T = structT("borrowed");
+const gCclosureNew = bind(LIB, "g_cclosure_new", [MARSHAL_T], OWNED_CLOSURE_T);
+const gValueGetBoxed = bind(LIB, "g_value_get_boxed", [VALUE_T], NESTED_VALUE_T);
+const gClosureRef = bind(LIB, "g_closure_ref", [CLOSURE_T], uint64T);
+const gClosureSink = bind(LIB, "g_closure_sink", [CLOSURE_T], voidT);
+const gClosureSetMarshal = bind(LIB, "g_closure_set_marshal", [CLOSURE_T, uint64T], voidT);
+
+const isClosureInstance = (value: object): boolean =>
+    typeIsA(getClassType(value.constructor as AnyClass), resolveBoxedType(CLOSURE_T));
+
+const getNestedValue = (param: ExternalObject<Handle>): object | null =>
+    wrapHandle(gValueGetBoxed(param) as ExternalObject<Handle> | null, getWrapperClass(resolveBoxedType(VALUE_T)));
+
+const fromParamValue = (param: ExternalObject<Handle>): unknown =>
+    getValueType(param) === resolveBoxedType(VALUE_T) ? getNestedValue(param) : fromValue(param);
+
+function describeValue(value: unknown): string {
+    if (value === null) {
+        return "null";
+    }
+
+    if (typeof value !== "object") {
+        return typeof value;
+    }
+
+    return instanceClassName(value);
+}
+
+function marshalFor(callback: ClosureCallback): (...args: unknown[]) => void {
+    return (_closure: unknown, returnValue: unknown, _count: unknown, paramValues: unknown): void => {
+        const values = paramValues as ExternalObject<Handle>[];
+        const args = values.map((value) => fromParamValue(value));
+        const result = (callback as (...values: unknown[]) => unknown)(...(args as never[]));
+
+        if (returnValue !== null) {
+            intoValue(returnValue as ExternalObject<Handle>, result);
+        }
+    };
+}
+
+function newClosure(callback: ClosureCallback): ExternalObject<Handle> {
+    const handle = gCclosureNew(marshalFor(callback)) as ExternalObject<Handle>;
+    const marshal = read(handle, uint64T, CCLOSURE_CALLBACK_OFFSET);
+    gClosureRef(handle);
+    gClosureSink(handle);
+    gClosureSetMarshal(handle, marshal);
+
+    return handle;
+}
+
+/**
+ * Marshals a value passed where a `GObject.Closure` is expected into a closure handle: a function
+ * becomes a new `GClosure` dispatching into it, and an existing closure yields its own handle.
+ * @param value Function to wrap, or an already-built closure.
+ * @throws {ClosureMarshalError} When the value is neither.
+ */
+function toClosure(value: unknown): ExternalObject<Handle> {
+    if (typeof value === "function") {
+        return newClosure(value as ClosureCallback);
+    }
+
+    if (typeof value === "object" && value !== null && isClosureInstance(value)) {
+        return getHandle(value);
+    }
+
+    throw new ClosureMarshalError(`Cannot marshal ${describeValue(value)} into a GObject.Closure`);
+}
+
+/** Same as {@link toClosure}, but passes a null or undefined value through as no closure at all. */
+function tryToClosure(value: unknown): ExternalObject<Handle> | undefined {
+    return value == null ? undefined : toClosure(value);
+}
+
+/** Thrown when a value passed where a `GObject.Closure` is expected cannot be marshalled into one. */
+class ClosureMarshalError extends TypeError {
+    /** Name callers match on when the error is caught as a plain `TypeError`. */
+    public override name = "ClosureMarshalError";
+}
+
+export { type ClosureCallback, ClosureMarshalError, toClosure, tryToClosure };