@gtkx/runtime 0.0.1 → 1.0.0-rc.2

package/src/signal.ts

@@ -0,0 +1,192 @@
+import type { Descriptor, ExternalObject, Handle } from "@gtkx/native";
+import type { TypedClass } from "./type.js";
+import { type Arg, isCallerAllocatedArg, isInoutArg, isOutputArg } from "./arg.js";
+import { bind, createBindCache } from "./bind.js";
+import { wrapCallback } from "./callback.js";
+import {
+    arrayT,
+    biguint64T,
+    booleanT,
+    type CallbackDescriptor,
+    objectT,
+    stringT,
+    uint32T,
+    uint64T,
+    voidT,
+} from "./descriptors.js";
+import { LIB, VALUE_SIZE, VALUE_T } from "./library.js";
+import { getHandle } from "./registry.js";
+import { packTupleResult } from "./tuple.js";
+import {
+    fromValue,
+    getBoxedValue,
+    inoutValueForBoxedDescriptor,
+    newValueForDescriptor,
+    outValueForBoxedDescriptor,
+    outValueForDescriptor,
+    toValue,
+} from "./value.js";
+
+/** Function invoked when a connected GObject signal is emitted. */
+type SignalHandler = (...args: unknown[]) => unknown;
+
+type SignalConnectSpec = {
+    callback: CallbackDescriptor;
+    handler: SignalHandler;
+    after: boolean;
+};
+
+type EmitArg = Arg & { value?: unknown };
+
+const connectCache = createBindCache();
+const gQuarkFromString = bind(LIB, "g_quark_from_string", [stringT("borrowed")], uint32T);
+const gSignalLookup = bind(LIB, "g_signal_lookup", [stringT("borrowed"), biguint64T], uint32T);
+
+const gSignalEmitv = bind(
+    LIB,
+    "g_signal_emitv",
+    [arrayT(VALUE_T, "array", "borrowed", { elementSize: VALUE_SIZE }), uint32T, uint32T, VALUE_T],
+    voidT,
+);
+
+const gSignalHandlersBlockMatched = bind(
+    LIB,
+    "g_signal_handlers_block_matched",
+    [objectT("borrowed"), uint32T, uint32T, uint32T, objectT("borrowed"), objectT("borrowed"), objectT("borrowed")],
+    uint32T,
+);
+
+const gSignalHandlerIsConnected = bind(
+    LIB,
+    "g_signal_handler_is_connected",
+    [objectT("borrowed"), uint64T],
+    booleanT,
+);
+
+/** Returns the signal name without its detail suffix (the part after `::`). */
+const getSignalBaseName = (signal: string): string => {
+    const detailIndex = signal.indexOf("::");
+
+    return detailIndex === -1 ? signal : signal.slice(0, detailIndex);
+};
+
+function getSignalDetailQuark(signal: string): number {
+    const detailIndex = signal.indexOf("::");
+
+    if (detailIndex === -1) {
+        return 0;
+    }
+
+    return gQuarkFromString(signal.slice(detailIndex + 2)) as number;
+}
+
+const isSignalHandlerConnected = (instance: object, handlerId: number): boolean =>
+    gSignalHandlerIsConnected(getHandle(instance), handlerId) as boolean;
+
+const getSignalId = (instance: object, signal: string): number => {
+    const type: bigint = (instance as TypedClass).__type__;
+
+    return gSignalLookup(getSignalBaseName(signal), type) as number;
+};
+
+function connectBind(type: bigint, signal: string, callback: CallbackDescriptor): (...values: unknown[]) => unknown {
+    const key = `${String(type)}\0${getSignalBaseName(signal)}`;
+
+    return connectCache(
+        key,
+        LIB,
+        "g_signal_connect_data",
+        [objectT("borrowed"), stringT("borrowed"), callback, uint32T],
+        uint64T,
+    );
+}
+
+/**
+ * Connects a handler to a GObject signal on an instance and returns the handler id.
+ * @param instance Emitter to connect to.
+ * @param signal Signal name, optionally including a `::detail` suffix.
+ * @param spec Callback descriptor, handler function, and whether to run after the default handler.
+ */
+function connectSignal(instance: object, signal: string, spec: SignalConnectSpec): number {
+    const { callback, handler, after } = spec;
+    const wrapped = wrapCallback(handler, callback, "emitter");
+    const type: bigint = (instance as TypedClass).__type__;
+    const connect = connectBind(type, signal, callback);
+
+    return connect(getHandle(instance), signal, wrapped, after ? 1 : 0) as number;
+}
+
+function blockMatchedSignalHandlers(instance: object, signal: string): void {
+    const signalId = getSignalId(instance, signal);
+    gSignalHandlersBlockMatched(getHandle(instance), 1, signalId, 0, undefined, undefined, undefined);
+}
+
+const createEmitValue = (arg: EmitArg): { value: ExternalObject<Handle>; read?: () => unknown } => {
+    if (!isOutputArg(arg)) {
+        return { value: toValue(arg.type, arg.value) };
+    }
+
+    if (isCallerAllocatedArg(arg)) {
+        if (isInoutArg(arg)) {
+            return { value: inoutValueForBoxedDescriptor(arg.type, arg.value as object) };
+        }
+
+        const value = outValueForBoxedDescriptor(arg.type, arg.value as object);
+
+        return { value, read: () => getBoxedValue(value) };
+    }
+
+    return isInoutArg(arg) ? outValueForDescriptor(arg.type, arg.value) : outValueForDescriptor(arg.type);
+};
+
+/**
+ * Emits a signal on an instance with the given arguments and returns its result
+ * combined with any output-argument values.
+ * @param instance Emitter to emit the signal on.
+ * @param signal Signal name, optionally including a `::detail` suffix.
+ * @param args Arguments to pass, including output and inout arguments.
+ * @param returnDescriptor Descriptor for the signal's return value, omitted when it returns void.
+ */
+function emitSignal(instance: object, signal: string, args: EmitArg[], returnDescriptor?: Descriptor): unknown {
+    const signalId = getSignalId(instance, signal);
+    const detail = getSignalDetailQuark(signal);
+    const values: ExternalObject<Handle>[] = [toValue(objectT("full"), instance)];
+    const reads: (() => unknown)[] = [];
+
+    for (const arg of args) {
+        const { value, read } = createEmitValue(arg);
+        values.push(value);
+
+        if (read) {
+            reads.push(read);
+        }
+    }
+
+    if (returnDescriptor !== undefined) {
+        const returnValue = newValueForDescriptor(returnDescriptor);
+        gSignalEmitv(values, signalId, detail, returnValue);
+
+        return packTupleResult(
+            reads.map((read) => read()),
+            fromValue(returnValue),
+            true,
+        );
+    }
+
+    gSignalEmitv(values, signalId, detail, undefined);
+
+    return packTupleResult(
+        reads.map((read) => read()),
+        undefined,
+        false,
+    );
+}
+
+export {
+    getSignalBaseName,
+    connectSignal,
+    blockMatchedSignalHandlers,
+    emitSignal,
+    isSignalHandlerConnected,
+    type SignalHandler,
+};

