knitting 0.1.55 → 0.1.56

package/src/memory/byte-carpet.js

@@ -0,0 +1,157 @@
+export const BYTE_CARPET_ALIGN_BYTES = 64;
+const U32_BYTES = Uint32Array.BYTES_PER_ELEMENT;
+const toNonNegativeInteger = (value, label) => {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new RangeError(`${label} must be a non-negative integer`);
+    }
+    return value;
+};
+export const alignBytes = (value, alignment = BYTE_CARPET_ALIGN_BYTES) => {
+    const safeValue = toNonNegativeInteger(value, "value");
+    const safeAlignment = toNonNegativeInteger(alignment, "alignment");
+    if (safeAlignment === 0) {
+        throw new RangeError("alignment must be greater than zero");
+    }
+    return Math.ceil(safeValue / safeAlignment) * safeAlignment;
+};
+export const makeSharedBufferRegion = (sab, byteOffset, byteLength) => ({
+    sab,
+    byteOffset: toNonNegativeInteger(byteOffset, "byteOffset"),
+    byteLength: toNonNegativeInteger(byteLength, "byteLength"),
+});
+export const createByteCarpet = ({ alignTo = BYTE_CARPET_ALIGN_BYTES, startByteOffset = 0, } = {}) => {
+    const defaultAlignment = toNonNegativeInteger(alignTo, "alignTo");
+    if (defaultAlignment === 0) {
+        throw new RangeError("alignTo must be greater than zero");
+    }
+    let cursor = toNonNegativeInteger(startByteOffset, "startByteOffset");
+    const slices = [];
+    const take = (name, byteLength, { alignTo: sliceAlignment = defaultAlignment, reserveByteLength, } = {}) => {
+        const logicalByteLength = toNonNegativeInteger(byteLength, `${name} byteLength`);
+        const safeSliceAlignment = toNonNegativeInteger(sliceAlignment, `${name} alignTo`);
+        if (safeSliceAlignment === 0) {
+            throw new RangeError(`${name} alignTo must be greater than zero`);
+        }
+        const reserved = reserveByteLength == null
+            ? alignBytes(logicalByteLength, safeSliceAlignment)
+            : toNonNegativeInteger(reserveByteLength, `${name} reserveByteLength`);
+        if (reserved < logicalByteLength) {
+            throw new RangeError(`${name} reserveByteLength must cover byteLength`);
+        }
+        const byteOffset = alignBytes(cursor, safeSliceAlignment);
+        const slice = {
+            name,
+            byteOffset,
+            byteLength: logicalByteLength,
+            reservedByteLength: reserved,
+        };
+        slices.push(slice);
+        cursor = byteOffset + reserved;
+        return slice;
+    };
+    return {
+        slices,
+        take,
+        byteLength: () => cursor,
+        bind: (sab, slice) => makeSharedBufferRegion(sab, slice.byteOffset, slice.byteLength),
+    };
+};
+export const getStridedSlotOffsetU32 = ({ slotIndex, slotStrideU32, baseU32 = 0, extraU32 = 0, }) => (slotIndex * slotStrideU32) + baseU32 + extraU32;
+export const getStridedSlotByteOffset = ({ slotIndex, slotStrideU32, baseByteOffset = 0, baseU32 = 0, extraU32 = 0, }) => baseByteOffset +
+    (getStridedSlotOffsetU32({
+        slotIndex,
+        slotStrideU32,
+        baseU32,
+        extraU32,
+    }) * U32_BYTES);
+export const getStridedRegionSpanBytes = ({ slotCount, slotStrideU32, slotLengthU32, baseU32 = 0, }) => {
+    const safeSlotCount = toNonNegativeInteger(slotCount, "slotCount");
+    if (safeSlotCount === 0)
+        return 0;
+    return (getStridedSlotOffsetU32({
+        slotIndex: safeSlotCount - 1,
+        slotStrideU32,
+        baseU32,
+    }) + slotLengthU32) * U32_BYTES;
+};
+export const getInterleavedSlotStrideU32 = (slotStrideU32) => slotStrideU32 * 2;
+export const getHeaderBlockByteLength = ({ slotCount, slotStrideU32, queues = 1, alignTo = BYTE_CARPET_ALIGN_BYTES, }) => alignBytes(slotCount * slotStrideU32 * U32_BYTES * queues, alignTo);
+const createInterleavedHeaderPair = ({ sab, byteOffset, slotCount, slotStrideU32, }) => {
+    const headerSlotStrideU32 = getInterleavedSlotStrideU32(slotStrideU32);
+    const slotBytes = slotStrideU32 * U32_BYTES;
+    const spanBytes = getStridedRegionSpanBytes({
+        slotCount,
+        slotStrideU32: headerSlotStrideU32,
+        slotLengthU32: slotStrideU32,
+    });
+    return {
+        headerSlotStrideU32,
+        requestHeaders: makeSharedBufferRegion(sab, byteOffset, spanBytes),
+        returnHeaders: makeSharedBufferRegion(sab, byteOffset + slotBytes, spanBytes),
+    };
+};
+export const createLockControlCarpet = ({ signalBytes, abortBytes, lockSectorBytes, headerSlotStrideU32, slotCount, headerLayout = "interleaved", alignTo = BYTE_CARPET_ALIGN_BYTES, createBuffer = (byteLength) => new SharedArrayBuffer(byteLength), }) => {
+    const carpet = createByteCarpet({ alignTo });
+    const signalsSlice = carpet.take("signals", signalBytes);
+    const requestLockSlice = carpet.take("requestLockSector", lockSectorBytes);
+    const returnLockSlice = carpet.take("returnLockSector", lockSectorBytes);
+    let requestHeadersSlice;
+    let returnHeadersSlice;
+    let interleavedHeadersSlice;
+    if (headerLayout === "interleaved") {
+        interleavedHeadersSlice = carpet.take("interleavedHeaders", getHeaderBlockByteLength({
+            slotCount,
+            slotStrideU32: headerSlotStrideU32,
+            queues: 2,
+            alignTo,
+        }));
+    }
+    else {
+        requestHeadersSlice = carpet.take("requestHeaders", getHeaderBlockByteLength({
+            slotCount,
+            slotStrideU32: headerSlotStrideU32,
+            alignTo,
+        }));
+        returnHeadersSlice = carpet.take("returnHeaders", getHeaderBlockByteLength({
+            slotCount,
+            slotStrideU32: headerSlotStrideU32,
+            alignTo,
+        }));
+    }
+    const abortSignalsSlice = carpet.take("abortSignals", abortBytes);
+    const controlSAB = createBuffer(carpet.byteLength());
+    const signals = carpet.bind(controlSAB, signalsSlice);
+    const abortSignals = carpet.bind(controlSAB, abortSignalsSlice);
+    const requestLockSector = carpet.bind(controlSAB, requestLockSlice);
+    const returnLockSector = carpet.bind(controlSAB, returnLockSlice);
+    const headerPair = headerLayout === "interleaved"
+        ? createInterleavedHeaderPair({
+            sab: controlSAB,
+            byteOffset: interleavedHeadersSlice.byteOffset,
+            slotCount,
+            slotStrideU32: headerSlotStrideU32,
+        })
+        : {
+            headerSlotStrideU32,
+            requestHeaders: carpet.bind(controlSAB, requestHeadersSlice),
+            returnHeaders: carpet.bind(controlSAB, returnHeadersSlice),
+        };
+    return {
+        controlSAB,
+        signals,
+        abortSignals,
+        lock: {
+            headers: headerPair.requestHeaders,
+            headerSlotStrideU32: headerPair.headerSlotStrideU32,
+            lockSector: requestLockSector,
+            payloadSector: requestLockSector,
+        },
+        returnLock: {
+            headers: headerPair.returnHeaders,
+            headerSlotStrideU32: headerPair.headerSlotStrideU32,
+            lockSector: returnLockSector,
+            payloadSector: returnLockSector,
+        },
+        slices: carpet.slices,
+    };
+};

