GC pacing and the "unit of work" question for CLIs — some data

[VenkatKwest]

A few days ago Jarred posted that one of Bun's most impactful memory optimizations is scheduling GC when the HTTP server finishes sending a response body, and asked what the equivalent is for CLIs (https://x.com/jarredsumner/status/2076636361814364659). I went digging through the runtime and ran some benchmarks on canary to see how much of the answer already exists. Sharing both in case it's useful.

A framing: the exit ledger is already a unit-of-work ledger

A process stays alive exactly as long as something is pending: an in-flight fetch, a running subprocess, a timer, unread stdin. The event loop already tracks this set — it's how the runtime decides when it may exit. Every decrement of that set is one unit of work finishing. The server hook is the special case where the pending thing is a request (mod.rs — the GC check sits right next to pending_requests -= 1), and the fetch-completion hint from #34009 (FetchTasklet.rs) is the same case pointed the other direction.

Two things from the thread fall out of this framing instead of needing separate rules:

• GC at process exit being wasted (the OS reclaims everything) is the degenerate case: pending count at a local minimum = a decent time to collect; count at zero = exit = don't bother.
• The "GC after stdout flush" suggestion ("directionally good but people flush constantly") sorts itself out: a console.log that lands in the kernel buffer never touches the pending set, so it generates no signal. A write that actually hit backpressure holds a loop ref, and its drain is a real decrement.

The objection about the http-client version — "JS may still be executing" — is already answered by the shape of the mechanism in the tree: the completion sets a flag, and the heap is measured at the next event-loop park (GarbageCollectionController.rs), by which point the handler and its microtasks have run and the garbage exists to be seen.

What I measured

Two CLI-shaped loops on 1.4.0-canary.1+88403d981, Windows 11 x64:

• fetch loop: 100 sequential fetches of a 2 MB body from a local server (separate process), each body read as text and split into ~524k strings so the JS heap actually churns
• spawn loop: 40 sequential Bun.spawn subprocesses each writing 2 MB to stdout, consumed and split the same way

Each ran with the GC controller in its default state and with BUN_GC_TIMER_DISABLE=1, 3 runs per configuration after a discarded warmup. Peak RSS and peak heapStats().heapSize sampled every 5 ms plus at each iteration.

scenario	peak RSS (MB)	peak JS heap (MB)	wall (ms)
fetch, default	92.3–94.8	42.2–44.2	4666–5032
fetch, timer off	85.8–96.0	38.2–46.2	4753–4988
spawn, default	97.6–97.8	36.7, 36.7, 36.7	6201–6474
spawn, timer off	94.1–102.2	32.2–45.2	6217–7964

Three observations:

1. No wall-time cost. The distributions overlap in both scenarios. Whatever the controller spends, it hides in the parks.
2. No big peak reduction at this scale either. ~200 MB of total churn isn't enough to separate the peaks.
3. The reproducible effect is determinism. With the controller on, the spawn loop's peak JS heap was 36.7 MB in all three runs, to the decimal, and peak RSS varied by 0.2 MB. With it off, the heap peak swung between 32 and 45 MB run to run. At this scale the controller doesn't buy a lower peak — it buys the same peak every time. An old but precise data point says predictability is the metric to watch here: when Node removed its IdleNotification GC in 0.10 (2013), the release notes explained that "there are different degrees of 'idleness', and if you get it wrong, you can easily end up spending massive amounts of time collecting garbage when you'd least expect" — and what shipped was "latency is much more predictable and stable." That was a guessed signal being removed. A pending-set decrement is a real one, and it appears to buy the same predictability from the other direction.

Also worth noting: the spawn loop — which has no completion hint — was paced just as tightly as the fetch loop that has one, so the park-time checks appear to carry CLI workloads fine today.

Caveats

One machine, Windows, three runs per configuration, a microbenchmark with uniform garbage. The determinism observation was consistent across every run I did, but it deserves replication on other platforms and at larger scales. Scripts below.

