@gtkx/runtime 1.0.0-rc.3 → 1.0.0

package/dist/vfunc-call.js

@@ -0,0 +1,168 @@
+import { bindVfunc } from "@gtkx/native";
+import { isCallerAllocatedArg, requiresInputArg } from "./arg.js";
+import { buildNativeArgTypes, fromNativeCallable } from "./fn.js";
+import { toNative } from "./native-value.js";
+import { getClassType, getHandle, getInterfaceVfuncRegistry, getVfuncRegistry, instanceClassName, resolveWrapperType, } from "./registry.js";
+import { TYPE_INVALID, typeInterfaces, typeIsA, typeParent } from "./type.js";
+import { seedsFor } from "./vfunc-seeds.js";
+import { findClassVfuncDescriptor, findInterfaceVfuncDescriptor, vfuncArgs } from "./vfunc.js";
+const NO_BASELINE = -1;
+const SEEDED_SLOTS = {
+    "LayoutManagerClass.measure": new Map([[6, NO_BASELINE], [7, NO_BASELINE]]),
+    "WidgetClass.measure": new Map([[5, NO_BASELINE], [6, NO_BASELINE]]),
+};
+const parentInvokers = new WeakMap();
+const vfuncInvokers = new WeakMap();
+function toNativeInput(arg, input) {
+    return isCallerAllocatedArg(arg) ? input : toNative(arg.type, input);
+}
+function bindOptionsFor(slot, instanceType, args, label) {
+    const { descriptor, interfaceType } = slot;
+    const options = {
+        byteOffset: descriptor.byteOffset,
+        label,
+        argDescriptors: buildNativeArgTypes(args, descriptor.canThrow === true),
+        returnDescriptor: descriptor.returnDescriptor,
+    };
+    if (descriptor.vtableSize !== undefined) {
+        options.vtableSize = descriptor.vtableSize;
+    }
+    if (instanceType !== undefined) {
+        options.instanceType = instanceType;
+    }
+    if (interfaceType !== undefined) {
+        options.interfaceType = interfaceType;
+    }
+    return options;
+}
+function buildInvoker(slot, instanceType, caller) {
+    const { descriptor } = slot;
+    const args = vfuncArgs(descriptor);
+    const canThrow = descriptor.canThrow === true;
+    const label = `${descriptor.className}.${descriptor.vfuncName}`;
+    const [, ...inputArgs] = args.filter(requiresInputArg);
+    let pendingSeeds;
+    const takeRefSeeds = () => {
+        const seeds = pendingSeeds;
+        pendingSeeds = undefined;
+        return seeds;
+    };
+    const shaped = fromNativeCallable(bindVfunc(bindOptionsFor(slot, instanceType, args, label)), { args, returns: descriptor.returnDescriptor, canThrow }, takeRefSeeds);
+    return (instance, inputs) => {
+        if (inputs.length !== inputArgs.length) {
+            throw new Error(`${caller}: ${label} expects ${String(inputArgs.length)} arguments, ` +
+                `received ${String(inputs.length)}`);
+        }
+        const nativeInputs = inputArgs.map((arg, index) => toNativeInput(arg, inputs[index]));
+        pendingSeeds = SEEDED_SLOTS[label] ?? seedsFor(descriptor.argDescriptors, instance);
+        return shaped(getHandle(instance), ...nativeInputs);
+    };
+}
+function cachedInvoker(cache, owner, key, build) {
+    let byKey = cache.get(owner);
+    if (byKey === undefined) {
+        byKey = new Map();
+        cache.set(owner, byKey);
+    }
+    let invoker = byKey.get(key);
+    if (invoker === undefined) {
+        invoker = build();
+        byKey.set(key, invoker);
+    }
+    return invoker;
+}
+function resolveParentSlot(klass, parentType, methodName) {
+    const classDescriptor = findClassVfuncDescriptor(klass, methodName);
+    if (classDescriptor) {
+        return { descriptor: classDescriptor };
+    }
+    for (const interfaceType of typeInterfaces(parentType)) {
+        const descriptor = findInterfaceVfuncDescriptor(interfaceType, methodName);
+        if (descriptor) {
+            return { descriptor, interfaceType };
+        }
+    }
+    return undefined;
+}
+function resolveParentType(klass, methodName) {
+    const gtype = getClassType(klass);
+    if (gtype === TYPE_INVALID) {
+        throw new Error(`callParent: cannot call '${methodName}' because ${klass.name} was never passed to registerClass`);
+    }
+    return typeParent(gtype);
+}
+function buildParentInvoker(klass, methodName) {
+    const parentType = resolveParentType(klass, methodName);
+    const slot = resolveParentSlot(klass, parentType, methodName);
+    if (!slot) {
+        throw new Error(`callParent: ${klass.name} inherits no '${methodName}' vtable slot`);
+    }
+    return buildInvoker(slot, parentType, "callParent");
+}
+/**
+ * Calls the implementation of a virtual function that the parent type of `klass` provides, so an
+ * override can chain up to the behavior it replaces. `klass` is the class whose override is
+ * running, named lexically rather than taken from `instance`, so each level of a hierarchy reaches
+ * exactly one level up. Arguments and the return value follow the same convention the override
+ * itself uses: pure out parameters are left out and returned instead, and a slot with several
+ * outputs returns them as a tuple. Throws if `klass` was never registered, inherits no such slot,
+ * or the parent type leaves the slot empty.
+ *
+ * @param klass The registered class whose override is chaining up.
+ * @param methodName Name of the overridden method, such as `vfuncMeasure`.
+ * @param instance The instance the override was invoked on.
+ * @param inputs The arguments the override received.
+ */
+function callParent(klass, methodName, instance, ...inputs) {
+    const invoker = cachedInvoker(parentInvokers, klass, methodName, () => buildParentInvoker(klass, methodName));
+    return invoker(instance, inputs);
+}
+function resolveOwnerSlot(owner, key) {
+    const classDescriptor = getVfuncRegistry(owner)?.[key];
+    if (classDescriptor !== undefined) {
+        return { descriptor: classDescriptor };
+    }
+    const interfaceType = getClassType(owner);
+    const descriptor = getInterfaceVfuncRegistry(interfaceType)?.[key];
+    if (descriptor === undefined) {
+        throw new Error(`callVfunc: ${owner.name} declares no '${key}' vtable slot`);
+    }
+    return { descriptor, interfaceType };
+}
+function requiresDefaultVtable(slot, instanceType) {
+    return slot.interfaceType !== undefined && !typeIsA(instanceType, slot.interfaceType);
+}
+function resolveInstanceType(key, instance, slot) {
+    const instanceType = resolveWrapperType(instance);
+    if (instanceType === TYPE_INVALID) {
+        const name = instanceClassName(instance);
+        throw new Error(`callVfunc: cannot call '${key}' because ${name} descends from no registered wrapper class`);
+    }
+    return requiresDefaultVtable(slot, instanceType) ? undefined : instanceType;
+}
+/**
+ * Calls the implementation of a virtual function a wrapper class or interface declares, backing the
+ * `vfunc`-prefixed members the generated bindings emit. The slot is read from the nearest generated
+ * wrapper class in the instance's class chain rather than from the instance's own type, so an
+ * override reaching it through `super` runs the implementation it replaced instead of re-entering
+ * itself. When that wrapper class does not carry the interface the slot belongs to, because a class
+ * registered below it adopted the interface, the slot comes from the interface's own default vtable
+ * instead, which holds exactly what the adopting class replaced. Arguments and the return value
+ * follow the same convention an override uses: pure out parameters are left out and returned
+ * instead, and a slot with several outputs returns them as a tuple. Throws if the owner declares no
+ * such slot, the instance descends from no wrapper class, or the resolved vtable leaves the slot
+ * empty.
+ *
+ * @param owner The wrapper class or interface declaring the slot.
+ * @param key Name of the generated member, such as `vfuncMeasure`.
+ * @param instance The instance to invoke the slot on.
+ * @param inputs The arguments the slot receives.
+ */
+function callVfunc(owner, key, instance, inputs) {
+    const slot = resolveOwnerSlot(owner, key);
+    const instanceType = resolveInstanceType(key, instance, slot);
+    const invoker = cachedInvoker(vfuncInvokers, owner, `${key}:${String(instanceType)}`, () => buildInvoker(slot, instanceType, "callVfunc"));
+    return invoker(instance, inputs);
+}
+export { callParent, callVfunc };
+//# sourceMappingURL=vfunc-call.js.map

