@gtkx/runtime 1.0.0-rc.3 → 1.0.0

package/src/value.ts

@@ -9,16 +9,18 @@ import {
     boxedT,
     float32T,
     float64T,
+    int8T,
     int32T,
     objectT,
     stringT,
+    uint8T,
     uint32T,
     uint64T,
     voidT,
 } from "./descriptors.js";
 import { LIB, PARAM_T, VALUE_SIZE, VALUE_T, VARIANT_T } from "./library.js";
 import { toNative } from "./native-value.js";
-import { getHandle, getWrapperClass, wrapHandle } from "./registry.js";
+import { getHandle, getWrapperClass, wrapHandle, wrapObject } from "./registry.js";
 import {
     getStrvType,
     isResolvableDescriptor,
@@ -28,6 +30,7 @@ import {
     resolveType,
     TYPE_BOOLEAN,
     TYPE_BOXED,
+    TYPE_CHAR,
     TYPE_DOUBLE,
     TYPE_ENUM,
     TYPE_FLAGS,
@@ -35,13 +38,17 @@ import {
     TYPE_GTYPE,
     TYPE_INT,
     TYPE_INT64,
+    TYPE_INTERFACE,
     TYPE_INVALID,
+    TYPE_LONG,
     TYPE_OBJECT,
     TYPE_PARAM,
     TYPE_POINTER,
     TYPE_STRING,
+    TYPE_UCHAR,
     TYPE_UINT,
     TYPE_UINT64,
+    TYPE_ULONG,
     TYPE_VARIANT,
     typeFundamental,
     typeName,
@@ -53,6 +60,7 @@ type ValueType = {
 };
 
 type ValueGetter = (value: ExternalObject<Handle>) => unknown;
+type ValueWriter = ValueType["set"];
 
 const setBoxedCache = createBindCache();
 const setStaticBoxedCache = createBindCache();
@@ -61,8 +69,12 @@ const gValueInit = bind(LIB, "g_value_init", [VALUE_T, biguint64T], voidT);
 const gValueCopy = bind(LIB, "g_value_copy", [VALUE_T, VALUE_T], voidT);
 const booleanValueType = bindValueType("boolean", booleanT);
 const typeValueType = bindValueType("gtype", biguint64T);
+const scharValueType = bindValueType("schar", int8T);
+const ucharValueType = bindValueType("uchar", uint8T);
 const intValueType = bindValueType("int", int32T);
 const uintValueType = bindValueType("uint", uint32T);
+const longValueType = bindValueType("long", bigint64T);
+const ulongValueType = bindValueType("ulong", biguint64T);
 const int64ValueType = bindValueType("int64", bigint64T);
 const uint64ValueType = bindValueType("uint64", biguint64T);
 const floatValueType = bindValueType("float", float32T);
@@ -101,8 +113,12 @@ const PLAIN_VALUE_TYPES: Partial<Record<Descriptor["kind"], ValueType>> = {
 const PLAIN_VALUE_GETTERS: Map<bigint, ValueGetter> = new Map([
     [TYPE_BOOLEAN, booleanValueType.get],
     [TYPE_GTYPE, typeValueType.get],
+    [TYPE_CHAR, scharValueType.get],
+    [TYPE_UCHAR, ucharValueType.get],
     [TYPE_INT, intValueType.get],
     [TYPE_UINT, uintValueType.get],
+    [TYPE_LONG, longValueType.get],
+    [TYPE_ULONG, ulongValueType.get],
     [TYPE_INT64, int64ValueType.get],
     [TYPE_UINT64, uint64ValueType.get],
     [TYPE_FLOAT, floatValueType.get],
@@ -114,8 +130,12 @@ const PLAIN_VALUE_GETTERS: Map<bigint, ValueGetter> = new Map([
 const PLAIN_VALUE_SETTERS: Map<bigint, ValueType["set"]> = new Map([
     [TYPE_BOOLEAN, booleanValueType.set],
     [TYPE_GTYPE, typeValueType.set],
+    [TYPE_CHAR, scharValueType.set],
+    [TYPE_UCHAR, ucharValueType.set],
     [TYPE_INT, intValueType.set],
     [TYPE_UINT, uintValueType.set],
+    [TYPE_LONG, longValueType.set],
+    [TYPE_ULONG, ulongValueType.set],
     [TYPE_INT64, int64ValueType.set],
     [TYPE_UINT64, uint64ValueType.set],
     [TYPE_FLOAT, floatValueType.set],
@@ -127,9 +147,11 @@ const PLAIN_VALUE_SETTERS: Map<bigint, ValueType["set"]> = new Map([
 const WRAPPED_VALUE_SETTERS: Map<bigint, ValueType["set"]> = new Map([
     [TYPE_STRING, setStringValue],
     [TYPE_OBJECT, handleSetter(objectValueType)],
+    [TYPE_INTERFACE, handleSetter(objectValueType)],
     [TYPE_PARAM, handleSetter(paramValueType)],
     [TYPE_VARIANT, handleSetter(variantValueType)],
     [TYPE_BOXED, setBoxedFromValue],
+    [TYPE_POINTER, setPointerValue],
 ]);
 
 const getBoxedTypeName = (type: bigint): string => typeName(type) ?? "GBoxed";
@@ -189,7 +211,7 @@ function copyValue(dest: ExternalObject<Handle>, src: ExternalObject<Handle>): v
     gValueCopy(src, dest);
 }
 
-const newTypedValue = (type: bigint): ExternalObject<Handle> => {
+const newValueForType = (type: bigint): ExternalObject<Handle> => {
     const value = newValue();
     gValueInit(value, type);
 
@@ -202,15 +224,15 @@ const newBoxedValue = (
     resolveSetBind: (name: string) => ValueType["set"],
 ): ExternalObject<Handle> => {
     const type = resolveDescriptorType(descriptor);
-    const value = newTypedValue(type);
+    const value = newValueForType(type);
     resolveSetBind(getBoxedTypeName(type))(value, getHandle(boxed));
 
     return value;
 };
 
 /**
- * Reads the boxed pointer out of a GValue and returns it wrapped in its registered
- * class, or null when the value does not hold a boxed type.
+ * Duplicates the boxed value held by a GValue and returns the copy wrapped in the
+ * class registered for its GType, or null when the GValue holds no boxed type.
  */
 function getBoxedValue(value: ExternalObject<Handle>): object | null {
     const type = getValueType(value);
@@ -276,8 +298,9 @@ const wrappedValueGetter = (fundamental: bigint): ValueGetter | undefined => {
         case TYPE_STRING: {
             return (value) => stringValueType.get(value) ?? null;
         }
+        case TYPE_INTERFACE:
         case TYPE_OBJECT: {
-            return (value) => wrapHandle(objectValueType.get(value) as ExternalObject<Handle> | null);
+            return (value) => wrapObject(objectValueType.get(value));
         }
         case TYPE_PARAM: {
             return (value) =>
@@ -309,6 +332,14 @@ function setStringValue(value: ExternalObject<Handle>, nativeValue: unknown): vo
     stringValueType.set(value, nativeValue ?? null);
 }
 
+function setPointerValue(value: ExternalObject<Handle>, nativeValue: unknown): void {
+    if (nativeValue != null) {
+        throw new Error("G_TYPE_POINTER non-null values cannot be marshalled from JS");
+    }
+
+    pointerValueType.set(value, 0);
+}
+
 function handleSetter(target: ValueType): ValueType["set"] {
     return (value, nativeValue) => {
         target.set(value, nativeValue == null ? null : getHandle(nativeValue));
@@ -325,22 +356,26 @@ const resolveValueGetter = (fundamental: bigint): ValueGetter | undefined =>
 const resolveValueSetter = (fundamental: bigint): ValueType["set"] | undefined =>
     PLAIN_VALUE_SETTERS.get(fundamental) ?? WRAPPED_VALUE_SETTERS.get(fundamental);
 
-/**
- * Stores a JavaScript value into an already-initialized GValue, converting it to
- * whatever type the GValue holds.
- *
- * @param value The initialized GValue to write into.
- * @param jsValue The JavaScript value to store.
- */
-function intoValue(value: ExternalObject<Handle>, jsValue: unknown): void {
-    const type = getValueType(value);
+function setStrvValue(value: ExternalObject<Handle>, jsValue: unknown): void {
+    strvValueType.set(value, jsValue ?? null);
+}
+
+function valueWriterFor(type: bigint): ValueWriter {
+    if (type === getStrvType()) {
+        return setStrvValue;
+    }
+
     const set = resolveValueSetter(typeFundamental(type));
 
     if (set === undefined) {
         throw new Error(`Unsupported type for intoValue: ${typeName(type) ?? String(type)}`);
     }
 
-    set(value, jsValue);
+    return set;
+}
+
+function intoValue(value: ExternalObject<Handle>, jsValue: unknown): void {
+    valueWriterFor(getValueType(value))(value, jsValue);
 }
 
 const resolveNativeValue = (descriptor: Descriptor, value: unknown): unknown => {
@@ -364,7 +399,7 @@ const resolveValueGType = (descriptor: Descriptor, nativeValue: unknown): bigint
 function toValue(descriptor: Descriptor, value: unknown): ExternalObject<Handle> {
     const nativeValue = resolveNativeValue(descriptor, value);
     const type = resolveValueGType(descriptor, nativeValue);
-    const gValue = newTypedValue(type);
+    const gValue = newValueForType(type);
     resolveValueType(descriptor).set(gValue, nativeValue);
 
     return gValue;
@@ -387,7 +422,7 @@ function fromValue(value: ExternalObject<Handle>): unknown {
 }
 
 function newValueForDescriptor(descriptor: Descriptor): ExternalObject<Handle> {
-    return newTypedValue(resolveDescriptorType(descriptor));
+    return newValueForType(resolveDescriptorType(descriptor));
 }
 
 function outValueForDescriptor(
@@ -401,7 +436,7 @@ function outValueForDescriptor(
         write(storage, descriptor, 0, initial);
     }
 
-    const value = newTypedValue(TYPE_POINTER);
+    const value = newValueForType(TYPE_POINTER);
     pointerValueType.set(value, storage);
 
     return { value, read: () => read(storage, descriptor, 0) };
@@ -424,7 +459,10 @@ export {
     toValue,
     fromValue,
     newValueForDescriptor,
+    newValueForType,
     outValueForDescriptor,
     outValueForBoxedDescriptor,
     inoutValueForBoxedDescriptor,
+    type ValueWriter,
+    valueWriterFor,
 };

package/src/vfunc-call.ts

@@ -0,0 +1,243 @@
+import type { BindVfuncOptions } from "@gtkx/native";
+import type { AnyClass } from "@gtkx/utils";
+import { bindVfunc } from "@gtkx/native";
+import { type Arg, isCallerAllocatedArg, requiresInputArg } from "./arg.js";
+import { buildNativeArgTypes, fromNativeCallable } from "./fn.js";
+import { toNative } from "./native-value.js";
+import {
+    getClassType,
+    getHandle,
+    getInterfaceVfuncRegistry,
+    getVfuncRegistry,
+    instanceClassName,
+    resolveWrapperType,
+    type VfuncDescriptor,
+} from "./registry.js";
+import { TYPE_INVALID, typeInterfaces, typeIsA, typeParent } from "./type.js";
+import { type RefSeeds, seedsFor } from "./vfunc-seeds.js";
+import { findClassVfuncDescriptor, findInterfaceVfuncDescriptor, vfuncArgs } from "./vfunc.js";
+
+type Invoker = (instance: object, inputs: unknown[]) => unknown;
+type InvokerCache = WeakMap<AnyClass, Map<string, Invoker>>;
+type ResolvedSlot = { descriptor: VfuncDescriptor; interfaceType?: bigint };
+
+const NO_BASELINE = -1;
+
+const SEEDED_SLOTS: Record<string, RefSeeds> = {
+    "LayoutManagerClass.measure": new Map([[6, NO_BASELINE], [7, NO_BASELINE]]),
+    "WidgetClass.measure": new Map([[5, NO_BASELINE], [6, NO_BASELINE]]),
+};
+
+const parentInvokers: InvokerCache = new WeakMap();
+const vfuncInvokers: InvokerCache = new WeakMap();
+
+function toNativeInput(arg: Arg, input: unknown): unknown {
+    return isCallerAllocatedArg(arg) ? input : toNative(arg.type, input);
+}
+
+function bindOptionsFor(
+    slot: ResolvedSlot,
+    instanceType: bigint | undefined,
+    args: Arg[],
+    label: string,
+): BindVfuncOptions {
+    const { descriptor, interfaceType } = slot;
+
+    const options: BindVfuncOptions = {
+        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: ResolvedSlot, instanceType: bigint | undefined, caller: string): Invoker {
+    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: RefSeeds | undefined;
+
+    const takeRefSeeds = (): RefSeeds | undefined => {
+        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: InvokerCache, owner: AnyClass, key: string, build: () => Invoker): Invoker {
+    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: AnyClass, parentType: bigint, methodName: string): ResolvedSlot | undefined {
+    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: AnyClass, methodName: string): bigint {
+    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: AnyClass, methodName: string): Invoker {
+    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: AnyClass, methodName: string, instance: object, ...inputs: unknown[]): unknown {
+    const invoker = cachedInvoker(parentInvokers, klass, methodName, () => buildParentInvoker(klass, methodName));
+
+    return invoker(instance, inputs);
+}
+
+function resolveOwnerSlot(owner: AnyClass, key: string): ResolvedSlot {
+    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: ResolvedSlot, instanceType: bigint): boolean {
+    return slot.interfaceType !== undefined && !typeIsA(instanceType, slot.interfaceType);
+}
+
+function resolveInstanceType(key: string, instance: object, slot: ResolvedSlot): bigint | undefined {
+    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: AnyClass, key: string, instance: object, inputs: unknown[]): unknown {
+    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 };

package/src/vfunc-seeds.ts

@@ -0,0 +1,36 @@
+import type { Descriptor } from "@gtkx/native";
+
+type RefSeeds = Map<number, unknown>;
+
+type SeedFrame = {
+    argDescriptors: Descriptor[];
+    instance: unknown;
+    seeds: RefSeeds;
+};
+
+const frames: SeedFrame[] = [];
+
+const pushSeedFrame = (frame: SeedFrame): void => {
+    frames.push(frame);
+};
+
+const popSeedFrame = (): void => {
+    frames.pop();
+};
+
+const isMatchingFrame = (frame: SeedFrame, argDescriptors: Descriptor[], instance: unknown): boolean =>
+    frame.argDescriptors === argDescriptors && frame.instance === instance;
+
+const seedsFor = (argDescriptors: Descriptor[], instance: unknown): RefSeeds | undefined => {
+    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, type RefSeeds, seedsFor };

package/src/vfunc.ts

@@ -0,0 +1,31 @@
+import type { Descriptor } from "@gtkx/native";
+import { type AnyClass, getParentClass, walkClassChain } from "@gtkx/utils";
+import type { Arg } from "./arg.js";
+import { isCallerAllocatedOut } from "./callback.js";
+import { getInterfaceVfuncRegistry, getVfuncRegistry, type VfuncDescriptor } from "./registry.js";
+
+function findClassVfuncDescriptor(klass: AnyClass, methodName: string): VfuncDescriptor | null {
+    return walkClassChain(getParentClass(klass), (cls) => getVfuncRegistry(cls)?.[methodName]) ?? null;
+}
+
+function findInterfaceVfuncDescriptor(interfaceGtype: bigint, methodName: string): VfuncDescriptor | undefined {
+    return getInterfaceVfuncRegistry(interfaceGtype)?.[methodName];
+}
+
+function vfuncArg(descriptor: Descriptor): Arg {
+    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: VfuncDescriptor): Arg[] {
+    return descriptor.argDescriptors.map((argDescriptor) => vfuncArg(argDescriptor));
+}
+
+export { findClassVfuncDescriptor, findInterfaceVfuncDescriptor, vfuncArgs };