package/src/memory/lock.d.ts

@@ -0,0 +1,203 @@
+import RingQueue from "../ipc/tools/ring-queue.js";
+import { type SharedBufferSource } from "../common/shared-buffer-region.js";
+import { type LockBufferTextCompat } from "../common/shared-buffer-text.js";
+import { type PayloadBufferOptions } from "./payload-config.js";
+/**
+ * TODO: Compose all the instance where the array is passed as argument
+ */
+export declare enum PayloadSignal {
+    UNREACHABLE = 0,
+    BigInt = 2,
+    True = 3,
+    False = 4,
+    Undefined = 5,
+    NaN = 6,
+    Float64 = 9,
+    Null = 10
+}
+export declare enum PayloadBuffer {
+    BORDER_SIGNAL_BUFFER = 11,
+    String = 11,
+    Json = 12,
+    StaticString = 15,
+    StaticJson = 16,
+    Binary = 17,
+    StaticBinary = 18,
+    Int32Array = 19,
+    Float64Array = 20,
+    BigInt64Array = 21,
+    BigUint64Array = 22,
+    DataView = 23,
+    Error = 24,
+    Date = 25,
+    Symbol = 26,
+    StaticSymbol = 27,
+    BigInt = 28,
+    StaticBigInt = 29,
+    StaticInt32Array = 31,
+    StaticFloat64Array = 32,
+    StaticBigInt64Array = 33,
+    StaticBigUint64Array = 34,
+    StaticDataView = 35,
+    ArrayBuffer = 36,
+    StaticArrayBuffer = 37,
+    Buffer = 38,
+    StaticBuffer = 39,
+    EnvelopeStaticHeader = 40,
+    EnvelopeDynamicHeader = 41,
+    EnvelopeStaticHeaderString = 42,
+    EnvelopeDynamicHeaderString = 43,
+    ExternalPayload = 44,
+    StaticExternalPayload = 45,
+    ProcessSharedBuffer = 46,
+    BufferReference = 47,
+    SharedArrayBuffer = 48,
+    EnvelopeStaticHeaderExternal = 49,
+    EnvelopeDynamicHeaderExternal = 50,
+    EnvelopeStaticHeaderStringExternal = 51,
+    EnvelopeDynamicHeaderStringExternal = 52,
+    NumericArray = 53,
+    StaticNumericArray = 54
+}
+export declare enum LockBound {
+    paddingLock = 0,
+    padding = 0,
+    slots = 32,
+    header = 0
+}
+export declare const LOCK_CACHE_LINE_BYTES = 64;
+export declare const LOCK_SECTOR_BYTES = 256;
+export type Task = [
+    number,
+    number,
+    PayloadSignal | PayloadBuffer,
+    number,
+    number,
+    number,
+    number,
+    number
+] & {
+    value: unknown;
+    finalize?: (() => void) | undefined;
+    resolve: (value?: unknown) => void;
+    reject: (reason?: unknown) => void;
+};
+export declare const PayloadTransportFinalizer: unique symbol;
+export declare const PromisePayloadMarker: unique symbol;
+export type PromisePayloadHandler = (task: Task, isRejected: boolean, value: unknown) => void;
+export declare const beginPromisePayload: (task: Task) => boolean;
+export declare const finishPromisePayload: (task: Task) => void;
+export declare const isPromisePayloadPending: (task: Task) => boolean;
+export declare const resetTaskLocalFlags: (task: Task) => void;
+export declare const addTaskFinalizer: (task: Task, finalizer: () => void) => void;
+export declare const attachPayloadTransportFinalizer: (task: Task, value: unknown) => void;
+export declare const runTaskFinalizers: (task: Task) => void;
+export declare enum TaskIndex {
+    /**
+     * Worker -> host response flags word.
+     */
+    FlagsToHost = 0,
+    /**
+     * Host -> worker request function id (low 16 bits).
+     * High 16 bits are reserved for caller metadata on request path.
+     * NOTE: shares the same storage word as `FlagsToHost`.
+     */
+    FunctionID = 0,
+    ID = 1,
+    Type = 2,
+    Start = 3,
+    End = 4,
+    PayloadLen = 5,
+    /**
+     * Low 5 bits: region slot index (0..31).
+     * High 27 bits: reserved for caller metadata (e.g. enqueue timing).
+     */
+    slotBuffer = 6,
+    Size = 8,
+    /**
+     * Total slot length in Uint32 words, including the task header.
+     */
+    TotalBuff = 144
+}
+export declare const TASK_SLOT_INDEX_BITS = 5;
+export declare const TASK_SLOT_INDEX_MASK: number;
+export declare const TASK_SLOT_META_BITS: number;
+export declare const TASK_SLOT_META_VALUE_MASK: number;
+export declare const TASK_FUNCTION_ID_BITS = 16;
+export declare const TASK_FUNCTION_ID_MASK: number;
+export declare const TASK_FUNCTION_META_BITS: number;
+export declare const TASK_FUNCTION_META_VALUE_MASK: number;
+export declare const getTaskFunctionID: (task: ArrayLike<number>) => number;
+export declare const setTaskFunctionID: (task: Task, functionID: number) => void;
+export declare const getTaskFunctionMeta: (task: ArrayLike<number>) => number;
+export declare const setTaskFunctionMeta: (task: Task, value: number) => void;
+export declare const getTaskSlotIndex: (task: ArrayLike<number>) => number;
+export declare const setTaskSlotIndex: (task: Task, slotIndex: number) => void;
+export declare const getTaskSlotMeta: (task: ArrayLike<number>) => number;
+export declare const setTaskSlotMeta: (task: Task, value: number) => void;
+export declare enum TaskFlag {
+    Reject = 1
+}
+export declare const LOCK_WORD_BYTES: number;
+export declare const LOCK_HOST_BITS_OFFSET_BYTES = LockBound.paddingLock;
+export declare const LOCK_WORKER_BITS_OFFSET_BYTES = 64;
+export declare const LOCK_SECTOR_BYTE_LENGTH = 256;
+export declare const PAYLOAD_LOCK_HOST_BITS_OFFSET_BYTES: number;
+export declare const PAYLOAD_LOCK_WORKER_BITS_OFFSET_BYTES: number;
+export declare const PAYLOAD_LOCK_SECTOR_BYTE_LENGTH = 256;
+export declare const HEADER_SLOT_STRIDE_U32: number;
+export declare const HEADER_SLOT_STRIDE_BYTES: number;
+export declare const HEADER_TASK_LINE_U32: number;
+export declare const HEADER_STATIC_PAYLOAD_U32: number;
+export declare const HEADER_TASK_OFFSET_IN_SLOT_U32: number;
+export declare const HEADER_U32_LENGTH: number;
+export declare const HEADER_BYTE_LENGTH: number;
+export declare const makeTask: () => Task;
+type ResolveHostOptions = {
+    queue: Task[];
+    onResolved?: (task: Task) => void;
+    shouldSettle?: (task: Task) => boolean;
+    activeRejectPlaceholder?: Task["reject"];
+};
+/**
+ * Complexity: 7 / 10
+ *
+ * SAFETY:
+ *  - Single producer/consumer; do not call encode/decode concurrently.
+ *  - Shared buffers must be the same between host/worker.
+ *  - encode/decode are not re-entrant; payload codec uses a shared scratch buffer.
+ */
+export type Lock2 = ReturnType<typeof lock2>;
+export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, }: {
+    headers?: SharedBufferSource;
+    headerSlotStrideU32?: number;
+    LockBoundSector?: SharedBufferSource;
+    payload?: SharedBufferSource;
+    payloadConfig?: PayloadBufferOptions;
+    payloadSector?: SharedBufferSource;
+    textCompat?: LockBufferTextCompat;
+    toSentList?: RingQueue<Task>;
+    resultList?: RingQueue<Task>;
+    recycleList?: RingQueue<Task>;
+}) => {
+    enlist: (task: Task) => true;
+    encode: (task: Task, state?: number) => boolean;
+    encodeManyFrom: (list: RingQueue<Task>) => number;
+    encodeAll: () => boolean;
+    publish: (task: Task) => boolean;
+    flushPending: () => boolean;
+    decode: () => boolean;
+    hasSpace: () => boolean;
+    resolved: RingQueue<Task>;
+    hostBits: Int32Array<import("../common/shared-buffer-region.js").SharedBuffer>;
+    workerBits: Int32Array<import("../common/shared-buffer-region.js").SharedBuffer>;
+    recyclecList: RingQueue<Task>;
+    resolveHost: ({ queue, onResolved, shouldSettle, activeRejectPlaceholder, }: ResolveHostOptions) => () => number;
+    hasPendingFrames: () => boolean;
+    getPendingFrameCount: () => number;
+    getPendingPromiseCount: () => number;
+    resetPendingState: () => void;
+    takeDeferredCount: () => number;
+    setPromiseHandler: (handler?: PromisePayloadHandler) => void;
+};
+export {};