benchmark scripts (4 files)

server.ts:

const buf = Buffer.alloc(2 * 1024 * 1024, "aaa,");
const server = Bun.serve({
  port: 0,
  fetch() {
    return new Response(buf);
  },
});
console.log(server.port);

fetch-bench.ts:

import { heapStats } from "bun:jsc";

const port = process.argv[2];
const url = `http://127.0.0.1:${port}/`;
const N = 100;

let peakRss = process.memoryUsage.rss();
let peakHeap = heapStats().heapSize;
function sample() {
  const r = process.memoryUsage.rss();
  if (r > peakRss) peakRss = r;
  const h = heapStats().heapSize;
  if (h > peakHeap) peakHeap = h;
}
const sampler = setInterval(sample, 5);

const t0 = performance.now();
for (let i = 0; i < N; i++) {
  const res = await fetch(url);
  const text = await res.text();
  const parts = text.split(",");
  if (parts.length < 100_000) throw new Error("bad body");
  sample();
}
const ms = performance.now() - t0;
clearInterval(sampler);

console.log(
  JSON.stringify({
    peakRssMB: +(peakRss / 1048576).toFixed(1),
    peakHeapMB: +(peakHeap / 1048576).toFixed(1),
    ms: Math.round(ms),
  }),
);

spawn-bench.ts:

import { heapStats } from "bun:jsc";

const N = 40;
const childCode = `const b=Buffer.alloc(2*1024*1024,'aaa,').toString();require('fs').writeSync(1,b);`;

let peakRss = process.memoryUsage.rss();
let peakHeap = heapStats().heapSize;
function sample() {
  const r = process.memoryUsage.rss();
  if (r > peakRss) peakRss = r;
  const h = heapStats().heapSize;
  if (h > peakHeap) peakHeap = h;
}
const sampler = setInterval(sample, 5);

const t0 = performance.now();
for (let i = 0; i < N; i++) {
  const proc = Bun.spawn({
    cmd: [process.execPath, "-e", childCode],
    stdout: "pipe",
    stderr: "ignore",
    stdin: "ignore",
  });
  const [text] = await Promise.all([proc.stdout.text(), proc.exited]);
  const parts = text.split(",");
  if (parts.length < 100_000) throw new Error("bad output");
  sample();
}
const ms = performance.now() - t0;
clearInterval(sampler);

console.log(
  JSON.stringify({
    peakRssMB: +(peakRss / 1048576).toFixed(1),
    peakHeapMB: +(peakHeap / 1048576).toFixed(1),
    ms: Math.round(ms),
  }),
);

run-bench.ts:

const bun = process.execPath;
const dir = import.meta.dir;

const server = Bun.spawn({
  cmd: [bun, `${dir}/server.ts`],
  stdout: "pipe",
  stderr: "inherit",
});
const reader = server.stdout.getReader();
const { value } = await reader.read();
reader.releaseLock();
const port = new TextDecoder().decode(value).trim();

async function run(script: string, env: Record<string, string | undefined>) {
  const proc = Bun.spawn({
    cmd: [bun, `${dir}/${script}`, port],
    env: { ...process.env, ...env },
    stdout: "pipe",
    stderr: "inherit",
  });
  const out = await proc.stdout.text();
  const code = await proc.exited;
  if (code !== 0) throw new Error(`${script} exited ${code}`);
  return JSON.parse(out.trim());
}

try {
  for (const [name, script] of [
    ["fetch", "fetch-bench.ts"],
    ["spawn", "spawn-bench.ts"],
  ] as const) {
    for (const [mode, env] of [
      ["gc-controller-ON ", {}],
      ["gc-controller-OFF", { BUN_GC_TIMER_DISABLE: "1" }],
    ] as const) {
      await run(script, env); // discarded warmup
      const runs = [];
      for (let i = 0; i < 3; i++) runs.push(await run(script, env));
      console.log(name, mode, JSON.stringify(runs));
    }
  }
} finally {
  server.kill();
}