package/src/t.ts

@@ -0,0 +1,90 @@
+import { bind } from "./bind.js";
+import * as helpers from "./descriptors.js";
+import { fn } from "./fn.js";
+
+type T = {
+    bind: typeof bind;
+    int8: typeof helpers.int8T;
+    uint8: typeof helpers.uint8T;
+    int16: typeof helpers.int16T;
+    uint16: typeof helpers.uint16T;
+    int32: typeof helpers.int32T;
+    uint32: typeof helpers.uint32T;
+    int64: typeof helpers.int64T;
+    uint64: typeof helpers.uint64T;
+    bigint64: typeof helpers.bigint64T;
+    biguint64: typeof helpers.biguint64T;
+    gtype: typeof helpers.gtypeT;
+    float32: typeof helpers.float32T;
+    float64: typeof helpers.float64T;
+    boolean: typeof helpers.booleanT;
+    void: typeof helpers.voidT;
+    unichar: typeof helpers.unicharT;
+    buffer: typeof helpers.bufferT;
+    string: typeof helpers.stringT;
+    object: typeof helpers.objectT;
+    boxed: typeof helpers.boxedT;
+    struct: typeof helpers.structT;
+    fundamental: typeof helpers.fundamentalT;
+    ref: typeof helpers.refT;
+    hashTable: typeof helpers.hashTableT;
+    enum: typeof helpers.enumT;
+    flags: typeof helpers.flagsT;
+    array: typeof helpers.arrayT;
+    list: typeof helpers.listT;
+    slist: typeof helpers.slistT;
+    ptrArray: typeof helpers.ptrArrayT;
+    gArray: typeof helpers.gArrayT;
+    byteArray: typeof helpers.byteArrayT;
+    sizedArray: typeof helpers.sizedArrayT;
+    fixedArray: typeof helpers.fixedArrayT;
+    callback: typeof helpers.callbackT;
+    fn: typeof fn;
+};
+
+/**
+ * Type descriptor builder: a collection of factory helpers that describe C types for
+ * FFI marshalling, plus `bind` to bind a native function and `fn` to describe a
+ * function signature.
+ */
+const t: T = {
+    bind,
+    int8: helpers.int8T,
+    uint8: helpers.uint8T,
+    int16: helpers.int16T,
+    uint16: helpers.uint16T,
+    int32: helpers.int32T,
+    uint32: helpers.uint32T,
+    int64: helpers.int64T,
+    uint64: helpers.uint64T,
+    bigint64: helpers.bigint64T,
+    biguint64: helpers.biguint64T,
+    gtype: helpers.gtypeT,
+    float32: helpers.float32T,
+    float64: helpers.float64T,
+    boolean: helpers.booleanT,
+    void: helpers.voidT,
+    unichar: helpers.unicharT,
+    buffer: helpers.bufferT,
+    string: helpers.stringT,
+    object: helpers.objectT,
+    boxed: helpers.boxedT,
+    struct: helpers.structT,
+    fundamental: helpers.fundamentalT,
+    ref: helpers.refT,
+    hashTable: helpers.hashTableT,
+    enum: helpers.enumT,
+    flags: helpers.flagsT,
+    array: helpers.arrayT,
+    list: helpers.listT,
+    slist: helpers.slistT,
+    ptrArray: helpers.ptrArrayT,
+    gArray: helpers.gArrayT,
+    byteArray: helpers.byteArrayT,
+    sizedArray: helpers.sizedArrayT,
+    fixedArray: helpers.fixedArrayT,
+    callback: helpers.callbackT,
+    fn,
+};
+
+export { t };

