Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

test(Markdown): time FR23 windows on the main thread's CPU clock (#8278)

Christopher Chedeau76d9634e3eef
diff --git a/.changeset/markdown-fr23-thread-clock.md b/.changeset/markdown-fr23-thread-clock.md
new file mode 100644
index 0000000000..a120341931
--- /dev/null
+++ b/.changeset/markdown-fr23-thread-clock.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Markdown's FR23 performance bench times each sampling window on the calling thread's CPU clock instead of the whole process's, so CPU spent by V8's background threads or a worker no longer counts toward either side. Test-only; `Markdown`'s behavior does not change.
+
+@vjeux
diff --git a/packages/core/src/Markdown/Markdown.fr23.bench.ts b/packages/core/src/Markdown/Markdown.fr23.bench.ts
index 819265672c..002f2d6114 100644
--- a/packages/core/src/Markdown/Markdown.fr23.bench.ts
+++ b/packages/core/src/Markdown/Markdown.fr23.bench.ts
@@ -16,7 +16,9 @@
* then nine alternating paired rounds averaging 20 iterations a side,
* reported as the median of the nine paired ratios — against the omitted
* baseline, for a stable list and a recreated equivalent one. Each ratio
- * comes from one sample, never a selection by the fastest baseline.
+ * comes from one sample, never a selection by the fastest baseline. Windows
+ * are timed on the main thread's CPU clock, so V8's background threads do not
+ * bill their work to whichever side happens to be running.
*
* The harness retries a fresh process only when the A/A control is invalid.
* A helper-overhead failure is never retried to obtain a passing sample.
diff --git a/packages/core/src/Markdown/Markdown.fr23.perf.test.ts b/packages/core/src/Markdown/Markdown.fr23.perf.test.ts
index 66ad28d7a1..6cb0599c12 100644
--- a/packages/core/src/Markdown/Markdown.fr23.perf.test.ts
+++ b/packages/core/src/Markdown/Markdown.fr23.perf.test.ts
@@ -19,7 +19,7 @@
* The timed region inside each process is the spec's protocol, unsmoothed:
* ten untimed warmups, then one median of nine alternating paired rounds,
* for a stable plugin list and a recreated equivalent one, against the
- * omitted baseline. A first attempt within budget on both paths certifies
+ * omitted baseline, timed on the main thread's CPU clock. A first attempt within budget on both paths certifies
* them. Otherwise up to nine fresh-process attempts decide each path on its
* own: a path fails the unchanged budget when a majority of the nine (five)
* exceed it, and collection stops as soon as both paths are decided.
@@ -27,10 +27,15 @@
import {execFileSync} from 'node:child_process';
import {mkdtempSync, rmSync, writeFileSync} from 'node:fs';
+import os from 'node:os';
import path from 'node:path';
import {fileURLToPath} from 'node:url';
+import {Worker} from 'node:worker_threads';
import {afterAll, describe, expect, it} from 'vitest';
-import {measureMarkdownPairedRatio} from './Markdown.fr23.sampling';
+import {
+ mainThreadCpuTime,
+ measureMarkdownPairedRatio,
+} from './Markdown.fr23.sampling';
interface BenchmarkResult {
readonly sections: number;
@@ -160,11 +165,17 @@ function runSettledBenchmark(sections: number): BenchmarkResult {
return measured;
}
+/**
+ * The ratios depend on the processor, so each line names it: a runner on a
+ * different CPU model shows up in the log rather than as an unexplained shift.
+ */
+const CPU_MODEL = os.cpus()[0]?.model.trim() ?? 'unknown CPU';
+
function logBenchmarkResult(result: BenchmarkResult, attempt: number): void {
console.log(
` ${result.sections} sections, attempt ${attempt}, FR23 representative set over empty:` +
` stable ${result.stable.toFixed(3)}, recreated ${result.recreated.toFixed(3)}` +
- ` (budget ${FR23_BUDGET}, A/A control ${result.control.toFixed(3)})`,
+ ` (budget ${FR23_BUDGET}, A/A control ${result.control.toFixed(3)}; ${CPU_MODEL})`,
);
}
@@ -266,6 +277,37 @@ describe('Markdown FR23 helper overhead', () => {
}
});
+ it("times only the main thread, not V8's or a worker's background threads", async () => {
+ // A worker spins for 300 ms of CPU while this thread sleeps without any.
+ // The process clock counts the worker's time; the sampling clock must not.
+ const flag = new Int32Array(new SharedArrayBuffer(4));
+ const processBefore = process.cpuUsage();
+ const threadBefore = mainThreadCpuTime();
+ const worker = new Worker(
+ `const {workerData} = require('node:worker_threads');
+ const end = Date.now() + 300;
+ while (Date.now() < end) {}
+ Atomics.store(workerData, 0, 1);
+ Atomics.notify(workerData, 0);`,
+ {eval: true, workerData: flag},
+ );
+ // A worker that dies before it finishes must fail the test, not hang it.
+ const deadline = Date.now() + 10_000;
+ while (Atomics.load(flag, 0) === 0) {
+ if (Date.now() > deadline) {
+ await worker.terminate();
+ throw new Error('The CPU-spinning worker did not finish in 10 s');
+ }
+ Atomics.wait(flag, 0, 0, 50);
+ }
+ const thread = mainThreadCpuTime() - threadBefore;
+ const processUsage = process.cpuUsage(processBefore);
+ await worker.terminate();
+ const processTime = processUsage.user + processUsage.system;
+ expect(processTime).toBeGreaterThan(200_000);
+ expect(thread).toBeLessThan(processTime / 4);
+ });
+
describe('deciding each path from fresh-process attempts', () => {
const result = (stable: number, recreated: number): BenchmarkResult => ({
sections: 500,
diff --git a/packages/core/src/Markdown/Markdown.fr23.sampling.ts b/packages/core/src/Markdown/Markdown.fr23.sampling.ts
index 462a10c903..da95620159 100644
--- a/packages/core/src/Markdown/Markdown.fr23.sampling.ts
+++ b/packages/core/src/Markdown/Markdown.fr23.sampling.ts
@@ -2,13 +2,22 @@
/**
* @file Markdown.fr23.sampling.ts
- * @input Baseline/candidate callbacks and a microsecond CPU clock
+ * @input Baseline/candidate callbacks and the main thread's microsecond CPU clock
* @output The FR23 paired-median ratio
* @position Test-only sampling for Markdown.fr23.bench.ts
*/
-function cpuTime(): number {
- const used = process.cpuUsage();
+/**
+ * CPU time of the calling thread, in microseconds: the time the measured call
+ * holds the JS thread, its own garbage-collection pauses included.
+ *
+ * Not `process.cpuUsage()`, which sums every thread of the process: V8's
+ * concurrent GC and compiler threads run during the timed windows, and their
+ * CPU lands in whichever window is open. At 500 sections that made even the
+ * A/A control (identical work on both sides) vary by up to 13 percent.
+ */
+export function mainThreadCpuTime(): number {
+ const used = process.threadCpuUsage();
return used.user + used.system;
}
@@ -20,7 +29,7 @@ function median(values: ReadonlyArray<number>): number {
export function measureMarkdownPairedRatio(
baseline: () => number,
candidate: () => number,
- now: () => number = cpuTime,
+ now: () => number = mainThreadCpuTime,
): number {
let sink = 0;
const average = (callback: () => number): number => {