fs: caller-supplied buffer for fs.readFile / fs.readFileSync #63600

fs.readFile* allocates a fresh Buffer on every call. Fine for most code, expensive on hot paths. Multiple Worker threads doing concurrent reads contend hard on the per-process mmap_lock in the kernel — about 17× longer wait per allocation than equivalent child processes (trace in #63597).

The workaround today is openSync + readSync + closeSync with your own buffer. Works, but you lose readFile's ergonomics, especially for the async variants.

Two small additions would close that gap.

{ buffer }

Pass a buffer to fill, get back a subarray view of the actual file bytes:

import fs from 'node:fs';
import fsp from 'node:fs/promises';

const buf = Buffer.allocUnsafe(1 << 20);

// sync
const data = fs.readFileSync(path, { buffer: buf });
// data === buf.subarray(0, fileSize)

// promise
const data2 = await fsp.readFile(path, { buffer: buf });

// callback
fs.readFile(path, { buffer: buf }, (err, data3) => { /* ... */ });

If the file is bigger than the buffer, throw. Same shape as crypto.randomFillSync(buf) vs crypto.randomBytes(n), or fs.read(fd, buf, ...) at the lower level.

{ getBuffer(size) }

Pass a factory called with the file's size (we already get it from fstat):

import fs from 'node:fs';
import fsp from 'node:fs/promises';

const opts = { getBuffer(size) { return pool.acquire(size); } };

const data  = fs.readFileSync(path, opts);
const data2 = await fsp.readFile(path, opts);
fs.readFile(path, opts, (err, data3) => { /* ... */ });

For pool implementations that want to pick the right slab once they know the size, instead of pre-allocating one giant buffer per concurrent caller.

getBuffer is synchronous in all variants. The async forms still benefit because the allocation step happens inline before the libuv read kicks off.

Why both

{ buffer } is for the simple case (one reusable buffer per worker or stream). { getBuffer } is for pool implementations. They compose:

buffer    → use it
getBuffer → call it
neither   → allocate (today's behaviour, unchanged)

Passing both throws.

Things to figure out

• encoding + buffer: I'd say return the string like today, treat the buffer as scratch.
• Pool release: leave to userland for v1. The caller can wrap the returned subarray however they want.

Implementation order would be readFileSync first, then fsPromises.readFile, then callback-style fs.readFile.

cc @nodejs/fs @nodejs/performance