knitting 0.1.56 → 0.1.61

package/src/memory/lock.d.ts

@@ -1,70 +1,77 @@
 import RingQueue from "../ipc/tools/ring-queue.js";
+type EncodePayloadFactory = typeof import("./payloadCodec.js").encodePayload;
+type DecodePayloadFactory = typeof import("./payloadCodec.js").decodePayload;
+export declare const registerLockPayloadCodec: (encode: EncodePayloadFactory, decode: DecodePayloadFactory) => void;
 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 PayloadSignal: {
+    readonly UNREACHABLE: 0;
+    readonly BigInt: 2;
+    readonly True: 3;
+    readonly False: 4;
+    readonly Undefined: 5;
+    readonly NaN: 6;
+    readonly Float64: 9;
+    readonly Null: 10;
+};
+export type PayloadSignal = typeof PayloadSignal[keyof typeof PayloadSignal];
+export declare const PayloadBuffer: {
+    readonly BORDER_SIGNAL_BUFFER: 11;
+    readonly String: 11;
+    readonly Json: 12;
+    readonly StaticString: 15;
+    readonly StaticJson: 16;
+    readonly Binary: 17;
+    readonly StaticBinary: 18;
+    readonly Int32Array: 19;
+    readonly Float64Array: 20;
+    readonly BigInt64Array: 21;
+    readonly BigUint64Array: 22;
+    readonly DataView: 23;
+    readonly Error: 24;
+    readonly Date: 25;
+    readonly Symbol: 26;
+    readonly StaticSymbol: 27;
+    readonly BigInt: 28;
+    readonly StaticBigInt: 29;
+    readonly StaticInt32Array: 31;
+    readonly StaticFloat64Array: 32;
+    readonly StaticBigInt64Array: 33;
+    readonly StaticBigUint64Array: 34;
+    readonly StaticDataView: 35;
+    readonly ArrayBuffer: 36;
+    readonly StaticArrayBuffer: 37;
+    readonly Buffer: 38;
+    readonly StaticBuffer: 39;
+    readonly EnvelopeStaticHeader: 40;
+    readonly EnvelopeDynamicHeader: 41;
+    readonly EnvelopeStaticHeaderString: 42;
+    readonly EnvelopeDynamicHeaderString: 43;
+    readonly ExternalPayload: 44;
+    readonly StaticExternalPayload: 45;
+    readonly ProcessSharedBuffer: 46;
+    readonly BufferReference: 47;
+    readonly SharedArrayBuffer: 48;
+    readonly EnvelopeStaticHeaderExternal: 49;
+    readonly EnvelopeDynamicHeaderExternal: 50;
+    readonly EnvelopeStaticHeaderStringExternal: 51;
+    readonly EnvelopeDynamicHeaderStringExternal: 52;
+    readonly NumericArray: 53;
+    readonly StaticNumericArray: 54;
+};
+export type PayloadBuffer = typeof PayloadBuffer[keyof typeof PayloadBuffer];
+export declare const payloadBufferName: (value: number) => string;
+export declare const LockBound: {
+    readonly paddingLock: 0;
+    readonly padding: 0;
+    readonly slots: 32;
+    readonly header: 0;
+};
+export type LockBound = typeof LockBound[keyof typeof LockBound];
 export declare const LOCK_CACHE_LINE_BYTES = 64;
 export declare const LOCK_SECTOR_BYTES = 256;
 export type Task = [
@@ -92,33 +99,34 @@ 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 {
+export declare const TaskIndex: {
     /**
      * Worker -> host response flags word.
      */
-    FlagsToHost = 0,
+    readonly 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,
+    readonly FunctionID: 0;
+    readonly ID: 1;
+    readonly Type: 2;
+    readonly Start: 3;
+    readonly End: 4;
+    readonly 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,
+    readonly slotBuffer: 6;
+    readonly Size: 8;
     /**
      * Total slot length in Uint32 words, including the task header.
      */
-    TotalBuff = 144
-}
+    readonly TotalBuff: 144;
+};
+export type TaskIndex = typeof TaskIndex[keyof typeof TaskIndex];
 export declare const TASK_SLOT_INDEX_BITS = 5;
 export declare const TASK_SLOT_INDEX_MASK: number;
 export declare const TASK_SLOT_META_BITS: number;
@@ -135,11 +143,12 @@ 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 TaskFlag: {
+    readonly Reject: 1;
+};
+export type TaskFlag = typeof TaskFlag[keyof typeof TaskFlag];
 export declare const LOCK_WORD_BYTES: number;
-export declare const LOCK_HOST_BITS_OFFSET_BYTES = LockBound.paddingLock;
+export declare const LOCK_HOST_BITS_OFFSET_BYTES: 0;
 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;
@@ -150,6 +159,20 @@ 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 STEAL_ACK_SLOT_OFFSET_U32: number;
+export declare const STEAL_WANT_SLOT_OFFSET_U32: number;
+/**
+ * The payload allocator needs its own participant-owned ACK per consumer, since
+ * several workers can free payload slots from one shared allocator. No intent
+ * word: freeing needs no arbitration, a consumer only frees what it drained.
+ */
+export declare const STEAL_PAYLOAD_ACK_SLOT_OFFSET_U32: number;
+/**
+ * Host-owned liveness mask for stealing consumers. A dead claimant may leave
+ * its WANT word set forever; survivors ignore WANT from consumers whose bit is
+ * clear here. This preserves single-writer ownership of every WANT word.
+ */
+export declare const STEAL_LIVE_SLOT_OFFSET_U32: number;
 export declare const HEADER_U32_LENGTH: number;
 export declare const HEADER_BYTE_LENGTH: number;
 export declare const makeTask: () => Task;
@@ -168,7 +191,7 @@ type ResolveHostOptions = {
  *  - 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, }: {
+export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, consumers, consumerId, regionLanes, }: {
     headers?: SharedBufferSource;
     headerSlotStrideU32?: number;
     LockBoundSector?: SharedBufferSource;
@@ -179,6 +202,17 @@ export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, pa
     toSentList?: RingQueue<Task>;
     resultList?: RingQueue<Task>;
     recycleList?: RingQueue<Task>;
+    processBoundary?: boolean;
+    /**
+     * Number of consumer endpoints sharing this lock. `1` (default) keeps the
+     * classic single-consumer path. `> 1` enables region-Dekker work stealing and
+     * is only valid on a host->worker submit lock, never on a return lock.
+     */
+    consumers?: number;
+    /** This endpoint's id, `0..consumers-1`. Priority is fixed by id. */
+    consumerId?: number;
+    /** Lanes claimed per Dekker handshake. Paper rule: `slots / regionLanes >= consumers + 1`. */
+    regionLanes?: number;
 }) => {
     enlist: (task: Task) => true;
     encode: (task: Task, state?: number) => boolean;
@@ -197,6 +231,7 @@ export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, pa
     getPendingFrameCount: () => number;
     getPendingPromiseCount: () => number;
     resetPendingState: () => void;
+    deactivateStealConsumer: (id: number) => boolean;
     takeDeferredCount: () => number;
     setPromiseHandler: (handler?: PromisePayloadHandler) => void;
 };