@ac-bench/measure-duration 0.1.0

package/dist/_pool.js

@@ -0,0 +1,219 @@
+import { poolRandomEffects, sumBy, } from "@ac-kit/math-stats";
+import * as z from "zod/mini";
+import { summarise } from "./_statistics.js";
+/**
+ * Normal quantile for a two-sided 95% interval, matching what `summarise`
+ * reports.
+ */
+const Z_95_ = 1.959964;
+export const pooledEstimateSchema = z.object({
+    /** The answer: every execution's estimate, weighted by its precision. */
+    estimateMs: z.number(),
+    lowerMs: z.number(),
+    upperMs: z.number(),
+    /** Between-process variance, τ². The process lottery, quantified. */
+    betweenVarianceMs2: z.number(),
+    /** Share of total variance that is between processes rather than within. */
+    heterogeneity: z.number(),
+    /** How many executions were combined. */
+    executions: z.number(),
+    /** Which of the reported statistics was pooled. */
+    estimator: z.enum(["mean", "median"]),
+});
+export const contaminationSchema = z.object({
+    /** Shared-arm estimate minus isolated-arm estimate, in milliseconds. */
+    differenceMs: z.number(),
+    /** As a fraction of the isolated estimate. */
+    share: z.number(),
+    /** Executions behind each side. */
+    sharedExecutions: z.number(),
+    isolatedExecutions: z.number(),
+});
+/**
+ * Combines every execution of one case into the result that answers for it.
+ *
+ * Executions come from different processes, and a process contributes an offset
+ * of its own — GC seed, address-space layout, which JIT tier the code settled
+ * in, the thermal state at that moment. Averaging the estimates would report an
+ * interval far too narrow, because it would treat that offset as if it did not
+ * exist. Random-effects pooling estimates it instead and widens the interval by
+ * it.
+ *
+ * The pooled interval is symmetric by construction, which is inverse-variance
+ * pooling's assumption rather than a property of the samples: a skewed median
+ * interval is symmetrised on the way in.
+ *
+ * @param executions At least one, in no particular order.
+ * @param estimator Which reported statistic to pool.
+ * @returns The pooled result, or the sole execution's own result when there is
+ *   only one.
+ */
+export function poolDurationExecutions(executions, estimator = "median") {
+    const measured = executions.filter((execution) => execution.result.statistics !== null);
+    // Every execution failed, or there was only ever one: nothing to combine, and
+    // inventing a pooled number over a single group would only look authoritative.
+    if (measured.length === 0) {
+        return executions[0].result;
+    }
+    if (measured.length === 1) {
+        return measured[0].result;
+    }
+    const groups = measured.map((execution) => ({
+        estimate: estimate_(execution.result, estimator),
+        variance: variance_(execution.result, estimator),
+    }));
+    // A clock too coarse to separate the samples leaves nothing to weight by.
+    if (groups.some((group) => group.variance <= 0)) {
+        return mergeSamples_(measured, estimator, null, null);
+    }
+    const pooled = poolRandomEffects(groups);
+    return mergeSamples_(measured, estimator, {
+        estimateMs: pooled.estimate,
+        lowerMs: pooled.interval.lower,
+        upperMs: pooled.interval.upper,
+        betweenVarianceMs2: pooled.betweenVariance,
+        heterogeneity: pooled.heterogeneity,
+        executions: measured.length,
+        estimator,
+    }, contamination_(measured, estimator));
+}
+/**
+ * Builds the pooled result on the concatenated samples.
+ *
+ * The reported `statistics` describe every sample from every execution, so the
+ * spread they show includes the between-process spread rather than one lucky
+ * process's view of it. `estimate` carries the properly weighted answer.
+ */
+function mergeSamples_(executions, estimator, estimate, contamination) {
+    const first = executions[0].result;
+    const timings = executions.flatMap((execution) => execution.result.timings);
+    return {
+        ...first,
+        statistics: timings.length > 0 ? summarise(timings) : first.statistics,
+        timings,
+        sampling: mergeSampling_(executions, estimate),
+        estimate,
+        contamination,
+        warnings: dedupeWarnings_(executions),
+    };
+}
+/**
+ * One report describing every execution.
+ *
+ * Carrying the first execution's report unchanged would state one process's
+ * sample count and precision next to statistics covering all of them.
+ */
+function mergeSampling_(executions, estimate) {
+    const reports = executions
+        .map((execution) => execution.result.sampling)
+        .filter((report) => report !== null);
+    const first = reports[0];
+    if (first === undefined) {
+        return null;
+    }
+    const stopReasons = new Set(reports.map((report) => report.stopReason));
+    const achieved = estimate === null ? null : pooledRelativeError_(estimate);
+    return {
+        ...first,
+        // A claim about precision is the weakest link: one precise replicate must
+        // not cover for four sloppy ones.
+        targetReached: reports.every((report) => report.targetReached),
+        achievedRelativeError: achieved ?? first.achievedRelativeError,
+        stopReason: stopReasons.size === 1 ? first.stopReason : "mixed",
+        measuredMs: sumBy(reports, (report) => report.measuredMs),
+        activeMs: sumBy(reports, (report) => report.activeMs),
+        elapsedMs: sumBy(reports, (report) => report.elapsedMs),
+        samples: sumBy(reports, (report) => report.samples),
+        batches: sumBy(reports, (report) => report.batches),
+    };
+}
+/** Half-width of the pooled interval, relative to the pooled estimate. */
+function pooledRelativeError_(estimate) {
+    if (estimate.estimateMs <= 0) {
+        return null;
+    }
+    return (estimate.upperMs - estimate.lowerMs) / 2 / estimate.estimateMs;
+}
+/**
+ * One warning per kind, with how many executions raised it.
+ *
+ * Keying on the message would keep all of them: each quotes its own numbers, so
+ * eight executions produce eight distinct texts saying the same thing. The
+ * retained message is one execution's, and the count is what says whether the
+ * finding was systematic or a one-off.
+ */
+function dedupeWarnings_(executions) {
+    const byKind = new Map();
+    for (const execution of executions) {
+        for (const warning of execution.result.warnings) {
+            const existing = byKind.get(warning.kind);
+            if (existing === undefined) {
+                byKind.set(warning.kind, { warning, seen: 1 });
+                continue;
+            }
+            existing.seen += 1;
+        }
+    }
+    const total = executions.length;
+    return [...byKind.values()].map(({ warning, seen }) => seen === 1 && total === 1
+        ? warning
+        : {
+            ...warning,
+            message: `${warning.message} (in ${seen} of ${total} executions)`,
+        });
+}
+/**
+ * How much slower a case runs alongside its siblings than alone.
+ *
+ * `null` unless both arms ran: with one arm there is nothing to compare, and a
+ * difference of an estimate against itself is zero by construction rather than
+ * by measurement.
+ */
+function contamination_(executions, estimator) {
+    const shared = executions.filter((execution) => execution.arm === "shared");
+    const isolated = executions.filter((execution) => execution.arm === "isolated");
+    if (shared.length === 0 || isolated.length === 0) {
+        return null;
+    }
+    const sharedMs = meanEstimate_(shared, estimator);
+    const isolatedMs = meanEstimate_(isolated, estimator);
+    return {
+        differenceMs: sharedMs - isolatedMs,
+        share: isolatedMs > 0 ? (sharedMs - isolatedMs) / isolatedMs : 0,
+        sharedExecutions: shared.length,
+        isolatedExecutions: isolated.length,
+    };
+}
+function meanEstimate_(executions, estimator) {
+    const total = executions.reduce((sum, execution) => sum + estimate_(execution.result, estimator), 0);
+    return total / executions.length;
+}
+function estimate_(result, estimator) {
+    const statistics = result.statistics;
+    return estimator === "mean" ? statistics.meanMs : statistics.medianMs;
+}
+/**
+ * Variance of the estimate, from the interval the sampler already reports.
+ *
+ * `halfWidth = z · σ`, so `σ² = (halfWidth / z)²` — exact for the mean's normal
+ * approximation, and the closest honest reading of the median's
+ * distribution-free interval.
+ */
+function variance_(result, estimator) {
+    const statistics = result.statistics;
+    const halfWidth = estimator === "mean"
+        ? statistics.confidence95Ms
+        : statistics.medianConfidence95Ms;
+    return (halfWidth / Z_95_) ** 2;
+}
+/** An interval a reader can quote, from the pooled estimate. */
+export function pooledInterval(estimate) {
+    return {
+        estimate: estimate.estimateMs,
+        lower: estimate.lowerMs,
+        upper: estimate.upperMs,
+        halfWidth: (estimate.upperMs - estimate.lowerMs) / 2,
+        level: 0.95,
+    };
+}
+//# sourceMappingURL=_pool.js.map

