@simulatte/doppler 0.1.9 → 0.2.0

package/src/gpu/submit-tracker.js

@@ -1,242 +0,0 @@
-
-
-import { trackSubmit } from './perf-guards.js';
-import { log, trace } from '../debug/index.js';
-
-
-export let TRACK_SUBMITS = false;
-
-
-let submitCount = 0;
-
-let submitTimes = [];
-let totalSubmitMs = 0;
-let maxSubmitMs = 0;
-let minSubmitMs = Infinity;
-
-let submitSources = new Map();
-
-
-
-
-let currentPhase = 'other';
-
-const WRAPPED_QUEUE_SENTINEL = Symbol.for('doppler.submitTrackerWrapped');
-
-
-const phaseStats = {
-  prefill: { count: 0, times: [], totalMs: 0, maxMs: 0, minMs: Infinity, sources: new Map() },
-  decode: { count: 0, times: [], totalMs: 0, maxMs: 0, minMs: Infinity, sources: new Map() },
-  other: { count: 0, times: [], totalMs: 0, maxMs: 0, minMs: Infinity, sources: new Map() },
-};
-
-
-export function setTrackSubmits(enabled) {
-  TRACK_SUBMITS = enabled;
-  if (enabled) {
-    resetSubmitStats();
-    log.debug('SubmitTracker', 'Enabled');
-  } else {
-    log.debug('SubmitTracker', 'Disabled');
-  }
-}
-
-
-export function resetSubmitStats() {
-  submitCount = 0;
-  submitTimes = [];
-  totalSubmitMs = 0;
-  maxSubmitMs = 0;
-  minSubmitMs = Infinity;
-  submitSources = new Map();
-  currentPhase = 'other';
-
-  // Reset phase stats
-  for (const phase of  (['prefill', 'decode', 'other'])) {
-    phaseStats[phase] = { count: 0, times: [], totalMs: 0, maxMs: 0, minMs: Infinity, sources: new Map() };
-  }
-}
-
-
-export function setSubmitPhase(phase) {
-  currentPhase = phase;
-}
-
-
-export function recordSubmit(durationMs, source) {
-  if (!TRACK_SUBMITS) return;
-
-  // Global stats
-  submitCount++;
-  submitTimes.push(durationMs);
-  totalSubmitMs += durationMs;
-  maxSubmitMs = Math.max(maxSubmitMs, durationMs);
-  minSubmitMs = Math.min(minSubmitMs, durationMs);
-
-  // Track by source
-  if (source) {
-    submitSources.set(source, (submitSources.get(source) || 0) + 1);
-  }
-
-  // Phase-specific stats
-  const ps = phaseStats[currentPhase];
-  ps.count++;
-  ps.times.push(durationMs);
-  ps.totalMs += durationMs;
-  ps.maxMs = Math.max(ps.maxMs, durationMs);
-  ps.minMs = Math.min(ps.minMs, durationMs);
-
-  // Track source in phase stats
-  if (source) {
-    ps.sources.set(source, (ps.sources.get(source) || 0) + 1);
-  }
-}
-
-
-export function getSubmitStats() {
-  return {
-    count: submitCount,
-    totalMs: totalSubmitMs,
-    avgMs: submitCount > 0 ? totalSubmitMs / submitCount : 0,
-    maxMs: maxSubmitMs,
-    minMs: minSubmitMs === Infinity ? 0 : minSubmitMs,
-    timestamps: [...submitTimes],
-    bySource: new Map(submitSources),
-  };
-}
-
-
-export function getPhaseSubmitStats(phase) {
-  const ps = phaseStats[phase];
-  return {
-    count: ps.count,
-    totalMs: ps.totalMs,
-    avgMs: ps.count > 0 ? ps.totalMs / ps.count : 0,
-    maxMs: ps.maxMs,
-    minMs: ps.minMs === Infinity ? 0 : ps.minMs,
-    timestamps: [...ps.times],
-    bySource: new Map(ps.sources),
-  };
-}
-
-
-export function getAllPhaseSubmitStats() {
-  return {
-    prefill: getPhaseSubmitStats('prefill'),
-    decode: getPhaseSubmitStats('decode'),
-    other: getPhaseSubmitStats('other'),
-  };
-}
-
-
-export function logSubmitStats(label = 'Forward pass') {
-  const stats = getSubmitStats();
-  trace.perf(
-    `SubmitTracker ${label}: ${stats.count} submits, ` +
-    `total=${stats.totalMs.toFixed(2)}ms, ` +
-    `avg=${stats.avgMs.toFixed(3)}ms, ` +
-    `range=[${stats.minMs.toFixed(3)}-${stats.maxMs.toFixed(3)}ms]`
-  );
-
-  // Log by source if available
-  if (stats.bySource && stats.bySource.size > 0) {
-    trace.perf('SubmitTracker: Submits by source:');
-    const sorted = Array.from(stats.bySource.entries()).sort((a, b) => b[1] - a[1]);
-    for (const [source, count] of sorted) {
-      const pct = ((count / stats.count) * 100).toFixed(1);
-      trace.perf(`  ${source}: ${count} (${pct}%)`);
-    }
-  }
-}
-
-
-export function logAllPhaseSubmitStats(label = 'All phases') {
-  const allStats = getAllPhaseSubmitStats();
-  trace.perf(`SubmitTracker ${label}:`);
-
-  for (const phase of  (['prefill', 'decode', 'other'])) {
-    const stats = allStats[phase];
-    if (stats.count === 0) continue;
-
-    trace.perf(
-      `  ${phase}: ${stats.count} submits, ` +
-      `total=${stats.totalMs.toFixed(2)}ms, ` +
-      `avg=${stats.avgMs.toFixed(3)}ms`
-    );
-
-    // Log by source for this phase
-    if (stats.bySource && stats.bySource.size > 0) {
-      const sorted = Array.from(stats.bySource.entries()).sort((a, b) => b[1] - a[1]);
-      for (const [source, count] of sorted) {
-        const pct = ((count / stats.count) * 100).toFixed(1);
-        trace.perf(`    ${source}: ${count} (${pct}%)`);
-      }
-    }
-  }
-}
-
-
-function extractSourceFromStack() {
-  const stack = new Error().stack;
-  if (!stack) return 'unknown';
-
-  const lines = stack.split('\n');
-  // Skip first 3 lines: Error, extractSourceFromStack, queue.submit wrapper
-  for (let i = 3; i < lines.length; i++) {
-    const line = lines[i];
-    // Match file:line pattern in stack trace
-    // Example: "at functionName (http://localhost:8080/path/to/file.ts:123:45)"
-    const match = line.match(/\/([^\/]+\.(?:js|ts)):(\d+):/);
-    if (match) {
-      return `${match[1]}:${match[2]}`;
-    }
-  }
-  return 'unknown';
-}
-
-
-export function wrapQueueForTracking(queue) {
-  if (!queue || queue[WRAPPED_QUEUE_SENTINEL] === true) {
-    return queue;
-  }
-
-  const originalSubmit = queue.submit.bind(queue);
-
-   (queue).submit = function( commandBuffers) {
-    const start = TRACK_SUBMITS ? performance.now() : 0;
-    const result = originalSubmit(commandBuffers);
-    trackSubmit();
-
-    if (!TRACK_SUBMITS) {
-      return result;
-    }
-
-    const duration = performance.now() - start;
-    recordSubmit(duration, extractSourceFromStack());
-    return result;
-  };
-
-  Object.defineProperty(queue, WRAPPED_QUEUE_SENTINEL, {
-    value: true,
-    configurable: true,
-    enumerable: false,
-    writable: false,
-  });
-
-  return queue;
-}
-
-
-export function estimateBatchingSavings(
-  currentStats,
-  targetSubmits = 1
-) {
-  const savedSubmits = Math.max(0, currentStats.count - targetSubmits);
-  // Each submit has overhead, estimate savings based on average submit time
-  const estimatedSavingsMs = savedSubmits * currentStats.avgMs;
-
-  return {
-    savedSubmits,
-    estimatedSavingsMs,
-  };
-}

