@gtkx/runtime 1.0.0-rc.3 → 1.0.0

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 => {
@@ -40,29 +45,29 @@ const fillCallerAllocatedBuffer = (descriptor: Descriptor, target: object, sourc
 };
 
 const isCallerAllocatedOut = (descriptor: Descriptor): boolean =>
-    (descriptor.kind === "boxed" || descriptor.kind === "struct") && descriptor.callerAllocated === true;
+    (descriptor.kind === "boxed" || descriptor.kind === "struct") && descriptor.isCallerAllocated === true;
 
 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 };