@atolljs/core 0.1.7 → 0.1.8

package/src/userTiming.ts

@@ -0,0 +1,71 @@
+/**
+ * User Timing bridge: `performance.measure` entries for atoll work, so the
+ * browser's own Performance panel shows tasks next to the app's frames.
+ * Callers gate on `devtoolsEnabled()`; this module never checks it itself.
+ *
+ * `detail.devtools` is Chrome's extensibility payload: entries land on a
+ * custom track inside an 'atoll' track group. Other engines ignore the
+ * detail and record a plain measure.
+ */
+
+/** Chrome's extensibility palette names. */
+export type TimingColor = 'primary' | 'primary-light' | 'secondary' | 'tertiary' | 'error' | 'warning';
+
+export interface TimingTrack {
+  /** Track label inside the 'atoll' group, e.g. a pool id. */
+  track: string;
+  color?: TimingColor;
+  properties?: [string, string | number][];
+  tooltipText?: string;
+}
+
+type MeasureFn = (name: string, options: { start: number; end: number; detail?: unknown }) => unknown;
+
+/**
+ * Record `[start, end]` (performance.now() ms on this thread) as `name`.
+ * The entry is cleared from the timeline buffer right away: the Performance
+ * panel captures it at measure time, and per-task measures would otherwise
+ * grow the buffer without bound (and trip Node's buffer-size warning).
+ */
+export const measureAtoll = (name: string, start: number, end: number, t: TimingTrack): void => {
+  const perf = globalThis.performance as
+    | (Performance & { measure?: MeasureFn; clearMeasures?: (name?: string) => void })
+    | undefined;
+  if (typeof perf?.measure !== 'function') return;
+  try {
+    perf.measure(name, {
+      start,
+      end: Math.max(end, start),
+      detail: {
+        devtools: {
+          dataType: 'track-entry',
+          track: t.track,
+          trackGroup: 'atoll',
+          color: t.color ?? 'primary',
+          properties: t.properties,
+          tooltipText: t.tooltipText,
+        },
+      },
+    });
+    perf.clearMeasures?.(name);
+  } catch {
+    /* engines without the options-object measure signature */
+  }
+};
+
+/** Main-thread span of one call, dispatch → settle, on the runner's track. */
+export const measureTaskCall = (
+  runnerId: string,
+  taskId: string,
+  callId: number,
+  slot: number,
+  start: number,
+  end: number,
+  ok: boolean,
+): void =>
+  measureAtoll(`atoll task ${taskId}`, start, end, {
+    track: runnerId,
+    color: ok ? 'primary' : 'error',
+    properties: [['runner', runnerId], ['slot', slot], ['call', callId], ['outcome', ok ? 'ok' : 'error']],
+    tooltipText: `${taskId} on ${runnerId}#${slot}: ${(end - start).toFixed(1)}ms`,
+  });

package/src/worker/workerBootstrap.ts

@@ -1,10 +1,22 @@
 import { TaskRegistry } from './registry';
 import { bindSharedMemories, getDefinedSharedMemoryCount } from '../contract/sharedMemory';
-import { enableWorkerDevtoolsForwarding } from '../devtools';
+import { devtoolsEnabled, enableWorkerDevtoolsForwarding } from '../devtools';
 import { fmtBytes, scoped } from '../log';
+import { measureAtoll } from '../userTiming';
 
 const workerLog = scoped('worker');
 
+/** Worker-side span of one task execution, on this worker thread's 'tasks' track. */
+const measureRun = (taskId: string, messageId: number, t0: number, ok: boolean): void => {
+  const t1 = performance.now();
+  measureAtoll(`atoll run ${taskId}`, t0, t1, {
+    track: 'tasks',
+    color: ok ? 'secondary' : 'error',
+    properties: [['message', messageId], ['outcome', ok ? 'ok' : 'error']],
+    tooltipText: `${taskId}: ${(t1 - t0).toFixed(1)}ms in worker`,
+  });
+};
+
 let memoryInitialized = false;
 let wired = false;
 
@@ -42,11 +54,20 @@ export function installWorkerListener(): void {
     }
 
     if (data.type === 'INIT_MEMORY') {
-      const memory = data.memory as WebAssembly.Memory;
-      bindSharedMemories(memory.buffer as unknown as SharedArrayBuffer);
+      // `memory` is the pool-allocated WebAssembly.Memory; `buffer` is an
+      // existing SharedArrayBuffer the caller ships directly (sub-worker
+      // shell, second pool sharing a buffer).
+      const buffer =
+        (data.memory as WebAssembly.Memory | undefined)?.buffer ??
+        (data.buffer as SharedArrayBuffer | undefined);
+      if (!buffer) {
+        workerLog.warn('INIT_MEMORY arrived without a buffer — contracts stay unbound');
+        return;
+      }
+      bindSharedMemories(buffer as unknown as SharedArrayBuffer);
       memoryInitialized = true;
       if (data.devtools) enableWorkerDevtoolsForwarding();
-      workerLog.info(`shared memory initialized (${fmtBytes(memory.buffer.byteLength)})`);
+      workerLog.info(`shared memory initialized (${fmtBytes(buffer.byteLength)})`);
       return;
     }
 
@@ -62,9 +83,11 @@ export function installWorkerListener(): void {
       const t0 = performance.now();
       try {
         const result = await TaskRegistry.execute(taskId, ...(args || []));
+        if (devtoolsEnabled()) measureRun(taskId, messageId, t0, true);
         workerLog.debug(`task ${taskId} → ${(performance.now() - t0).toFixed(1)}ms`);
         self.postMessage({ messageId, success: true, result });
       } catch (err: any) {
+        if (devtoolsEnabled()) measureRun(taskId, messageId, t0, false);
         workerLog.warn(`task ${taskId} failed: ${err.message || String(err)}`);
         self.postMessage({ messageId, success: false, error: err.message || String(err) });
       }