buffer: increase Buffer.poolSize default to 64 KiB

[mcollina]

The Buffer.poolSize default of 8 KiB has been unchanged since May 2015. Two issues with it today:

1. The 4 KiB cliff. The pool check is size < (Buffer.poolSize >>> 1), so with the 8 KiB default the threshold is 4 KiB and the strict inequality means a 4 KiB allocation itself bypasses the pool. The current default helps allocations from 1 B to 3999 B and abruptly stops at the page-aligned and HTTP-frame-sized boundary where many real allocations land.

2. Stale in 2025. Predates HTTP/2 (16 KiB-1 MiB frame sizes), modern stream chunk sizes, and ~10× growth in typical RAM. Many Buffer.allocUnsafe calls in core (fs.readFileSync for non-utf8 reads, HTTP parser, stream chunkers) sit in the 4-64 KiB range and miss the pool.

This PR raises the default to 64 KiB, extending pool coverage to allocations up to ~32 KiB.

Evidence

Benchmark setup: 8 Worker threads in one process, each looping fs.readFileSync(file) on files of various sizes, measuring throughput. Linux 6.8, glibc 2.39, i7-7700, Node main (built locally).

File size	8 KiB pool (default)	64 KiB pool	Δ
512 B	404k ops/s	431k ops/s	+7%
2 KiB	360k ops/s	367k ops/s	~
4 KiB	326k ops/s	360k ops/s	+10%
8 KiB	202k ops/s	254k ops/s	+26%
16 KiB	148k ops/s	181k ops/s	+23%
64 KiB	86k ops/s	87k ops/s	~
1 MiB	12k ops/s	12k ops/s	~

Wins where it matters (4-32 KiB), no regressions at small or large sizes.

Why workers benefit more than single-threaded

Buffer.allocUnsafe(size) for size ≥ Buffer.poolSize/2 falls through to fresh V8 ArrayBuffer allocations, which land on glibc malloc. When multiple Worker threads do this concurrently they contend on the per-mm_struct mmap_lock write lock (every arena growth takes it). Confirmed by bpftrace: workers wait ~17× longer per mmap_lock acquisition than equivalent child processes on the same workload, with cumulative wait dropping ~2.5× when the pool covers the allocation size. Full investigation: https://github.com/platformatic/node-worker-mmap-lock-contention.

Single-threaded apps benefit too, just less dramatically — fewer allocator round-trips for medium-sized buffers.

Cost

+56 KiB RSS per realm at startup (one 64 KiB pool per realm; main thread + each Worker thread). On a typical app with 1 main + 4 Workers that's +280 KiB, trivial on modern hardware. The pool occupies RSS for the lifetime of any sliced Buffer that's still referenced, so peak RSS may grow modestly in apps that hold many small Buffers; same shape as today, just larger granularity.

Why 64 KiB and not larger

Tested 32 / 64 / 128 / 256 KiB; 64 KiB is the smallest pool that captures the 4-16 KiB hot zone where the current default fails. 128/256 KiB give additional wins on 16-64 KiB allocations (+64% at 16 KiB with a 256 KiB pool) but the marginal RSS cost is harder to justify as a default. Easy follow-up if there's appetite.

Pool refills at 64 KiB stay under glibc's M_MMAP_THRESHOLD (128 KiB default), so each refill uses the heap rather than triggering a fresh mmap — that boundary is part of why 64 KiB is the right ceiling for a default.

Notes

• Doc updated in doc/api/buffer.md (default value + the "4 KiB" example reference).
• No code change other than the constant; the existing Buffer.poolSize setter machinery is unchanged.
• Filed as draft for discussion of the value (64 KiB vs 128 KiB) and to surface any concerns about RSS in memory-constrained deployments (Lambda, embedded).

cc @nodejs/buffer @nodejs/performance

[ronag]

Yes!

[mertcanaltin]

SGTM. I'm wondering how close the performance at 32 KiB is to 64 KiB, and whether larger allocations are actually harmful here.

[mcollina]

SGTM. I'm wondering how close the performance at 32 KiB is to 64 KiB, and whether larger allocations are actually harmful here.

There is little to no drawback to increase this up to 256KB on my tests, but 8->256KB seemed jumping over a few too many steps.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/73780/

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.32%. Comparing base (8257091) to head (3aa77e7).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #63597      +/-   ##
==========================================
- Coverage   90.32%   90.32%   -0.01%     
==========================================
  Files         730      730              
  Lines      234671   234671              
  Branches    43946    43955       +9     
==========================================
- Hits       211965   211960       -5     
- Misses      14423    14426       +3     
- Partials     8283     8285       +2     

Files with missing lines	Coverage Δ
lib/buffer.js	99.11% <100.00%> (-0.07%)	⬇️

... and 31 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[LiviaMedeiros]

64 KiB sounds reasonable.

The value is adjustable so users who know they have enough RAM and benefit from bigger pool can do it on their end. Maybe worth adding example to the docs as followup, i think something like --import 'data:text/javascript,Buffer.poolSize=0x100000;' should do the trick for them?

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/73792/

[nodejs-github-bot]

Landed in dbec31c

[Renegade334]

notable-change PRs with changes that should be highlighted in changelogs. ?