package/src/gpu/tensor.d.ts

@@ -1,69 +0,0 @@
-/**
- * Tensor Abstraction
- *
- * Wraps GPUBuffer with explicit dtype and shape metadata.
- * Ensures dtype flows through the pipeline structurally rather than
- * being tracked in a separate WeakMap.
- */
-
-export type TensorDtype = 'f16' | 'f32';
-
-/**
- * A tensor with explicit dtype and shape.
- * Use this instead of raw GPUBuffer for dtype-sensitive operations.
- */
-export interface Tensor {
-  readonly buffer: GPUBuffer;
-  readonly dtype: TensorDtype;
-  readonly shape: readonly number[];
-  readonly label?: string;
-}
-
-/**
- * Create a tensor from a buffer with explicit dtype.
- */
-export function createTensor(
-  buffer: GPUBuffer,
-  dtype: TensorDtype,
-  shape: number[],
-  label?: string
-): Tensor;
-
-/**
- * Assert tensor has expected dtype, throw if mismatch.
- */
-export function assertDtype(
-  tensor: Tensor,
-  expected: TensorDtype,
-  operation: string
-): void;
-
-/**
- * Assert tensor has expected shape, throw if mismatch.
- */
-export function assertShape(
-  tensor: Tensor,
-  expected: readonly number[],
-  operation: string
-): void;
-
-/**
- * Get bytes per element for dtype.
- */
-export function dtypeBytes(dtype: TensorDtype): number;
-
-/**
- * Compute total byte size for a tensor.
- */
-export function tensorBytes(shape: readonly number[], dtype: TensorDtype): number;
-
-/**
- * Check if two tensors have compatible dtypes for an operation.
- */
-export function dtypesMatch(a: Tensor, b: Tensor): boolean;
-
-/**
- * Determine output dtype for a binary operation.
- * F16 only if both inputs are F16.
- */
-export function inferOutputDtype(a: Tensor, b: Tensor): TensorDtype;