package/dist/vfunc-call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfunc-call.js","sourceRoot":"","sources":["../src/vfunc-call.ts"],"names":[],"mappings":"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","sourcesContent":["import type { BindVfuncOptions } from \"@gtkx/native\";\nimport type { AnyClass } from \"@gtkx/utils\";\nimport { bindVfunc } from \"@gtkx/native\";\nimport { type Arg, isCallerAllocatedArg, requiresInputArg } from \"./arg.js\";\nimport { buildNativeArgTypes, fromNativeCallable } from \"./fn.js\";\nimport { toNative } from \"./native-value.js\";\nimport {\n    getClassType,\n    getHandle,\n    getInterfaceVfuncRegistry,\n    getVfuncRegistry,\n    instanceClassName,\n    resolveWrapperType,\n    type VfuncDescriptor,\n} from \"./registry.js\";\nimport { TYPE_INVALID, typeInterfaces, typeIsA, typeParent } from \"./type.js\";\nimport { type RefSeeds, seedsFor } from \"./vfunc-seeds.js\";\nimport { findClassVfuncDescriptor, findInterfaceVfuncDescriptor, vfuncArgs } from \"./vfunc.js\";\n\ntype Invoker = (instance: object, inputs: unknown[]) => unknown;\ntype InvokerCache = WeakMap<AnyClass, Map<string, Invoker>>;\ntype ResolvedSlot = { descriptor: VfuncDescriptor; interfaceType?: bigint };\n\nconst NO_BASELINE = -1;\n\nconst SEEDED_SLOTS: Record<string, RefSeeds> = {\n    \"LayoutManagerClass.measure\": new Map([[6, NO_BASELINE], [7, NO_BASELINE]]),\n    \"WidgetClass.measure\": new Map([[5, NO_BASELINE], [6, NO_BASELINE]]),\n};\n\nconst parentInvokers: InvokerCache = new WeakMap();\nconst vfuncInvokers: InvokerCache = new WeakMap();\n\nfunction toNativeInput(arg: Arg, input: unknown): unknown {\n    return isCallerAllocatedArg(arg) ? input : toNative(arg.type, input);\n}\n\nfunction bindOptionsFor(\n    slot: ResolvedSlot,\n    instanceType: bigint | undefined,\n    args: Arg[],\n    label: string,\n): BindVfuncOptions {\n    const { descriptor, interfaceType } = slot;\n\n    const options: BindVfuncOptions = {\n        byteOffset: descriptor.byteOffset,\n        label,\n        argDescriptors: buildNativeArgTypes(args, descriptor.canThrow === true),\n        returnDescriptor: descriptor.returnDescriptor,\n    };\n\n    if (descriptor.vtableSize !== undefined) {\n        options.vtableSize = descriptor.vtableSize;\n    }\n\n    if (instanceType !== undefined) {\n        options.instanceType = instanceType;\n    }\n\n    if (interfaceType !== undefined) {\n        options.interfaceType = interfaceType;\n    }\n\n    return options;\n}\n\nfunction buildInvoker(slot: ResolvedSlot, instanceType: bigint | undefined, caller: string): Invoker {\n    const { descriptor } = slot;\n    const args = vfuncArgs(descriptor);\n    const canThrow = descriptor.canThrow === true;\n    const label = `${descriptor.className}.${descriptor.vfuncName}`;\n    const [, ...inputArgs] = args.filter(requiresInputArg);\n    let pendingSeeds: RefSeeds | undefined;\n\n    const takeRefSeeds = (): RefSeeds | undefined => {\n        const seeds = pendingSeeds;\n        pendingSeeds = undefined;\n\n        return seeds;\n    };\n\n    const shaped = fromNativeCallable(\n        bindVfunc(bindOptionsFor(slot, instanceType, args, label)),\n        { args, returns: descriptor.returnDescriptor, canThrow },\n        takeRefSeeds,\n    );\n\n    return (instance, inputs) => {\n        if (inputs.length !== inputArgs.length) {\n            throw new Error(\n                `${caller}: ${label} expects ${String(inputArgs.length)} arguments, ` +\n                `received ${String(inputs.length)}`,\n            );\n        }\n\n        const nativeInputs = inputArgs.map((arg, index) => toNativeInput(arg, inputs[index]));\n        pendingSeeds = SEEDED_SLOTS[label] ?? seedsFor(descriptor.argDescriptors, instance);\n\n        return shaped(getHandle(instance), ...nativeInputs);\n    };\n}\n\nfunction cachedInvoker(cache: InvokerCache, owner: AnyClass, key: string, build: () => Invoker): Invoker {\n    let byKey = cache.get(owner);\n\n    if (byKey === undefined) {\n        byKey = new Map();\n        cache.set(owner, byKey);\n    }\n\n    let invoker = byKey.get(key);\n\n    if (invoker === undefined) {\n        invoker = build();\n        byKey.set(key, invoker);\n    }\n\n    return invoker;\n}\n\nfunction resolveParentSlot(klass: AnyClass, parentType: bigint, methodName: string): ResolvedSlot | undefined {\n    const classDescriptor = findClassVfuncDescriptor(klass, methodName);\n\n    if (classDescriptor) {\n        return { descriptor: classDescriptor };\n    }\n\n    for (const interfaceType of typeInterfaces(parentType)) {\n        const descriptor = findInterfaceVfuncDescriptor(interfaceType, methodName);\n\n        if (descriptor) {\n            return { descriptor, interfaceType };\n        }\n    }\n\n    return undefined;\n}\n\nfunction resolveParentType(klass: AnyClass, methodName: string): bigint {\n    const gtype = getClassType(klass);\n\n    if (gtype === TYPE_INVALID) {\n        throw new Error(\n            `callParent: cannot call '${methodName}' because ${klass.name} was never passed to registerClass`,\n        );\n    }\n\n    return typeParent(gtype);\n}\n\nfunction buildParentInvoker(klass: AnyClass, methodName: string): Invoker {\n    const parentType = resolveParentType(klass, methodName);\n    const slot = resolveParentSlot(klass, parentType, methodName);\n\n    if (!slot) {\n        throw new Error(`callParent: ${klass.name} inherits no '${methodName}' vtable slot`);\n    }\n\n    return buildInvoker(slot, parentType, \"callParent\");\n}\n\n/**\n * Calls the implementation of a virtual function that the parent type of `klass` provides, so an\n * override can chain up to the behavior it replaces. `klass` is the class whose override is\n * running, named lexically rather than taken from `instance`, so each level of a hierarchy reaches\n * exactly one level up. Arguments and the return value follow the same convention the override\n * itself uses: pure out parameters are left out and returned instead, and a slot with several\n * outputs returns them as a tuple. Throws if `klass` was never registered, inherits no such slot,\n * or the parent type leaves the slot empty.\n *\n * @param klass The registered class whose override is chaining up.\n * @param methodName Name of the overridden method, such as `vfuncMeasure`.\n * @param instance The instance the override was invoked on.\n * @param inputs The arguments the override received.\n */\nfunction callParent(klass: AnyClass, methodName: string, instance: object, ...inputs: unknown[]): unknown {\n    const invoker = cachedInvoker(parentInvokers, klass, methodName, () => buildParentInvoker(klass, methodName));\n\n    return invoker(instance, inputs);\n}\n\nfunction resolveOwnerSlot(owner: AnyClass, key: string): ResolvedSlot {\n    const classDescriptor = getVfuncRegistry(owner)?.[key];\n\n    if (classDescriptor !== undefined) {\n        return { descriptor: classDescriptor };\n    }\n\n    const interfaceType = getClassType(owner);\n    const descriptor = getInterfaceVfuncRegistry(interfaceType)?.[key];\n\n    if (descriptor === undefined) {\n        throw new Error(`callVfunc: ${owner.name} declares no '${key}' vtable slot`);\n    }\n\n    return { descriptor, interfaceType };\n}\n\nfunction requiresDefaultVtable(slot: ResolvedSlot, instanceType: bigint): boolean {\n    return slot.interfaceType !== undefined && !typeIsA(instanceType, slot.interfaceType);\n}\n\nfunction resolveInstanceType(key: string, instance: object, slot: ResolvedSlot): bigint | undefined {\n    const instanceType = resolveWrapperType(instance);\n\n    if (instanceType === TYPE_INVALID) {\n        const name = instanceClassName(instance);\n        throw new Error(`callVfunc: cannot call '${key}' because ${name} descends from no registered wrapper class`);\n    }\n\n    return requiresDefaultVtable(slot, instanceType) ? undefined : instanceType;\n}\n\n/**\n * Calls the implementation of a virtual function a wrapper class or interface declares, backing the\n * `vfunc`-prefixed members the generated bindings emit. The slot is read from the nearest generated\n * wrapper class in the instance's class chain rather than from the instance's own type, so an\n * override reaching it through `super` runs the implementation it replaced instead of re-entering\n * itself. When that wrapper class does not carry the interface the slot belongs to, because a class\n * registered below it adopted the interface, the slot comes from the interface's own default vtable\n * instead, which holds exactly what the adopting class replaced. Arguments and the return value\n * follow the same convention an override uses: pure out parameters are left out and returned\n * instead, and a slot with several outputs returns them as a tuple. Throws if the owner declares no\n * such slot, the instance descends from no wrapper class, or the resolved vtable leaves the slot\n * empty.\n *\n * @param owner The wrapper class or interface declaring the slot.\n * @param key Name of the generated member, such as `vfuncMeasure`.\n * @param instance The instance to invoke the slot on.\n * @param inputs The arguments the slot receives.\n */\nfunction callVfunc(owner: AnyClass, key: string, instance: object, inputs: unknown[]): unknown {\n    const slot = resolveOwnerSlot(owner, key);\n    const instanceType = resolveInstanceType(key, instance, slot);\n\n    const invoker = cachedInvoker(vfuncInvokers, owner, `${key}:${String(instanceType)}`, () =>\n        buildInvoker(slot, instanceType, \"callVfunc\"));\n\n    return invoker(instance, inputs);\n}\n\nexport { callParent, callVfunc };\n"]}