package/src/tuple.ts

@@ -0,0 +1,37 @@
+const packTupleResult = (outs: unknown[], primary: unknown, hasPrimary: boolean): unknown => {
+    if (hasPrimary) {
+        return outs.length === 0 ? primary : [primary, ...outs];
+    }
+
+    if (outs.length === 0) {
+        return undefined;
+    }
+
+    if (outs.length === 1) {
+        return outs[0];
+    }
+
+    return outs;
+};
+
+const splitTupleResult = (
+    result: unknown,
+    hasPrimary: boolean,
+    outCount: number,
+): { primary: unknown; outValues: unknown[] } => {
+    if (hasPrimary) {
+        if (Array.isArray(result)) {
+            return { primary: result[0], outValues: result.slice(1) };
+        }
+
+        return { primary: result, outValues: [] };
+    }
+
+    if (outCount === 1) {
+        return { primary: undefined, outValues: [result] };
+    }
+
+    return { primary: undefined, outValues: Array.isArray(result) ? result : [] };
+};
+
+export { packTupleResult, splitTupleResult };

package/src/type.ts

@@ -0,0 +1,290 @@
+import { type Descriptor, resolveType as nativeResolveType } from "@gtkx/native";
+import { bind } from "./bind.js";
+import {
+    type ArrayDescriptor,
+    biguint64T,
+    booleanT,
+    type BoxedDescriptor,
+    type FundamentalDescriptor,
+    refT,
+    sizedArrayT,
+    stringT,
+    uint32T,
+} from "./descriptors.js";
+import { LIB } from "./library.js";
+
+/** Object tagged with its GLib type through a `__type__` GType field. */
+type TypedClass = {
+    __type__: bigint;
+};
+
+type ResolvableKind = "enum" | "flags" | "boxed" | "fundamental" | "array";
+/** Descriptor kinds whose GType is resolved from library metadata rather than a fixed fundamental type. */
+type ResolvableDescriptor = Extract<Descriptor, { kind: ResolvableKind }>;
+
+const resolvedTypeCache: Map<string, bigint> = new Map();
+const gTypeFromName = bind(LIB, "g_type_from_name", [stringT("borrowed")], biguint64T);
+const gTypeIsA = bind(LIB, "g_type_is_a", [biguint64T, biguint64T], booleanT);
+const gTypeParent = bind(LIB, "g_type_parent", [biguint64T], biguint64T);
+const gTypeFundamental = bind(LIB, "g_type_fundamental", [biguint64T], biguint64T);
+const gTypeName = bind(LIB, "g_type_name", [biguint64T], stringT("borrowed"));
+const gTypeInterfaces = bind(LIB, "g_type_interfaces", [biguint64T, refT(uint32T)], sizedArrayT(biguint64T, 1, "full"));
+/** GType tag for an invalid or uninitialized type. */
+const TYPE_INVALID = 0n;
+/** GType tag for the absence of a value (`void`). */
+const TYPE_NONE: bigint = typeFromName("void");
+/** GType tag for the base GInterface type. */
+const TYPE_INTERFACE: bigint = typeFromName("GInterface");
+/** GType tag for `gchar` (signed 8-bit integer). */
+const TYPE_CHAR: bigint = typeFromName("gchar");
+/** GType tag for `guchar` (unsigned 8-bit integer). */
+const TYPE_UCHAR: bigint = typeFromName("guchar");
+/** GType tag for `gboolean`. */
+const TYPE_BOOLEAN: bigint = typeFromName("gboolean");
+/** GType tag for `gint`. */
+const TYPE_INT: bigint = typeFromName("gint");
+/** GType tag for `guint`. */
+const TYPE_UINT: bigint = typeFromName("guint");
+/** GType tag for `glong`. */
+const TYPE_LONG: bigint = typeFromName("glong");
+/** GType tag for `gulong`. */
+const TYPE_ULONG: bigint = typeFromName("gulong");
+/** GType tag for `gint64`. */
+const TYPE_INT64: bigint = typeFromName("gint64");
+/** GType tag for `guint64`. */
+const TYPE_UINT64: bigint = typeFromName("guint64");
+/** GType tag for the base GEnum type. */
+const TYPE_ENUM: bigint = typeFromName("GEnum");
+/** GType tag for the base GFlags type. */
+const TYPE_FLAGS: bigint = typeFromName("GFlags");
+/** GType tag for `gfloat`. */
+const TYPE_FLOAT: bigint = typeFromName("gfloat");
+/** GType tag for `gdouble`. */
+const TYPE_DOUBLE: bigint = typeFromName("gdouble");
+/** GType tag for `gchararray` (a nul-terminated C string). */
+const TYPE_STRING: bigint = typeFromName("gchararray");
+/** GType tag for `gpointer` (an opaque pointer). */
+const TYPE_POINTER: bigint = typeFromName("gpointer");
+/** GType tag for the base GBoxed type. */
+const TYPE_BOXED: bigint = typeFromName("GBoxed");
+/** GType tag for the base GParam type. */
+const TYPE_PARAM: bigint = typeFromName("GParam");
+/** GType tag for the base GObject type. */
+const TYPE_OBJECT: bigint = typeFromName("GObject");
+/** GType tag for a GType value itself. */
+const TYPE_GTYPE: bigint = typeFromName("GType");
+/** GType tag for GVariant. */
+const TYPE_VARIANT: bigint = typeFromName("GVariant");
+/** GType tag for a Unicode character stored as `guint`. */
+const TYPE_UNICHAR: bigint = typeFromName("guint");
+const getErrorType: () => bigint = lazyType("GError");
+const getStrvType: () => bigint = lazyType("GStrv");
+
+const PLAIN_DESCRIPTOR_TYPES: Partial<Record<Descriptor["kind"], bigint>> = {
+    boolean: TYPE_BOOLEAN,
+    string: TYPE_STRING,
+    int8: TYPE_INT,
+    int16: TYPE_INT,
+    int32: TYPE_INT,
+    uint8: TYPE_UINT,
+    uint16: TYPE_UINT,
+    uint32: TYPE_UINT,
+    int64: TYPE_INT64,
+    bigint64: TYPE_INT64,
+    uint64: TYPE_UINT64,
+    biguint64: TYPE_UINT64,
+    float32: TYPE_FLOAT,
+    float64: TYPE_DOUBLE,
+    object: TYPE_OBJECT,
+};
+
+const RESOLVABLE_DESCRIPTOR_KINDS: Set<Descriptor["kind"]> = new Set<ResolvableKind>([
+    "enum",
+    "flags",
+    "boxed",
+    "fundamental",
+    "array",
+]);
+
+function lazyType(name: string): () => bigint {
+    let cached: bigint | undefined;
+
+    return () => {
+        cached ??= typeFromName(name);
+
+        return cached;
+    };
+}
+
+const isTypedClass = (value: unknown): value is TypedClass =>
+    typeof value === "object" && value !== null && "__type__" in value && typeof value.__type__ === "bigint";
+
+/** Returns whether `type` is `ancestorType` or descends from it. */
+function typeIsA(type: bigint, ancestorType: bigint): boolean {
+    return gTypeIsA(type, ancestorType) as boolean;
+}
+
+/** Returns the immediate parent GType of the given type. */
+function typeParent(type: bigint): bigint {
+    return gTypeParent(type) as bigint;
+}
+
+/** Returns the GTypes of the interfaces implemented by the given type. */
+function typeInterfaces(type: bigint): bigint[] {
+    const nInterfacesRef = { value: 0 };
+
+    return gTypeInterfaces(type, nInterfacesRef) as bigint[];
+}
+
+/** Returns the GType registered under the given name, or `TYPE_INVALID` if none exists. */
+function typeFromName(name: string): bigint {
+    return gTypeFromName(name) as bigint;
+}
+
+function typeFundamental(type: bigint): bigint {
+    return gTypeFundamental(type) as bigint;
+}
+
+/** Returns the registered name of a GType, or null if it has none. */
+function typeName(type: bigint): string | null {
+    return (gTypeName(type) ?? null) as string | null;
+}
+
+/** Returns whether `value` is a typed wrapper whose GType is or descends from `gtype`. */
+function valueIsA(value: unknown, gtype: bigint): boolean {
+    return isTypedClass(value) && typeIsA(value.__type__, gtype);
+}
+
+/**
+ * Resolves the GType produced by a `get_type` function in a shared library, caching
+ * the result per library and function name.
+ * @param sharedLibrary Path or name of the shared library exporting the function.
+ * @param typeFnName Name of the `*_get_type` function to call.
+ */
+const resolveType = (sharedLibrary: string, typeFnName: string): bigint => {
+    const key = `${sharedLibrary}:${typeFnName}`;
+    const cached = resolvedTypeCache.get(key);
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const gtype = nativeResolveType(sharedLibrary, typeFnName);
+    resolvedTypeCache.set(key, gtype);
+
+    return gtype;
+};
+
+const resolveBoxedType = (descriptor: BoxedDescriptor): bigint => {
+    if (descriptor.getTypeFnName && descriptor.sharedLibrary) {
+        return resolveType(descriptor.sharedLibrary, descriptor.getTypeFnName);
+    }
+
+    const gtype = typeFromName(descriptor.typeName);
+
+    if (gtype === TYPE_INVALID) {
+        throw new Error(`Cannot resolve gtype for boxed type '${descriptor.typeName}'`);
+    }
+
+    return gtype;
+};
+
+const resolveFundamentalType = (descriptor: FundamentalDescriptor): bigint => {
+    if (descriptor.typeName) {
+        const gtype = typeFromName(descriptor.typeName);
+
+        if (gtype !== TYPE_INVALID) {
+            return gtype;
+        }
+    }
+
+    throw new Error("Cannot resolve gtype for fundamental type without a typeName");
+};
+
+function resolveArrayType(descriptor: ArrayDescriptor): bigint {
+    if (descriptor.itemDescriptor.kind === "string" && descriptor.arrayKind === "array") {
+        return getStrvType();
+    }
+
+    throw new Error(`Unsupported array type ${descriptor.arrayKind} of ${descriptor.itemDescriptor.kind}`);
+}
+
+function isResolvableDescriptor(descriptor: Descriptor): descriptor is ResolvableDescriptor {
+    return RESOLVABLE_DESCRIPTOR_KINDS.has(descriptor.kind);
+}
+
+function resolveDescriptorType(descriptor: Descriptor): bigint {
+    if (descriptor.kind === "biguint64" && "type" in descriptor) {
+        return TYPE_GTYPE;
+    }
+
+    const plain = PLAIN_DESCRIPTOR_TYPES[descriptor.kind];
+
+    if (plain !== undefined) {
+        return plain;
+    }
+
+    if (!isResolvableDescriptor(descriptor)) {
+        throw new Error(`Unsupported type descriptor '${descriptor.kind}'`);
+    }
+
+    switch (descriptor.kind) {
+        case "enum":
+        case "flags": {
+            return resolveType(descriptor.sharedLibrary, descriptor.getTypeFnName);
+        }
+        case "boxed": {
+            return resolveBoxedType(descriptor);
+        }
+        case "fundamental": {
+            return resolveFundamentalType(descriptor);
+        }
+        case "array": {
+            return resolveArrayType(descriptor);
+        }
+    }
+}
+
+export {
+    TYPE_INVALID,
+    TYPE_NONE,
+    TYPE_INTERFACE,
+    TYPE_CHAR,
+    TYPE_UCHAR,
+    TYPE_BOOLEAN,
+    TYPE_INT,
+    TYPE_UINT,
+    TYPE_LONG,
+    TYPE_ULONG,
+    TYPE_INT64,
+    TYPE_UINT64,
+    TYPE_ENUM,
+    TYPE_FLAGS,
+    TYPE_FLOAT,
+    TYPE_DOUBLE,
+    TYPE_STRING,
+    TYPE_POINTER,
+    TYPE_BOXED,
+    TYPE_PARAM,
+    TYPE_OBJECT,
+    TYPE_GTYPE,
+    TYPE_VARIANT,
+    TYPE_UNICHAR,
+    getErrorType,
+    getStrvType,
+    isResolvableDescriptor,
+    isTypedClass,
+    typeIsA,
+    typeParent,
+    typeInterfaces,
+    typeFromName,
+    typeFundamental,
+    typeName,
+    valueIsA,
+    resolveType,
+    resolveBoxedType,
+    resolveFundamentalType,
+    resolveDescriptorType,
+    type ResolvableDescriptor,
+    type TypedClass,
+};