@graphty/webgpu-graph-algorithms 0.5.1 → 0.6.1

package/src/kernel/kernel.ts

@@ -2,7 +2,8 @@
  * Kernel (spec 5.1; contract 3.9): a compiled pipeline bound to the binding list of its spec. `bind()` creates the
  * bind groups from a `Record<name, Binding>` keyed by the declared names and caches them by the identity of the
  * buffers, offsets and sizes (a layout's bind groups are created once per load(), not per iteration); `dispatch()`
- * records setPipeline / setBindGroup / dispatchWorkgroups and skips an empty plan (spec 5.6).
+ * records setPipeline / setBindGroup / dispatchWorkgroups and skips an empty plan (spec 5.6); `dispatchIndirect()`
+ * (P4, spec 5.4) records the same prefix and a dispatchWorkgroupsIndirect over one 16-byte slot of an args buffer.
  */
 
 import { STORAGE_ALIGN } from "../constants.js";
@@ -21,6 +22,9 @@ export interface BoundKernel {
     readonly dynamicGroups: readonly number[];
 }
 
+/** Bytes of one indirect args slot: (x, y, 1, count) as four u32 (spec 5.4; P4 PD-2). */
+export const INDIRECT_ARGS_STRIDE = 16;
+
 /** Buffer identities for the bind-group cache key: every GPUBuffer seen by any Kernel gets one number, once. */
 const bufferIds = new WeakMap<GPUBuffer, number>();
 let nextBufferId = 1;
@@ -259,6 +263,50 @@ export class Kernel {
         plan: DispatchPlan,
         dynamicOffsets?: readonly number[],
     ): void {
+        this.check(bound, dynamicOffsets);
+        if (plan.x === 0) {
+            return;
+        }
+        this.setUp(pass, bound, dynamicOffsets);
+        pass.dispatchWorkgroups(plan.x, plan.y, 1);
+    }
+
+    /**
+     * setPipeline + the bind groups exactly as dispatch(), then dispatchWorkgroupsIndirect(args.buffer, args.offset +
+     * INDIRECT_ARGS_STRIDE * slot) (spec 5.4): the (x, y, 1) of the slot were written by the indirect-finalize kernel
+     * earlier in the same pass. A slot beyond the binding is E_INVALID_ARGUMENT.
+     * @param pass - the open compute pass
+     * @param bound - a BoundKernel of THIS kernel
+     * @param args - the args buffer range (usage INDIRECT | STORAGE)
+     * @param slot - the 16-byte slot index inside the range
+     * @param dynamicOffsets - one byte offset per entry of bound.dynamicGroups
+     */
+    dispatchIndirect(
+        pass: GPUComputePassEncoder,
+        bound: BoundKernel,
+        args: Binding,
+        slot: number,
+        dynamicOffsets?: readonly number[],
+    ): void {
+        this.check(bound, dynamicOffsets);
+        if (!Number.isInteger(slot) || slot < 0 || (slot + 1) * INDIRECT_ARGS_STRIDE > args.size) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${this.spec.id}: args slot ${slot} is outside the binding`, {
+                argument: "slot",
+                value: slot,
+                expected: `0 <= slot < ${Math.floor(args.size / INDIRECT_ARGS_STRIDE)}`,
+            });
+        }
+        this.setUp(pass, bound, dynamicOffsets);
+        pass.dispatchWorkgroupsIndirect(args.buffer, args.offset + INDIRECT_ARGS_STRIDE * slot);
+    }
+
+    /**
+     * The argument checks dispatch() and dispatchIndirect() share: a BoundKernel of another kernel or an offset list
+     * of the wrong length is E_INVALID_ARGUMENT.
+     * @param bound - the bound kernel
+     * @param dynamicOffsets - the offsets, if any
+     */
+    private check(bound: BoundKernel, dynamicOffsets: readonly number[] | undefined): void {
         const { id } = this.spec;
         if (bound.kernel !== this) {
             throw new WebGpuGraphError(
@@ -282,9 +330,16 @@ export class Kernel {
                 },
             );
         }
-        if (plan.x === 0) {
-            return;
-        }
+    }
+
+    /**
+     * setPipeline + setBindGroup for every group (the dynamic offsets replicated over the uniform bindings of each
+     * dynamic group), the prefix dispatch() and dispatchIndirect() share.
+     * @param pass - the open compute pass
+     * @param bound - a BoundKernel of this kernel
+     * @param dynamicOffsets - one byte offset per entry of bound.dynamicGroups (absent = 0)
+     */
+    private setUp(pass: GPUComputePassEncoder, bound: BoundKernel, dynamicOffsets: readonly number[] | undefined): void {
         pass.setPipeline(this.pipeline);
         let next = 0;
         bound.bindGroups.forEach((bindGroup, group) => {
@@ -301,7 +356,6 @@ export class Kernel {
                 pass.setBindGroup(group, bindGroup);
             }
         });
-        pass.dispatchWorkgroups(plan.x, plan.y, 1);
     }
 
     /** Drops cached bind groups (a layout's buffers changed). */

package/src/kernel/prelude.ts

@@ -19,7 +19,11 @@ import {
     FA2_FLAG_FIRST,
     FR_COOLING_PATIENCE,
     FR_COOLING_STEP,
+    GRID_BBOX_MARGIN,
+    GRID_EXTENT_FLOOR,
+    GRID_HUB_CELL,
     MAX_WORKGROUPS_PER_DIM,
+    RADIX_BINS,
     U32_MAX,
     WORKGROUP_SIZE,
 } from "../constants.js";
@@ -55,6 +59,11 @@ const FA2_FLAG_FIRST: u32 = ${FA2_FLAG_FIRST}u;
 const FA2_FLAG_ADAPTIVE: u32 = ${FA2_FLAG_ADAPTIVE}u;
 const FR_COOLING_STEP: f32 = ${wgslF32Literal(FR_COOLING_STEP)};
 const FR_COOLING_PATIENCE: u32 = ${FR_COOLING_PATIENCE}u;
+const GRID_HUB_CELL: u32 = ${GRID_HUB_CELL}u;
+const GRID_EXTENT_FLOOR: f32 = ${wgslF32Literal(GRID_EXTENT_FLOOR)};
+const GRID_BBOX_MARGIN: f32 = ${wgslF32Literal(GRID_BBOX_MARGIN)};
+const RADIX_BINS: u32 = ${RADIX_BINS}u;
+const RADIX_DIGIT_MASK: u32 = ${RADIX_BINS - 1}u;
 const F32_MAX: f32 = 0x1.fffffep+127;
 override WG: u32 = ${WORKGROUP_SIZE}u;
 override USE_PERM: bool = false;

package/src/kernel/profiler.ts

@@ -4,8 +4,10 @@
  * every CommandBatch pass; `resolveInto(batch)` records the resolve plus a copy into the batch's
  * staging slot and `timings(bytes, request)` decodes `{ label, ns }` per pass from the batch's
  * readback bytes. Chromium quantises timestamps to 100 us (`quantised: true`); Dawn-node reports
- * 1,024 ns ticks (spec 2.6). The profiler never throws: a full query set drops timings and a device
- * without the feature disables it. Slot pairs are handed out in order and the cursor restarts at 0
+ * 1,024 ns ticks (spec 2.6). The profiler never throws: a full query set drops the timings of the
+ * passes past the budget and marks the batch's request `partial(request)` so a caller summing the
+ * rows into a duration falls back to wall time; a device without the feature disables it. Slot
+ * pairs are handed out in order and the cursor restarts at 0
  * after every resolve: queue order guarantees the resolve of batch A reads its slots before batch B
  * overwrites them, and one resolve buffer suffices for the same reason.
  */
@@ -36,8 +38,10 @@ export class Profiler {
     private readonly querySet: GPUQuerySet | null;
     private readonly resolveBuffer: GPUBuffer | null;
     private readonly labels = new WeakMap<ReadbackRequest, readonly string[]>();
+    private readonly partialRequests = new WeakSet<ReadbackRequest>();
     private pending: PendingPass[] = [];
     private cursor = 0;
+    private refused = 0;
     private destroyed = false;
 
     /**
@@ -69,12 +73,17 @@ export class Profiler {
     }
 
     /**
-     * The timestampWrites descriptor for a new pass, or undefined when disabled / out of slots.
+     * The timestampWrites descriptor for a new pass, or undefined when disabled / out of slots. A pass refused for
+     * want of slots is counted, and the next `resolveInto()` marks its request partial.
      * @param label - the pass name reported by `timings()`
      * @returns the descriptor a CommandBatch puts on beginComputePass, or undefined
      */
     beginPass(label: string): GPUComputePassTimestampWrites | undefined {
-        if (this.querySet === null || this.destroyed || this.cursor + 2 > this.slots) {
+        if (this.querySet === null || this.destroyed) {
+            return undefined;
+        }
+        if (this.cursor + 2 > this.slots) {
+            this.refused++;
             return undefined;
         }
         const begin = this.cursor;
@@ -100,11 +109,25 @@ export class Profiler {
             request,
             this.pending.map((pass) => pass.label),
         );
+        if (this.refused > 0) {
+            this.partialRequests.add(request);
+        }
         this.pending = [];
         this.cursor = 0;
+        this.refused = 0;
         return request;
     }
 
+    /**
+     * Whether a pass of the batch was refused a slot pair, so `timings()` covers only its first slots / 2 passes
+     * and their sum is not the batch's duration.
+     * @param request - the request `resolveInto()` returned
+     * @returns true when at least one pass of that batch went untimed
+     */
+    partial(request: ReadbackRequest): boolean {
+        return this.partialRequests.has(request);
+    }
+
     /**
      * Decodes the timings of a batch from its readback bytes.
      * @param bytes - the resolved readback of the batch
@@ -138,6 +161,7 @@ export class Profiler {
         this.destroyed = true;
         this.pending = [];
         this.cursor = 0;
+        this.refused = 0;
         if (this.querySet !== null) {
             this.querySet.destroy();
         }