package/src/gpu/tensor.js

@@ -1,75 +0,0 @@
-
-
-
-import { selectRuleValue } from '../rules/rule-registry.js';
-
-
-export function createTensor(
-  buffer,
-  dtype,
-  shape,
-  label
-) {
-  return {
-    buffer,
-    dtype,
-    shape: Object.freeze([...shape]),
-    label,
-  };
-}
-
-
-export function assertDtype(
-  tensor,
-  expected,
-  operation
-) {
-  if (tensor.dtype !== expected) {
-    throw new Error(
-      `${operation}: expected ${expected} tensor, got ${tensor.dtype}` +
-      (tensor.label ? ` (${tensor.label})` : '')
-    );
-  }
-}
-
-
-export function assertShape(
-  tensor,
-  expected,
-  operation
-) {
-  if (tensor.shape.length !== expected.length) {
-    throw new Error(
-      `${operation}: expected ${expected.length}D tensor, got ${tensor.shape.length}D` +
-      (tensor.label ? ` (${tensor.label})` : '')
-    );
-  }
-  for (let i = 0; i < expected.length; i++) {
-    if (expected[i] !== -1 && tensor.shape[i] !== expected[i]) {
-      throw new Error(
-        `${operation}: shape mismatch at dim ${i}: expected ${expected[i]}, got ${tensor.shape[i]}` +
-        (tensor.label ? ` (${tensor.label})` : '')
-      );
-    }
-  }
-}
-
-
-export function dtypeBytes(dtype) {
-  return dtype === 'f16' ? 2 : 4;
-}
-
-
-export function tensorBytes(shape, dtype) {
-  return shape.reduce((a, b) => a * b, 1) * dtypeBytes(dtype);
-}
-
-
-export function dtypesMatch(a, b) {
-  return a.dtype === b.dtype;
-}
-
-
-export function inferOutputDtype(a, b) {
-  return selectRuleValue('shared', 'dtype', 'bothF16', { aDtype: a.dtype, bDtype: b.dtype });
-}