package/dist/vfunc-seeds.d.ts

@@ -0,0 +1,12 @@
+import type { Descriptor } from "@gtkx/native";
+type RefSeeds = Map<number, unknown>;
+type SeedFrame = {
+    argDescriptors: Descriptor[];
+    instance: unknown;
+    seeds: RefSeeds;
+};
+declare const pushSeedFrame: (frame: SeedFrame) => void;
+declare const popSeedFrame: () => void;
+declare const seedsFor: (argDescriptors: Descriptor[], instance: unknown) => RefSeeds | undefined;
+export { popSeedFrame, pushSeedFrame, type RefSeeds, seedsFor };
+//# sourceMappingURL=vfunc-seeds.d.ts.map

package/dist/vfunc-seeds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfunc-seeds.d.ts","sourceRoot":"","sources":["../src/vfunc-seeds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,KAAK,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErC,KAAK,SAAS,GAAG;IACb,cAAc,EAAE,UAAU,EAAE,CAAC;IAC7B,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;CACnB,CAAC;AAIF,QAAA,MAAM,aAAa,GAAI,OAAO,SAAS,KAAG,IAEzC,CAAC;AAEF,QAAA,MAAM,YAAY,QAAO,IAExB,CAAC;AAKF,QAAA,MAAM,QAAQ,GAAI,gBAAgB,UAAU,EAAE,EAAE,UAAU,OAAO,KAAG,QAAQ,GAAG,SAU9E,CAAC;AAEF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,QAAQ,EAAE,CAAC"}