package/dist/_pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_pool.js","sourceRoot":"","sources":["../src/_pool.ts"],"names":[],"mappings":"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"}

package/dist/_process-execution.d.ts

@@ -0,0 +1,62 @@
+import * as z from "zod/mini";
+/**
+ * Wall-clock breakdown of one cold start, reported by the spawned process.
+ *
+ * A total plus an exit code is enough to compare two cold starts but not to say
+ * where the time went, which is the only actionable part of a slow one.
+ */
+export declare const coldStartPhasesSchema: z.ZodMiniObject<{
+    startupMs: z.ZodMiniNumber<number>;
+    importMs: z.ZodMiniNumber<number>;
+    runMs: z.ZodMiniNumber<number>;
+}, z.core.$strip>;
+export type ColdStartPhases = z.infer<typeof coldStartPhasesSchema>;
+export type IterationOutcome = {
+    readonly wallMs: number;
+    readonly exitCode: number | null;
+    readonly terminatedBy: string | null;
+    /** Last {@link STDERR_TAIL_BYTES_} bytes of stderr, empty when it wrote none. */
+    readonly stderrTail: string;
+    /** `null` unless phases were requested and the process reported them. */
+    readonly phases: ColdStartPhases | null;
+};
+export type SpawnIterationOptions = {
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    /** Reads one JSON line of {@link ColdStartPhases} from stdout. */
+    readonly capturePhases?: boolean;
+};
+/**
+ * Owns every process spawned for a case, and guarantees none outlives it.
+ *
+ * Killing a process does not kill its children on POSIX: a hung grandchild is
+ * reparented to init and survives the whole run, holding a port or a lock, with
+ * nothing left pointing at it. Each iteration is therefore started `detached`,
+ * which makes `terminate`/`kill` address its whole process group.
+ */
+export declare class ProcessGroup {
+    private readonly live;
+    private readonly onProcessExit;
+    private disposed;
+    constructor();
+    /**
+     * Spawns one iteration and resolves when it has exited.
+     *
+     * @param command Executable, resolved on `PATH`. Never passed through a
+     *   shell.
+     * @param args Arguments, passed as a vector rather than a command line.
+     * @param options Working directory, environment and phase capture.
+     * @param signal Aborting tears the whole group down.
+     * @returns What the process cost and how it ended.
+     * @throws {Error} If the executable cannot be started at all.
+     */
+    run(command: string, args: readonly string[], options: SpawnIterationOptions, signal: AbortSignal): Promise<IterationOutcome>;
+    /**
+     * Terminates every process still running, escalating only if it has to.
+     *
+     * @returns Once the group is gone, or once it has been killed outright for
+     *   failing to leave within the grace period.
+     */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=_process-execution.d.ts.map

package/dist/_process-execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_process-execution.d.ts","sourceRoot":"","sources":["../src/_process-execution.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAQ9B;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;iBAUhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,MAAM,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,kEAAkE;IAClE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAI5B;IAEF,OAAO,CAAC,QAAQ,CAAS;IAEzB,cAIC;IAED;;;;;;;;;;OAUG;IACG,GAAG,CACR,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,WAAW,GACjB,OAAO,CAAC,gBAAgB,CAAC,CAuC3B;IAED;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAW7B;CACD"}

package/dist/_process-execution.js

@@ -0,0 +1,142 @@
+import { startProcess } from "@ac-kit/node";
+import * as z from "zod/mini";
+/** Grace given to a `SIGTERM` before the group is killed outright. */
+const TERMINATE_GRACE_MS_ = 2000;
+/** Bytes of stderr retained per iteration for failure diagnostics. */
+const STDERR_TAIL_BYTES_ = 4096;
+/**
+ * Wall-clock breakdown of one cold start, reported by the spawned process.
+ *
+ * A total plus an exit code is enough to compare two cold starts but not to say
+ * where the time went, which is the only actionable part of a slow one.
+ */
+export const coldStartPhasesSchema = z.object({
+    /**
+     * Interpreter start-up, before any user code: `bootstrapComplete -
+     * nodeStart`.
+     */
+    startupMs: z.number(),
+    /** Importing the bench file and everything it pulls in. */
+    importMs: z.number(),
+    /** The case body's single call. */
+    runMs: z.number(),
+});
+/**
+ * Owns every process spawned for a case, and guarantees none outlives it.
+ *
+ * Killing a process does not kill its children on POSIX: a hung grandchild is
+ * reparented to init and survives the whole run, holding a port or a lock, with
+ * nothing left pointing at it. Each iteration is therefore started `detached`,
+ * which makes `terminate`/`kill` address its whole process group.
+ */
+export class ProcessGroup {
+    live = new Set();
+    onProcessExit = () => {
+        for (const child of this.live) {
+            child.kill("SIGKILL");
+        }
+    };
+    disposed = false;
+    constructor() {
+        // Last resort: the owning process is going away and async teardown will
+        // never get a turn.
+        process.on("exit", this.onProcessExit);
+    }
+    /**
+     * Spawns one iteration and resolves when it has exited.
+     *
+     * @param command Executable, resolved on `PATH`. Never passed through a
+     *   shell.
+     * @param args Arguments, passed as a vector rather than a command line.
+     * @param options Working directory, environment and phase capture.
+     * @param signal Aborting tears the whole group down.
+     * @returns What the process cost and how it ended.
+     * @throws {Error} If the executable cannot be started at all.
+     */
+    async run(command, args, options, signal) {
+        signal.throwIfAborted();
+        const child = await startProcess(command, args, {
+            // Group leader, so teardown reaches whatever the iteration spawned.
+            detached: process.platform !== "win32",
+            stdout: options.capturePhases === true ? "pipe" : "ignore",
+            stderr: "pipe",
+            cwd: options.cwd,
+            env: options.env === undefined ? undefined : { ...options.env },
+            graceMs: TERMINATE_GRACE_MS_,
+        });
+        this.live.add(child);
+        const stderr = collectTail_(child.stderr);
+        const stdout = options.capturePhases === true ? collectTail_(child.stdout) : null;
+        // Straight to `SIGKILL`: an aborted run is not waiting out a grace period.
+        const onAbort = () => {
+            child.kill("SIGKILL");
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        try {
+            const exit = await child.waitForExit();
+            return {
+                wallMs: exit.durationMs,
+                exitCode: exit.code,
+                terminatedBy: exit.signal,
+                stderrTail: await stderr,
+                phases: stdout === null ? null : parsePhases_(await stdout),
+            };
+        }
+        finally {
+            signal.removeEventListener("abort", onAbort);
+            this.live.delete(child);
+        }
+    }
+    /**
+     * Terminates every process still running, escalating only if it has to.
+     *
+     * @returns Once the group is gone, or once it has been killed outright for
+     *   failing to leave within the grace period.
+     */
+    async dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        process.off("exit", this.onProcessExit);
+        await Promise.all([...this.live].map((child) => child.terminate(TERMINATE_GRACE_MS_)));
+    }
+}
+/**
+ * Drains a stream to its end, keeping only the tail.
+ *
+ * Draining is not optional: an unread pipe fills and blocks the writer, which
+ * would show up as a mysteriously slow iteration rather than as a deadlock.
+ */
+async function collectTail_(stream) {
+    if (stream === null) {
+        return "";
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of stream) {
+        const buffer = Buffer.from(chunk);
+        chunks.push(buffer);
+        size += buffer.length;
+        while (chunks.length > 1 &&
+            size - (chunks[0]?.length ?? 0) >= STDERR_TAIL_BYTES_) {
+            size -= chunks.shift()?.length ?? 0;
+        }
+    }
+    return Buffer.concat(chunks).subarray(-STDERR_TAIL_BYTES_).toString("utf8");
+}
+/** @returns The reported phases, or `null` when the process reported none. */
+function parsePhases_(stdout) {
+    const line = stdout.trimEnd().split("\n").at(-1);
+    if (line === undefined || line === "") {
+        return null;
+    }
+    try {
+        return coldStartPhasesSchema.parse(JSON.parse(line));
+    }
+    catch {
+        // A case that writes its own output to stdout is not an error.
+        return null;
+    }
+}
+//# sourceMappingURL=_process-execution.js.map

package/dist/_process-execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_process-execution.js","sourceRoot":"","sources":["../src/_process-execution.ts"],"names":[],"mappings":"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"}

package/dist/_run-case.d.ts

@@ -0,0 +1,32 @@
+import { BenchCaseRunContext } from "@ac-bench/core/runner";
+import { DurationCaseRunFn } from "./decl.js";
+import { DurationCaseOptions, DurationCommandCaseOptions, DurationConditionOptions } from "./options.js";
+export type DurationRunCaseOptions = DurationCaseOptions & {
+    conditionOptions?: DurationConditionOptions;
+    /** Set by `durationCommandCase`; the case body is then a formality. */
+    commandCase?: {
+        readonly command: string;
+        readonly args: readonly string[];
+        readonly options: DurationCommandCaseOptions | undefined;
+    };
+};
+/**
+ * Runs one benchmark case under the adaptive sampler.
+ *
+ * The loop belongs to the sampler: it decides how many samples to take next and
+ * when the interval around the estimate is tight enough. What happens here is
+ * only the measuring — the timed span is `performance.now()` immediately around
+ * one iteration and nothing else, so hooks, statistics and reporting stay
+ * outside the number being reported.
+ *
+ * An iteration is one call in this process, one fresh process running this same
+ * case body, or one execution of an external program. All three go through the
+ * same loop and the same stopping rule; only what an iteration _is_ differs.
+ *
+ * @param title Case name, carried into the reported result.
+ * @param runFn The work to measure.
+ * @param context Run context, used to report the result and check for abort.
+ * @param options Sampling policy and execution mode.
+ */
+export declare function runDurationCase(title: string, runFn: DurationCaseRunFn, context: BenchCaseRunContext, options?: DurationRunCaseOptions): Promise<void>;
+//# sourceMappingURL=_run-case.d.ts.map

package/dist/_run-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_run-case.d.ts","sourceRoot":"","sources":["../src/_run-case.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,mBAAmB,EAGnB,MAAM,uBAAuB,CAAC;AA8B/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EACN,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,GAAG;IAC1D,gBAAgB,CAAC,EAAE,wBAAwB,CAAC;IAC5C,uEAAuE;IACvE,WAAW,CAAC,EAAE;QACb,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;QACjC,QAAQ,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,CAAC;KACzD,CAAC;CACF,CAAC;AAKF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,eAAe,CACpC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAiRf"}