package/src/gpu/uniform-cache.d.ts

@@ -1,109 +0,0 @@
-/**
- * Uniform Buffer Cache
- *
- * Caches small uniform buffers by content hash to avoid repeated allocations.
- * WebLLM-inspired optimization: uniform buffers with identical contents are reused
- * across kernel dispatches instead of being created fresh and destroyed each time.
- */
-
-interface UniformCacheEntry {
-  buffer: GPUBuffer;
-  bytes: Uint8Array;
-  lastUsed: number;
-  refCount: number;
-}
-
-interface UniformCacheStats {
-  hits: number;
-  misses: number;
-  evictions: number;
-  currentSize: number;
-}
-
-/**
- * Uniform Buffer Cache
- *
- * Provides content-addressed caching for uniform buffers. Buffers with
- * identical contents share the same GPU buffer, reducing allocation overhead.
- *
- * IMPORTANT: Evicted buffers are NOT destroyed immediately. They are queued
- * for deferred destruction to avoid use-after-destroy bugs when command
- * buffers reference cached uniforms that get evicted before submit.
- * Call flushPendingDestruction() after GPU work completes.
- */
-export declare class UniformBufferCache {
-  private cache: Map<string, UniformCacheEntry>;
-  private stats: UniformCacheStats;
-  private pendingDestruction: GPUBuffer[];
-  private readonly maxEntries: number;
-  private readonly maxAgeMs: number;
-
-  constructor(maxEntries?: number, maxAgeMs?: number);
-
-  /**
-   * Get or create a uniform buffer with the given contents.
-   * Returns a cached buffer if one exists with identical data.
-   */
-  getOrCreate(data: ArrayBuffer | SharedArrayBuffer, label: string): GPUBuffer;
-
-  /**
-   * Release a reference to a cached buffer.
-   * Buffer is NOT destroyed - it stays in cache for reuse.
-   * Call this instead of buffer.destroy() for cached uniforms.
-   */
-  release(buffer: GPUBuffer): void;
-
-  /**
-   * Evict stale entries (older than maxAgeMs).
-   * Buffers are queued for deferred destruction.
-   */
-  evictStale(): number;
-
-  /**
-   * Clear all cached buffers.
-   * Also flushes any pending destruction queue.
-   */
-  clear(): void;
-
-  /**
-   * Destroy all buffers in the pending destruction queue.
-   * Call this after GPU work completes (e.g., after onSubmittedWorkDone).
-   *
-   * This is critical for avoiding use-after-destroy bugs: when the uniform
-   * cache evicts a buffer that's still referenced by a pending command buffer,
-   * the buffer is queued here instead of being destroyed immediately.
-   */
-  flushPendingDestruction(): number;
-
-  /**
-   * Get the number of buffers pending destruction.
-   */
-  getPendingDestructionCount(): number;
-
-  /**
-   * Check if a buffer is managed by this cache
-   */
-  isCached(buffer: GPUBuffer): boolean;
-
-  /**
-   * Get cache statistics
-   */
-  getStats(): UniformCacheStats & { hitRate: string; pendingDestruction: number };
-}
-
-/**
- * Release or destroy a uniform buffer appropriately.
- * If the buffer is cached, releases it back to the cache.
- * If not cached, destroys it directly.
- */
-export function releaseUniformBuffer(buffer: GPUBuffer): void;
-
-/**
- * Get the global uniform buffer cache instance
- */
-export function getUniformCache(): UniformBufferCache;
-
-/**
- * Reset the global uniform cache (useful for testing or device loss)
- */
-export function resetUniformCache(): void;