package/dist/vfunc-seeds.js

@@ -0,0 +1,19 @@
+const frames = [];
+const pushSeedFrame = (frame) => {
+    frames.push(frame);
+};
+const popSeedFrame = () => {
+    frames.pop();
+};
+const isMatchingFrame = (frame, argDescriptors, instance) => frame.argDescriptors === argDescriptors && frame.instance === instance;
+const seedsFor = (argDescriptors, instance) => {
+    for (let index = frames.length - 1; index >= 0; index--) {
+        const frame = frames[index];
+        if (frame !== undefined && isMatchingFrame(frame, argDescriptors, instance)) {
+            return frame.seeds;
+        }
+    }
+    return undefined;
+};
+export { popSeedFrame, pushSeedFrame, seedsFor };
+//# sourceMappingURL=vfunc-seeds.js.map

package/dist/vfunc-seeds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfunc-seeds.js","sourceRoot":"","sources":["../src/vfunc-seeds.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,GAAgB,EAAE,CAAC;AAE/B,MAAM,aAAa,GAAG,CAAC,KAAgB,EAAQ,EAAE;IAC7C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC,CAAC;AAEF,MAAM,YAAY,GAAG,GAAS,EAAE;IAC5B,MAAM,CAAC,GAAG,EAAE,CAAC;AACjB,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,KAAgB,EAAE,cAA4B,EAAE,QAAiB,EAAW,EAAE,CACnG,KAAK,CAAC,cAAc,KAAK,cAAc,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC;AAE3E,MAAM,QAAQ,GAAG,CAAC,cAA4B,EAAE,QAAiB,EAAwB,EAAE;IACvF,KAAK,IAAI,KAAK,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACtD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAE5B,IAAI,KAAK,KAAK,SAAS,IAAI,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,CAAC;YAC1E,OAAO,KAAK,CAAC,KAAK,CAAC;QACvB,CAAC;IACL,CAAC;IAED,OAAO,SAAS,CAAC;AACrB,CAAC,CAAC;AAEF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAiB,QAAQ,EAAE,CAAC","sourcesContent":["import type { Descriptor } from \"@gtkx/native\";\n\ntype RefSeeds = Map<number, unknown>;\n\ntype SeedFrame = {\n    argDescriptors: Descriptor[];\n    instance: unknown;\n    seeds: RefSeeds;\n};\n\nconst frames: SeedFrame[] = [];\n\nconst pushSeedFrame = (frame: SeedFrame): void => {\n    frames.push(frame);\n};\n\nconst popSeedFrame = (): void => {\n    frames.pop();\n};\n\nconst isMatchingFrame = (frame: SeedFrame, argDescriptors: Descriptor[], instance: unknown): boolean =>\n    frame.argDescriptors === argDescriptors && frame.instance === instance;\n\nconst seedsFor = (argDescriptors: Descriptor[], instance: unknown): RefSeeds | undefined => {\n    for (let index = frames.length - 1; index >= 0; index--) {\n        const frame = frames[index];\n\n        if (frame !== undefined && isMatchingFrame(frame, argDescriptors, instance)) {\n            return frame.seeds;\n        }\n    }\n\n    return undefined;\n};\n\nexport { popSeedFrame, pushSeedFrame, type RefSeeds, seedsFor };\n"]}

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.3",
+  "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/utils": "1.0.0-rc.3",
-    "@gtkx/native": "1.0.0-rc.3"
+    "@gtkx/native": "1.0.0",
+    "@gtkx/utils": "1.0.0"
   },
   "devDependencies": {
-    "@gtkx/vitest": "1.0.0-rc.3"
+    "@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

@@ -1,15 +1,21 @@
 import type { Descriptor } from "@gtkx/native";
 
+/** How one argument of a native call or signal emission is marshalled and which way it flows. */
 type Arg = {
+    /** Descriptor the value is marshalled with, wrapped in a pointer to it for an output argument. */
     type: Descriptor;
+    /** Direction of an output argument, omitted for a plain input argument. */
     direction?: "out" | "inout";
-    callerAllocated?: boolean;
-    consumed?: boolean;
+    /** When true, the caller supplies the storage the callee writes into, rather than a pointer to fill. */
+    isCallerAllocated?: boolean;
+    /** When true, the argument is consumed internally and left out of the packed result. */
+    isConsumed?: boolean;
 };
 
 const isOutputArg = (arg: Arg): boolean => arg.direction !== undefined;
 const isInoutArg = (arg: Arg): boolean => arg.direction === "inout";
-const isCallerAllocatedArg = (arg: Arg): boolean => arg.callerAllocated === true;
-const isRefArg = (arg: Arg): boolean => arg.direction !== undefined && arg.callerAllocated !== true;
+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,