buffer: support aligned allocations

Add an optional `alignment` argument to `Buffer.allocUnsafe()` and
`Buffer.allocUnsafeSlow()`, which guarantees that the memory backing the
returned buffer starts at an address that is a multiple of `alignment`.
Some operating system interfaces refuse to work with unaligned memory.
The motivating case is unbuffered ("direct") file I/O: a read or write
on a descriptor opened with `O_DIRECT` fails with `EINVAL` unless the
buffer address is a multiple of the logical block size of the underlying
device. Until now there was no way to obtain such a buffer from JS,
since the address of a backing store can neither be observed nor chosen.
Alignment is also worth having purely for performance, for instance to
keep a hot buffer from straddling one more cache line than its size
requires.
V8 does not allow picking the address of a backing store, so alignment
is instead achieved by over-allocating `alignment - 1` bytes and
positioning the buffer at the first suitably aligned byte within them.
The new `arrayBufferAlignedOffset()` binding computes that offset.
Addresses are not stable across snapshot serialization, so the binding
reports no padding while a snapshot is being built. Otherwise the
snapshot would capture where this particular process happened to
allocate and stop being reproducible. Buffers restored from a snapshot
are consequently not aligned; the pool works around this by recreating
itself in a deserialize callback.
The `Buffer.allocUnsafe()` pool is now aligned to a cache line itself,
which lets pooled allocations satisfy any alignment up to 64 bytes by
padding their offset into the pool rather than allocating separately.
Assisted-by: Claude/Opus 5
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Robert Nagy <ronagy@icloud.com>
PR-URL: #65003
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>

Author: 2 people

doc/api/buffer.md

@@ -791,11 +791,14 @@ data that might not have been allocated for `Buffer`s.
 
 A `TypeError` will be thrown if `size` is not a number.
 
-### Static method: `Buffer.allocUnsafe(size)`
+### Static method: `Buffer.allocUnsafe(size[, alignment])`
 
 <!-- YAML
 added: v5.10.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -810,6 +813,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -865,11 +871,14 @@ pool, while `Buffer.allocUnsafe(size).fill(fill)` _will_ use the internal
 difference is subtle but can be important when an application requires the
 additional performance that [`Buffer.allocUnsafe()`][] provides.
 
-### Static method: `Buffer.allocUnsafeSlow(size)`
+### Static method: `Buffer.allocUnsafeSlow(size[, alignment])`
 
 <!-- YAML
 added: v5.12.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -881,6 +890,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -5608,16 +5620,92 @@ While there are clear performance advantages to using
 [`Buffer.allocUnsafe()`][], extra care _must_ be taken in order to avoid
 introducing security vulnerabilities into an application.
 
+### Aligned allocations
+
+Some operating system interfaces require the memory they operate on to be
+aligned, and on some hardware alignment is merely faster. The most common
+example of the former is unbuffered ("direct") file I/O, which on Linux requires
+the buffer address, the file offset and the transfer length to all be multiples
+of the logical block size of the underlying device:
+
+```mjs
+import { open } from'node:fs/promises';
+import { constants } from'node:fs';
+import { Buffer } from'node:buffer';
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constfile=awaitopen('/dev/sda', constants.O_RDONLY|constants.O_DIRECT);
+try {
+awaitfile.read(buf, 0, blockSize, 0);
+} finally {
+awaitfile.close();
+}
+```
+
+```cjs
+constfs=require('node:fs');
+const { Buffer } =require('node:buffer');
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constflags=fs.constants.O_RDONLY|fs.constants.O_DIRECT;
+fs.open('/dev/sda', flags, (err, fd) => {
+if (err) throw err;
+fs.read(fd, buf, 0, blockSize, 0, (err) => {
+fs.close(fd, () => {});
+if (err) throw err;
+ });
+});
+```
+
+Alignment can also be worth requesting purely for performance, even when no
+interface demands it. Aligning a hot `Buffer` to the cache line size (64 bytes on
+most contemporary CPUs) keeps it from straddling one more cache line than it
+needs to, so that a small structure is fetched with one cache miss instead of
+two, and page-aligned (4096 bytes) allocations similarly help interfaces that map
+or pin memory. These are micro-optimizations: measure before reaching for them,
+since the extra bytes are not free.
+
+Because the address of a `Buffer`'s memory cannot be chosen directly, extra bytes
+have to be allocated or skipped to reach an aligned address.
+[`Buffer.allocUnsafeSlow()`][] over-allocates up to `alignment - 1` bytes and
+positions the returned `Buffer` at the first suitably aligned byte within them.
+[`Buffer.allocUnsafe()`][] instead pads its offset into the shared internal pool,
+whose start is always aligned to 64 bytes, and only falls back to an allocation
+of its own when `alignment` is larger than that. Either way,
+[`buf.byteOffset`][] is usually not 0 and [`buf.buffer`][] is larger than `size`,
+so code that reaches past the `Buffer` into its underlying `ArrayBuffer` must
+take the offset into account, as it must for pooled `Buffer`s.
+
+The alignment is a property of the returned `Buffer` and is preserved for its
+whole lifetime, but it is not inherited by other views: [`buf.subarray`][],
+[`buf.slice()`][] and `structuredClone()` may all produce unaligned `Buffer`s.
+
+Alignment also does not survive being captured in a startup snapshot: memory does
+not keep its address across serialization, so a `Buffer` allocated while
+[`--build-snapshot`][] is in effect is not aligned in the deserialized process.
+Allocate inside a [`v8.startupSnapshot.setDeserializeMainFunction()`][] callback,
+or after startup, if the alignment has to hold at run time.
+
 [ASCII]: https://en.wikipedia.org/wiki/ASCII
+[Aligned allocations]: #aligned-allocations
 [Base64]: https://en.wikipedia.org/wiki/Base64
 [ISO-8859-1]: https://en.wikipedia.org/wiki/ISO-8859-1
 [RFC 4648, Section 5]: https://tools.ietf.org/html/rfc4648#section-5
 [UTF-16]: https://en.wikipedia.org/wiki/UTF-16
 [UTF-8]: https://en.wikipedia.org/wiki/UTF-8
 [WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/
+[`--build-snapshot`]: cli.md#--build-snapshot
 [`Buffer.alloc()`]: #static-method-bufferallocsize-fill-encoding
-[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize
-[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize-alignment
+[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.concat()`]: #static-method-bufferconcatlist-totallength
 [`Buffer.copyBytesFrom()`]: #static-method-buffercopybytesfromview-offset-length
 [`Buffer.from(array)`]: #static-method-bufferfromarray
@@ -5639,6 +5727,7 @@ introducing security vulnerabilities into an application.
 [`TypedArray.prototype.subarray()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray
 [`blob.stream()`]: #blobstream
 [`buf.buffer`]: #bufbuffer
+[`buf.byteOffset`]: #bufbyteoffset
 [`buf.compare()`]: #bufcomparetarget-targetstart-targetend-sourcestart-sourceend
 [`buf.entries()`]: #bufentries
 [`buf.fill()`]: #buffillvalue-offset-end-encoding
@@ -5653,6 +5742,7 @@ introducing security vulnerabilities into an application.
 [`buffer.constants.MAX_STRING_LENGTH`]: #bufferconstantsmax_string_length
 [`buffer.kMaxLength`]: #bufferkmaxlength
 [`util.inspect()`]: util.md#utilinspectobject-options
+[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
 [`v8::Uint8Array::kMaxLength`]: https://v8.github.io/api/head/classv8_1_1Uint8Array.html#a7677e3d0c9c92e4d40bef7212f5980c6
 [base64url]: https://tools.ietf.org/html/rfc4648#section-5
 [endianness]: https://en.wikipedia.org/wiki/Endianness

doc/api/deprecations.md

@@ -4624,7 +4624,7 @@ will throw an error in a future version.
 [`--pending-deprecation`]: cli.md#--pending-deprecation
 [`--throw-deprecation`]: cli.md#--throw-deprecation
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
-[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.from(array)`]: buffer.md#static-method-bufferfromarray
 [`Buffer.from(buffer)`]: buffer.md#static-method-bufferfrombuffer
 [`Buffer.isBuffer()`]: buffer.md#static-method-bufferisbufferobj
@@ -4770,7 +4770,7 @@ will throw an error in a future version.
 [`writable.writableLength`]: stream.md#writablewritablelength
 [`zlib.bytesWritten`]: zlib.md#zlibbyteswritten
 [alloc]: buffer.md#static-method-bufferallocsize-fill-encoding
-[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize
+[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize-alignment
 [caveats of asynchronous customization hooks]: module.md#caveats-of-asynchronous-customization-hooks
 [from_arraybuffer]: buffer.md#static-method-bufferfromarraybuffer-byteoffset-length
 [from_string_encoding]: buffer.md#static-method-bufferfromstring-encoding

doc/api/worker_threads.md

@@ -2234,7 +2234,7 @@ thread spawned will spawn another until the application crashes.
 [`--max-old-space-size`]:cli.md#--max-old-space-sizesize-in-mib
 [`--max-semi-space-size`]:cli.md#--max-semi-space-sizesize-in-mib
 [`AsyncResource`]:async_hooks.md#class-asyncresource
-[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize
+[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize-alignment
 [`ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST`]:errors.md#err_missing_message_port_in_transfer_list
 [`ERR_WORKER_MESSAGING_ERRORED`]:errors.md#err_worker_messaging_errored
 [`ERR_WORKER_MESSAGING_FAILED`]:errors.md#err_worker_messaging_failed

lib/buffer.js

@@ -140,6 +140,7 @@ const {
  markAsUntransferable,
  addBufferPrototypeMethods,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  asciiWrite,
  latin1Write,
  utf8Write,
@@ -171,13 +172,27 @@ const constants = ObjectDefineProperties({}, {
 },
 });
 
+// The largest alignment accepted by `Buffer.allocUnsafeSlow()`. Any plausible
+// I/O alignment requirement (logical block size, memory page size, huge page
+// size) is well below this.
+constkMaxAlignment=2**30;
+
+// Slices handed out of the pool are 8 byte aligned relative to the start of the
+// pool, so aligning the pool itself to a cache line keeps them from straddling
+// one more cache line than their size requires.
+constkPoolAlignment=64;
+
 Buffer.poolSize=64*1024;
-letpoolSize,poolOffset,allocPool,allocBuffer;
+// `poolOffset` is relative to `poolBase`, which is where the pool starts inside
+// `allocPool`. The pool is over-allocated to be able to align it, so `poolBase`
+// is not necessarily 0.
+letpoolSize,poolOffset,poolBase,allocPool,allocBuffer;
 
 functioncreatePool(){
 poolSize=Buffer.poolSize;
-allocBuffer=createUnsafeBuffer(poolSize);
+allocBuffer=createUnsafeAlignedBuffer(poolSize,kPoolAlignment);
 allocPool=allocBuffer.buffer;
+poolBase=TypedArrayPrototypeGetByteOffset(allocBuffer);
 markAsUntransferable(allocPool);
 poolOffset=0;
 }
@@ -444,40 +459,92 @@ Buffer.alloc = function alloc(size, fill, encoding) {
 /**
  * Equivalent to Buffer(num), by default creates a non-zero-filled Buffer
  * instance. If `--zero-fill-buffers` is set, will zero-fill the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`. See `Buffer.allocUnsafeSlow()`.
+ * @param {number} size
+ * @param {number} [alignment] A power of two, at most 2 ** 30
  * @returns {FastBuffer}
  */
-Buffer.allocUnsafe=functionallocUnsafe(size){
+Buffer.allocUnsafe=functionallocUnsafe(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returnallocate(size);
+if(alignment===undefined){
+returnallocate(size);
+}
+validateAlignment(size,alignment);
+returnallocateAligned(size,alignment);
 };
 
 /**
  * By default creates a non-zero-filled Buffer instance that is not allocated
  * off the pre-initialized pool. If `--zero-fill-buffers` is set, will zero-fill
  * the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`, which is required by e.g. reads
+ * and writes on file descriptors opened with `O_DIRECT`. Note that up to
+ * `alignment - 1` extra bytes are allocated to satisfy the request, and that
+ * the returned buffer's `byteOffset` is therefore usually non-zero.
  * @param {number} size
- * @returns {FastBuffer|undefined}
+ * @param {number} [alignment] A power of two, at most 2 ** 30
+ * @returns {FastBuffer}
  */
-Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size){
+Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returncreateUnsafeBuffer(size);
+if(alignment===undefined){
+returncreateUnsafeBuffer(size);
+}
+validateAlignment(size,alignment);
+returncreateUnsafeAlignedBuffer(size,alignment);
 };
 
+functionvalidateAlignment(size,alignment){
+validateInteger(alignment,'alignment',1,kMaxAlignment);
+if((alignment&(alignment-1))!==0){
+thrownewERR_INVALID_ARG_VALUE(
+'alignment',alignment,'must be a power of two');
+}
+// Satisfying the alignment costs up to `alignment - 1` extra bytes.
+if(size>kMaxLength-(alignment-1)){
+thrownewERR_OUT_OF_RANGE(
+'size',`<= ${kMaxLength-(alignment-1)}`,size);
+}
+}
+
 functionallocate(size){
 if(size<=0){
 returnnewFastBuffer();
 }
 if(size<(Buffer.poolSize>>>1)){
 if(size>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,size);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
 poolOffset+=size;
 alignPool();
 returnb;
 }
 returncreateUnsafeBuffer(size);
 }
 
+functionallocateAligned(size,alignment){
+if(size<=0){
+returnnewFastBuffer();
+}
+// The pool starts at a `kPoolAlignment` aligned address, so any alignment up
+// to that can be satisfied by padding the offset into the pool. Stricter
+// alignments need an allocation of their own.
+if(alignment>kPoolAlignment||size>=(Buffer.poolSize>>>1)){
+returncreateUnsafeAlignedBuffer(size,alignment);
+}
+poolOffset=(poolOffset+alignment-1)&~(alignment-1);
+if(size>(poolSize-poolOffset))
+createPool();
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
+poolOffset+=size;
+alignPool();
+returnb;
+}
+
 functionfromStringFast(string,ops){
 constmaxLength=Buffer.poolSize>>>1;
 
@@ -498,7 +565,7 @@ function fromStringFast(string, ops) {
 createPool();
 
 constactual=ops.write(allocBuffer,string,poolOffset,length);
-constb=newFastBuffer(allocPool,poolOffset,actual);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,actual);
 
 poolOffset+=actual;
 alignPool();
@@ -560,7 +627,7 @@ function fromArrayLike(obj) {
 if(length<(Buffer.poolSize>>>1)){
 if(length>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,length);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,length);
 TypedArrayPrototypeSet(b,obj,0);
 poolOffset+=length;
 alignPool();

lib/internal/buffer.js

@@ -33,6 +33,7 @@ const {
  hexWrite,
  ucs2Write,
  utf8WriteStatic,
+ arrayBufferAlignedOffset,
  createUnsafeArrayBuffer,
  setDetachKey,
 }=internalBinding('buffer');
@@ -1104,12 +1105,28 @@ function createUnsafeBuffer(size) {
 returnnewFastBuffer(createUnsafeArrayBuffer(size));
 }
 
+// Returns an uninitialized buffer of `size` bytes whose first byte is located at
+// a memory address that is a multiple of `alignment`. `alignment` must be a
+// power of two, and `size + alignment - 1` must not exceed the maximum buffer
+// length. Since the address of a backing store cannot be chosen, `alignment - 1`
+// extra bytes are allocated and skipped, which leaves the returned buffer with a
+// non-zero `byteOffset` into a larger ArrayBuffer.
+functioncreateUnsafeAlignedBuffer(size,alignment){
+if(size===0){
+returnnewFastBuffer();
+}
+
+constab=createUnsafeArrayBuffer(size+alignment-1);
+returnnewFastBuffer(ab,arrayBufferAlignedOffset(ab,alignment),size);
+}
+
 module.exports={
  FastBuffer,
  addBufferPrototypeMethods,
  markAsUntransferable,
  isMarkedAsUntransferable,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  readUInt16BE,
  readUInt32BE,
  asciiWrite,

doc/api/buffer.md

@@ -791,11 +791,14 @@ data that might not have been allocated for `Buffer`s.
 
 A `TypeError` will be thrown if `size` is not a number.
 
-### Static method: `Buffer.allocUnsafe(size)`
+### Static method: `Buffer.allocUnsafe(size[, alignment])`
 
 <!-- YAML
 added: v5.10.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -810,6 +813,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -865,11 +871,14 @@ pool, while `Buffer.allocUnsafe(size).fill(fill)` _will_ use the internal
 difference is subtle but can be important when an application requires the
 additional performance that [`Buffer.allocUnsafe()`][] provides.
 
-### Static method: `Buffer.allocUnsafeSlow(size)`
+### Static method: `Buffer.allocUnsafeSlow(size[, alignment])`
 
 <!-- YAML
 added: v5.12.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -881,6 +890,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -5608,16 +5620,92 @@ While there are clear performance advantages to using
 [`Buffer.allocUnsafe()`][], extra care _must_ be taken in order to avoid
 introducing security vulnerabilities into an application.
 
+### Aligned allocations
+
+Some operating system interfaces require the memory they operate on to be
+aligned, and on some hardware alignment is merely faster. The most common
+example of the former is unbuffered ("direct") file I/O, which on Linux requires
+the buffer address, the file offset and the transfer length to all be multiples
+of the logical block size of the underlying device:
+
+```mjs
+import { open } from'node:fs/promises';
+import { constants } from'node:fs';
+import { Buffer } from'node:buffer';
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constfile=awaitopen('/dev/sda', constants.O_RDONLY|constants.O_DIRECT);
+try {
+awaitfile.read(buf, 0, blockSize, 0);
+} finally {
+awaitfile.close();
+}
+```
+
+```cjs
+constfs=require('node:fs');
+const { Buffer } =require('node:buffer');
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constflags=fs.constants.O_RDONLY|fs.constants.O_DIRECT;
+fs.open('/dev/sda', flags, (err, fd) => {
+if (err) throw err;
+fs.read(fd, buf, 0, blockSize, 0, (err) => {
+fs.close(fd, () => {});
+if (err) throw err;
+ });
+});
+```
+
+Alignment can also be worth requesting purely for performance, even when no
+interface demands it. Aligning a hot `Buffer` to the cache line size (64 bytes on
+most contemporary CPUs) keeps it from straddling one more cache line than it
+needs to, so that a small structure is fetched with one cache miss instead of
+two, and page-aligned (4096 bytes) allocations similarly help interfaces that map
+or pin memory. These are micro-optimizations: measure before reaching for them,
+since the extra bytes are not free.
+
+Because the address of a `Buffer`'s memory cannot be chosen directly, extra bytes
+have to be allocated or skipped to reach an aligned address.
+[`Buffer.allocUnsafeSlow()`][] over-allocates up to `alignment - 1` bytes and
+positions the returned `Buffer` at the first suitably aligned byte within them.
+[`Buffer.allocUnsafe()`][] instead pads its offset into the shared internal pool,
+whose start is always aligned to 64 bytes, and only falls back to an allocation
+of its own when `alignment` is larger than that. Either way,
+[`buf.byteOffset`][] is usually not 0 and [`buf.buffer`][] is larger than `size`,
+so code that reaches past the `Buffer` into its underlying `ArrayBuffer` must
+take the offset into account, as it must for pooled `Buffer`s.
+
+The alignment is a property of the returned `Buffer` and is preserved for its
+whole lifetime, but it is not inherited by other views: [`buf.subarray`][],
+[`buf.slice()`][] and `structuredClone()` may all produce unaligned `Buffer`s.
+
+Alignment also does not survive being captured in a startup snapshot: memory does
+not keep its address across serialization, so a `Buffer` allocated while
+[`--build-snapshot`][] is in effect is not aligned in the deserialized process.
+Allocate inside a [`v8.startupSnapshot.setDeserializeMainFunction()`][] callback,
+or after startup, if the alignment has to hold at run time.
+
 [ASCII]: https://en.wikipedia.org/wiki/ASCII
+[Aligned allocations]: #aligned-allocations
 [Base64]: https://en.wikipedia.org/wiki/Base64
 [ISO-8859-1]: https://en.wikipedia.org/wiki/ISO-8859-1
 [RFC 4648, Section 5]: https://tools.ietf.org/html/rfc4648#section-5
 [UTF-16]: https://en.wikipedia.org/wiki/UTF-16
 [UTF-8]: https://en.wikipedia.org/wiki/UTF-8
 [WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/
+[`--build-snapshot`]: cli.md#--build-snapshot
 [`Buffer.alloc()`]: #static-method-bufferallocsize-fill-encoding
-[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize
-[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize-alignment
+[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.concat()`]: #static-method-bufferconcatlist-totallength
 [`Buffer.copyBytesFrom()`]: #static-method-buffercopybytesfromview-offset-length
 [`Buffer.from(array)`]: #static-method-bufferfromarray
@@ -5639,6 +5727,7 @@ introducing security vulnerabilities into an application.
 [`TypedArray.prototype.subarray()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray
 [`blob.stream()`]: #blobstream
 [`buf.buffer`]: #bufbuffer
+[`buf.byteOffset`]: #bufbyteoffset
 [`buf.compare()`]: #bufcomparetarget-targetstart-targetend-sourcestart-sourceend
 [`buf.entries()`]: #bufentries
 [`buf.fill()`]: #buffillvalue-offset-end-encoding
@@ -5653,6 +5742,7 @@ introducing security vulnerabilities into an application.
 [`buffer.constants.MAX_STRING_LENGTH`]: #bufferconstantsmax_string_length
 [`buffer.kMaxLength`]: #bufferkmaxlength
 [`util.inspect()`]: util.md#utilinspectobject-options
+[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
 [`v8::Uint8Array::kMaxLength`]: https://v8.github.io/api/head/classv8_1_1Uint8Array.html#a7677e3d0c9c92e4d40bef7212f5980c6
 [base64url]: https://tools.ietf.org/html/rfc4648#section-5
 [endianness]: https://en.wikipedia.org/wiki/Endianness

doc/api/deprecations.md

@@ -4624,7 +4624,7 @@ will throw an error in a future version.
 [`--pending-deprecation`]: cli.md#--pending-deprecation
 [`--throw-deprecation`]: cli.md#--throw-deprecation
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
-[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.from(array)`]: buffer.md#static-method-bufferfromarray
 [`Buffer.from(buffer)`]: buffer.md#static-method-bufferfrombuffer
 [`Buffer.isBuffer()`]: buffer.md#static-method-bufferisbufferobj
@@ -4770,7 +4770,7 @@ will throw an error in a future version.
 [`writable.writableLength`]: stream.md#writablewritablelength
 [`zlib.bytesWritten`]: zlib.md#zlibbyteswritten
 [alloc]: buffer.md#static-method-bufferallocsize-fill-encoding
-[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize
+[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize-alignment
 [caveats of asynchronous customization hooks]: module.md#caveats-of-asynchronous-customization-hooks
 [from_arraybuffer]: buffer.md#static-method-bufferfromarraybuffer-byteoffset-length
 [from_string_encoding]: buffer.md#static-method-bufferfromstring-encoding

doc/api/worker_threads.md

@@ -2234,7 +2234,7 @@ thread spawned will spawn another until the application crashes.
 [`--max-old-space-size`]:cli.md#--max-old-space-sizesize-in-mib
 [`--max-semi-space-size`]:cli.md#--max-semi-space-sizesize-in-mib
 [`AsyncResource`]:async_hooks.md#class-asyncresource
-[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize
+[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize-alignment
 [`ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST`]:errors.md#err_missing_message_port_in_transfer_list
 [`ERR_WORKER_MESSAGING_ERRORED`]:errors.md#err_worker_messaging_errored
 [`ERR_WORKER_MESSAGING_FAILED`]:errors.md#err_worker_messaging_failed

lib/buffer.js

@@ -140,6 +140,7 @@ const {
  markAsUntransferable,
  addBufferPrototypeMethods,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  asciiWrite,
  latin1Write,
  utf8Write,
@@ -171,13 +172,27 @@ const constants = ObjectDefineProperties({}, {
 },
 });
 
+// The largest alignment accepted by `Buffer.allocUnsafeSlow()`. Any plausible
+// I/O alignment requirement (logical block size, memory page size, huge page
+// size) is well below this.
+constkMaxAlignment=2**30;
+
+// Slices handed out of the pool are 8 byte aligned relative to the start of the
+// pool, so aligning the pool itself to a cache line keeps them from straddling
+// one more cache line than their size requires.
+constkPoolAlignment=64;
+
 Buffer.poolSize=64*1024;
-letpoolSize,poolOffset,allocPool,allocBuffer;
+// `poolOffset` is relative to `poolBase`, which is where the pool starts inside
+// `allocPool`. The pool is over-allocated to be able to align it, so `poolBase`
+// is not necessarily 0.
+letpoolSize,poolOffset,poolBase,allocPool,allocBuffer;
 
 functioncreatePool(){
 poolSize=Buffer.poolSize;
-allocBuffer=createUnsafeBuffer(poolSize);
+allocBuffer=createUnsafeAlignedBuffer(poolSize,kPoolAlignment);
 allocPool=allocBuffer.buffer;
+poolBase=TypedArrayPrototypeGetByteOffset(allocBuffer);
 markAsUntransferable(allocPool);
 poolOffset=0;
 }
@@ -444,40 +459,92 @@ Buffer.alloc = function alloc(size, fill, encoding) {
 /**
  * Equivalent to Buffer(num), by default creates a non-zero-filled Buffer
  * instance. If `--zero-fill-buffers` is set, will zero-fill the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`. See `Buffer.allocUnsafeSlow()`.
+ * @param {number} size
+ * @param {number} [alignment] A power of two, at most 2 ** 30
  * @returns {FastBuffer}
  */
-Buffer.allocUnsafe=functionallocUnsafe(size){
+Buffer.allocUnsafe=functionallocUnsafe(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returnallocate(size);
+if(alignment===undefined){
+returnallocate(size);
+}
+validateAlignment(size,alignment);
+returnallocateAligned(size,alignment);
 };
 
 /**
  * By default creates a non-zero-filled Buffer instance that is not allocated
  * off the pre-initialized pool. If `--zero-fill-buffers` is set, will zero-fill
  * the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`, which is required by e.g. reads
+ * and writes on file descriptors opened with `O_DIRECT`. Note that up to
+ * `alignment - 1` extra bytes are allocated to satisfy the request, and that
+ * the returned buffer's `byteOffset` is therefore usually non-zero.
  * @param {number} size
- * @returns {FastBuffer|undefined}
+ * @param {number} [alignment] A power of two, at most 2 ** 30
+ * @returns {FastBuffer}
  */
-Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size){
+Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returncreateUnsafeBuffer(size);
+if(alignment===undefined){
+returncreateUnsafeBuffer(size);
+}
+validateAlignment(size,alignment);
+returncreateUnsafeAlignedBuffer(size,alignment);
 };
 
+functionvalidateAlignment(size,alignment){
+validateInteger(alignment,'alignment',1,kMaxAlignment);
+if((alignment&(alignment-1))!==0){
+thrownewERR_INVALID_ARG_VALUE(
+'alignment',alignment,'must be a power of two');
+}
+// Satisfying the alignment costs up to `alignment - 1` extra bytes.
+if(size>kMaxLength-(alignment-1)){
+thrownewERR_OUT_OF_RANGE(
+'size',`<= ${kMaxLength-(alignment-1)}`,size);
+}
+}
+
 functionallocate(size){
 if(size<=0){
 returnnewFastBuffer();
 }
 if(size<(Buffer.poolSize>>>1)){
 if(size>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,size);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
 poolOffset+=size;
 alignPool();
 returnb;
 }
 returncreateUnsafeBuffer(size);
 }
 
+functionallocateAligned(size,alignment){
+if(size<=0){
+returnnewFastBuffer();
+}
+// The pool starts at a `kPoolAlignment` aligned address, so any alignment up
+// to that can be satisfied by padding the offset into the pool. Stricter
+// alignments need an allocation of their own.
+if(alignment>kPoolAlignment||size>=(Buffer.poolSize>>>1)){
+returncreateUnsafeAlignedBuffer(size,alignment);
+}
+poolOffset=(poolOffset+alignment-1)&~(alignment-1);
+if(size>(poolSize-poolOffset))
+createPool();
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
+poolOffset+=size;
+alignPool();
+returnb;
+}
+
 functionfromStringFast(string,ops){
 constmaxLength=Buffer.poolSize>>>1;
 
@@ -498,7 +565,7 @@ function fromStringFast(string, ops) {
 createPool();
 
 constactual=ops.write(allocBuffer,string,poolOffset,length);
-constb=newFastBuffer(allocPool,poolOffset,actual);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,actual);
 
 poolOffset+=actual;
 alignPool();
@@ -560,7 +627,7 @@ function fromArrayLike(obj) {
 if(length<(Buffer.poolSize>>>1)){
 if(length>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,length);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,length);
 TypedArrayPrototypeSet(b,obj,0);
 poolOffset+=length;
 alignPool();

lib/internal/buffer.js

@@ -33,6 +33,7 @@ const {
  hexWrite,
  ucs2Write,
  utf8WriteStatic,
+ arrayBufferAlignedOffset,
  createUnsafeArrayBuffer,
  setDetachKey,
 }=internalBinding('buffer');
@@ -1104,12 +1105,28 @@ function createUnsafeBuffer(size) {
 returnnewFastBuffer(createUnsafeArrayBuffer(size));
 }
 
+// Returns an uninitialized buffer of `size` bytes whose first byte is located at
+// a memory address that is a multiple of `alignment`. `alignment` must be a
+// power of two, and `size + alignment - 1` must not exceed the maximum buffer
+// length. Since the address of a backing store cannot be chosen, `alignment - 1`
+// extra bytes are allocated and skipped, which leaves the returned buffer with a
+// non-zero `byteOffset` into a larger ArrayBuffer.
+functioncreateUnsafeAlignedBuffer(size,alignment){
+if(size===0){
+returnnewFastBuffer();
+}
+
+constab=createUnsafeArrayBuffer(size+alignment-1);
+returnnewFastBuffer(ab,arrayBufferAlignedOffset(ab,alignment),size);
+}
+
 module.exports={
  FastBuffer,
  addBufferPrototypeMethods,
  markAsUntransferable,
  isMarkedAsUntransferable,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  readUInt16BE,
  readUInt32BE,
  asciiWrite,

doc/api/buffer.md

@@ -791,11 +791,14 @@ data that might not have been allocated for `Buffer`s.
 
 A `TypeError` will be thrown if `size` is not a number.
 
-### Static method: `Buffer.allocUnsafe(size)`
+### Static method: `Buffer.allocUnsafe(size[, alignment])`
 
 <!-- YAML
 added: v5.10.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -810,6 +813,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -865,11 +871,14 @@ pool, while `Buffer.allocUnsafe(size).fill(fill)` _will_ use the internal
 difference is subtle but can be important when an application requires the
 additional performance that [`Buffer.allocUnsafe()`][] provides.
 
-### Static method: `Buffer.allocUnsafeSlow(size)`
+### Static method: `Buffer.allocUnsafeSlow(size[, alignment])`
 
 <!-- YAML
 added: v5.12.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -881,6 +890,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -5608,16 +5620,92 @@ While there are clear performance advantages to using
 [`Buffer.allocUnsafe()`][], extra care _must_ be taken in order to avoid
 introducing security vulnerabilities into an application.
 
+### Aligned allocations
+
+Some operating system interfaces require the memory they operate on to be
+aligned, and on some hardware alignment is merely faster. The most common
+example of the former is unbuffered ("direct") file I/O, which on Linux requires
+the buffer address, the file offset and the transfer length to all be multiples
+of the logical block size of the underlying device:
+
+```mjs
+import { open } from'node:fs/promises';
+import { constants } from'node:fs';
+import { Buffer } from'node:buffer';
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constfile=awaitopen('/dev/sda', constants.O_RDONLY|constants.O_DIRECT);
+try {
+awaitfile.read(buf, 0, blockSize, 0);
+} finally {
+awaitfile.close();
+}
+```
+
+```cjs
+constfs=require('node:fs');
+const { Buffer } =require('node:buffer');
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constflags=fs.constants.O_RDONLY|fs.constants.O_DIRECT;
+fs.open('/dev/sda', flags, (err, fd) => {
+if (err) throw err;
+fs.read(fd, buf, 0, blockSize, 0, (err) => {
+fs.close(fd, () => {});
+if (err) throw err;
+ });
+});
+```
+
+Alignment can also be worth requesting purely for performance, even when no
+interface demands it. Aligning a hot `Buffer` to the cache line size (64 bytes on
+most contemporary CPUs) keeps it from straddling one more cache line than it
+needs to, so that a small structure is fetched with one cache miss instead of
+two, and page-aligned (4096 bytes) allocations similarly help interfaces that map
+or pin memory. These are micro-optimizations: measure before reaching for them,
+since the extra bytes are not free.
+
+Because the address of a `Buffer`'s memory cannot be chosen directly, extra bytes
+have to be allocated or skipped to reach an aligned address.
+[`Buffer.allocUnsafeSlow()`][] over-allocates up to `alignment - 1` bytes and
+positions the returned `Buffer` at the first suitably aligned byte within them.
+[`Buffer.allocUnsafe()`][] instead pads its offset into the shared internal pool,
+whose start is always aligned to 64 bytes, and only falls back to an allocation
+of its own when `alignment` is larger than that. Either way,
+[`buf.byteOffset`][] is usually not 0 and [`buf.buffer`][] is larger than `size`,
+so code that reaches past the `Buffer` into its underlying `ArrayBuffer` must
+take the offset into account, as it must for pooled `Buffer`s.
+
+The alignment is a property of the returned `Buffer` and is preserved for its
+whole lifetime, but it is not inherited by other views: [`buf.subarray`][],
+[`buf.slice()`][] and `structuredClone()` may all produce unaligned `Buffer`s.
+
+Alignment also does not survive being captured in a startup snapshot: memory does
+not keep its address across serialization, so a `Buffer` allocated while
+[`--build-snapshot`][] is in effect is not aligned in the deserialized process.
+Allocate inside a [`v8.startupSnapshot.setDeserializeMainFunction()`][] callback,
+or after startup, if the alignment has to hold at run time.
+
 [ASCII]: https://en.wikipedia.org/wiki/ASCII
+[Aligned allocations]: #aligned-allocations
 [Base64]: https://en.wikipedia.org/wiki/Base64
 [ISO-8859-1]: https://en.wikipedia.org/wiki/ISO-8859-1
 [RFC 4648, Section 5]: https://tools.ietf.org/html/rfc4648#section-5
 [UTF-16]: https://en.wikipedia.org/wiki/UTF-16
 [UTF-8]: https://en.wikipedia.org/wiki/UTF-8
 [WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/
+[`--build-snapshot`]: cli.md#--build-snapshot
 [`Buffer.alloc()`]: #static-method-bufferallocsize-fill-encoding
-[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize
-[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize-alignment
+[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.concat()`]: #static-method-bufferconcatlist-totallength
 [`Buffer.copyBytesFrom()`]: #static-method-buffercopybytesfromview-offset-length
 [`Buffer.from(array)`]: #static-method-bufferfromarray
@@ -5639,6 +5727,7 @@ introducing security vulnerabilities into an application.
 [`TypedArray.prototype.subarray()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray
 [`blob.stream()`]: #blobstream
 [`buf.buffer`]: #bufbuffer
+[`buf.byteOffset`]: #bufbyteoffset
 [`buf.compare()`]: #bufcomparetarget-targetstart-targetend-sourcestart-sourceend
 [`buf.entries()`]: #bufentries
 [`buf.fill()`]: #buffillvalue-offset-end-encoding
@@ -5653,6 +5742,7 @@ introducing security vulnerabilities into an application.
 [`buffer.constants.MAX_STRING_LENGTH`]: #bufferconstantsmax_string_length
 [`buffer.kMaxLength`]: #bufferkmaxlength
 [`util.inspect()`]: util.md#utilinspectobject-options
+[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
 [`v8::Uint8Array::kMaxLength`]: https://v8.github.io/api/head/classv8_1_1Uint8Array.html#a7677e3d0c9c92e4d40bef7212f5980c6
 [base64url]: https://tools.ietf.org/html/rfc4648#section-5
 [endianness]: https://en.wikipedia.org/wiki/Endianness

doc/api/deprecations.md

@@ -4624,7 +4624,7 @@ will throw an error in a future version.
 [`--pending-deprecation`]: cli.md#--pending-deprecation
 [`--throw-deprecation`]: cli.md#--throw-deprecation
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
-[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.from(array)`]: buffer.md#static-method-bufferfromarray
 [`Buffer.from(buffer)`]: buffer.md#static-method-bufferfrombuffer
 [`Buffer.isBuffer()`]: buffer.md#static-method-bufferisbufferobj
@@ -4770,7 +4770,7 @@ will throw an error in a future version.
 [`writable.writableLength`]: stream.md#writablewritablelength
 [`zlib.bytesWritten`]: zlib.md#zlibbyteswritten
 [alloc]: buffer.md#static-method-bufferallocsize-fill-encoding
-[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize
+[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize-alignment
 [caveats of asynchronous customization hooks]: module.md#caveats-of-asynchronous-customization-hooks
 [from_arraybuffer]: buffer.md#static-method-bufferfromarraybuffer-byteoffset-length
 [from_string_encoding]: buffer.md#static-method-bufferfromstring-encoding

doc/api/worker_threads.md

@@ -2234,7 +2234,7 @@ thread spawned will spawn another until the application crashes.
 [`--max-old-space-size`]:cli.md#--max-old-space-sizesize-in-mib
 [`--max-semi-space-size`]:cli.md#--max-semi-space-sizesize-in-mib
 [`AsyncResource`]:async_hooks.md#class-asyncresource
-[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize
+[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize-alignment
 [`ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST`]:errors.md#err_missing_message_port_in_transfer_list
 [`ERR_WORKER_MESSAGING_ERRORED`]:errors.md#err_worker_messaging_errored
 [`ERR_WORKER_MESSAGING_FAILED`]:errors.md#err_worker_messaging_failed

lib/buffer.js

@@ -140,6 +140,7 @@ const {
  markAsUntransferable,
  addBufferPrototypeMethods,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  asciiWrite,
  latin1Write,
  utf8Write,
@@ -171,13 +172,27 @@ const constants = ObjectDefineProperties({}, {
 },
 });
 
+// The largest alignment accepted by `Buffer.allocUnsafeSlow()`. Any plausible
+// I/O alignment requirement (logical block size, memory page size, huge page
+// size) is well below this.
+constkMaxAlignment=2**30;
+
+// Slices handed out of the pool are 8 byte aligned relative to the start of the
+// pool, so aligning the pool itself to a cache line keeps them from straddling
+// one more cache line than their size requires.
+constkPoolAlignment=64;
+
 Buffer.poolSize=64*1024;
-letpoolSize,poolOffset,allocPool,allocBuffer;
+// `poolOffset` is relative to `poolBase`, which is where the pool starts inside
+// `allocPool`. The pool is over-allocated to be able to align it, so `poolBase`
+// is not necessarily 0.
+letpoolSize,poolOffset,poolBase,allocPool,allocBuffer;
 
 functioncreatePool(){
 poolSize=Buffer.poolSize;
-allocBuffer=createUnsafeBuffer(poolSize);
+allocBuffer=createUnsafeAlignedBuffer(poolSize,kPoolAlignment);
 allocPool=allocBuffer.buffer;
+poolBase=TypedArrayPrototypeGetByteOffset(allocBuffer);
 markAsUntransferable(allocPool);
 poolOffset=0;
 }
@@ -444,40 +459,92 @@ Buffer.alloc = function alloc(size, fill, encoding) {
 /**
  * Equivalent to Buffer(num), by default creates a non-zero-filled Buffer
  * instance. If `--zero-fill-buffers` is set, will zero-fill the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`. See `Buffer.allocUnsafeSlow()`.
+ * @param {number} size
+ * @param {number} [alignment] A power of two, at most 2 ** 30
  * @returns {FastBuffer}
  */
-Buffer.allocUnsafe=functionallocUnsafe(size){
+Buffer.allocUnsafe=functionallocUnsafe(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returnallocate(size);
+if(alignment===undefined){
+returnallocate(size);
+}
+validateAlignment(size,alignment);
+returnallocateAligned(size,alignment);
 };
 
 /**
  * By default creates a non-zero-filled Buffer instance that is not allocated
  * off the pre-initialized pool. If `--zero-fill-buffers` is set, will zero-fill
  * the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`, which is required by e.g. reads
+ * and writes on file descriptors opened with `O_DIRECT`. Note that up to
+ * `alignment - 1` extra bytes are allocated to satisfy the request, and that
+ * the returned buffer's `byteOffset` is therefore usually non-zero.
  * @param {number} size
- * @returns {FastBuffer|undefined}
+ * @param {number} [alignment] A power of two, at most 2 ** 30
+ * @returns {FastBuffer}
  */
-Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size){
+Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returncreateUnsafeBuffer(size);
+if(alignment===undefined){
+returncreateUnsafeBuffer(size);
+}
+validateAlignment(size,alignment);
+returncreateUnsafeAlignedBuffer(size,alignment);
 };
 
+functionvalidateAlignment(size,alignment){
+validateInteger(alignment,'alignment',1,kMaxAlignment);
+if((alignment&(alignment-1))!==0){
+thrownewERR_INVALID_ARG_VALUE(
+'alignment',alignment,'must be a power of two');
+}
+// Satisfying the alignment costs up to `alignment - 1` extra bytes.
+if(size>kMaxLength-(alignment-1)){
+thrownewERR_OUT_OF_RANGE(
+'size',`<= ${kMaxLength-(alignment-1)}`,size);
+}
+}
+
 functionallocate(size){
 if(size<=0){
 returnnewFastBuffer();
 }
 if(size<(Buffer.poolSize>>>1)){
 if(size>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,size);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
 poolOffset+=size;
 alignPool();
 returnb;
 }
 returncreateUnsafeBuffer(size);
 }
 
+functionallocateAligned(size,alignment){
+if(size<=0){
+returnnewFastBuffer();
+}
+// The pool starts at a `kPoolAlignment` aligned address, so any alignment up
+// to that can be satisfied by padding the offset into the pool. Stricter
+// alignments need an allocation of their own.
+if(alignment>kPoolAlignment||size>=(Buffer.poolSize>>>1)){
+returncreateUnsafeAlignedBuffer(size,alignment);
+}
+poolOffset=(poolOffset+alignment-1)&~(alignment-1);
+if(size>(poolSize-poolOffset))
+createPool();
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
+poolOffset+=size;
+alignPool();
+returnb;
+}
+
 functionfromStringFast(string,ops){
 constmaxLength=Buffer.poolSize>>>1;
 
@@ -498,7 +565,7 @@ function fromStringFast(string, ops) {
 createPool();
 
 constactual=ops.write(allocBuffer,string,poolOffset,length);
-constb=newFastBuffer(allocPool,poolOffset,actual);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,actual);
 
 poolOffset+=actual;
 alignPool();
@@ -560,7 +627,7 @@ function fromArrayLike(obj) {
 if(length<(Buffer.poolSize>>>1)){
 if(length>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,length);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,length);
 TypedArrayPrototypeSet(b,obj,0);
 poolOffset+=length;
 alignPool();

lib/internal/buffer.js

@@ -33,6 +33,7 @@ const {
  hexWrite,
  ucs2Write,
  utf8WriteStatic,
+ arrayBufferAlignedOffset,
  createUnsafeArrayBuffer,
  setDetachKey,
 }=internalBinding('buffer');
@@ -1104,12 +1105,28 @@ function createUnsafeBuffer(size) {
 returnnewFastBuffer(createUnsafeArrayBuffer(size));
 }
 
+// Returns an uninitialized buffer of `size` bytes whose first byte is located at
+// a memory address that is a multiple of `alignment`. `alignment` must be a
+// power of two, and `size + alignment - 1` must not exceed the maximum buffer
+// length. Since the address of a backing store cannot be chosen, `alignment - 1`
+// extra bytes are allocated and skipped, which leaves the returned buffer with a
+// non-zero `byteOffset` into a larger ArrayBuffer.
+functioncreateUnsafeAlignedBuffer(size,alignment){
+if(size===0){
+returnnewFastBuffer();
+}
+
+constab=createUnsafeArrayBuffer(size+alignment-1);
+returnnewFastBuffer(ab,arrayBufferAlignedOffset(ab,alignment),size);
+}
+
 module.exports={
  FastBuffer,
  addBufferPrototypeMethods,
  markAsUntransferable,
  isMarkedAsUntransferable,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  readUInt16BE,
  readUInt32BE,
  asciiWrite,

doc/api/buffer.md

@@ -791,11 +791,14 @@ data that might not have been allocated for `Buffer`s.
 
 A `TypeError` will be thrown if `size` is not a number.
 
-### Static method: `Buffer.allocUnsafe(size)`
+### Static method: `Buffer.allocUnsafe(size[, alignment])`
 
 <!-- YAML
 added: v5.10.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -810,6 +813,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -865,11 +871,14 @@ pool, while `Buffer.allocUnsafe(size).fill(fill)` _will_ use the internal
 difference is subtle but can be important when an application requires the
 additional performance that [`Buffer.allocUnsafe()`][] provides.
 
-### Static method: `Buffer.allocUnsafeSlow(size)`
+### Static method: `Buffer.allocUnsafeSlow(size[, alignment])`
 
 <!-- YAML
 added: v5.12.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -881,6 +890,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -5608,16 +5620,92 @@ While there are clear performance advantages to using
 [`Buffer.allocUnsafe()`][], extra care _must_ be taken in order to avoid
 introducing security vulnerabilities into an application.
 
+### Aligned allocations
+
+Some operating system interfaces require the memory they operate on to be
+aligned, and on some hardware alignment is merely faster. The most common
+example of the former is unbuffered ("direct") file I/O, which on Linux requires
+the buffer address, the file offset and the transfer length to all be multiples
+of the logical block size of the underlying device:
+
+```mjs
+import { open } from'node:fs/promises';
+import { constants } from'node:fs';
+import { Buffer } from'node:buffer';
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constfile=awaitopen('/dev/sda', constants.O_RDONLY|constants.O_DIRECT);
+try {
+awaitfile.read(buf, 0, blockSize, 0);
+} finally {
+awaitfile.close();
+}
+```
+
+```cjs
+constfs=require('node:fs');
+const { Buffer } =require('node:buffer');
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constflags=fs.constants.O_RDONLY|fs.constants.O_DIRECT;
+fs.open('/dev/sda', flags, (err, fd) => {
+if (err) throw err;
+fs.read(fd, buf, 0, blockSize, 0, (err) => {
+fs.close(fd, () => {});
+if (err) throw err;
+ });
+});
+```
+
+Alignment can also be worth requesting purely for performance, even when no
+interface demands it. Aligning a hot `Buffer` to the cache line size (64 bytes on
+most contemporary CPUs) keeps it from straddling one more cache line than it
+needs to, so that a small structure is fetched with one cache miss instead of
+two, and page-aligned (4096 bytes) allocations similarly help interfaces that map
+or pin memory. These are micro-optimizations: measure before reaching for them,
+since the extra bytes are not free.
+
+Because the address of a `Buffer`'s memory cannot be chosen directly, extra bytes
+have to be allocated or skipped to reach an aligned address.
+[`Buffer.allocUnsafeSlow()`][] over-allocates up to `alignment - 1` bytes and
+positions the returned `Buffer` at the first suitably aligned byte within them.
+[`Buffer.allocUnsafe()`][] instead pads its offset into the shared internal pool,
+whose start is always aligned to 64 bytes, and only falls back to an allocation
+of its own when `alignment` is larger than that. Either way,
+[`buf.byteOffset`][] is usually not 0 and [`buf.buffer`][] is larger than `size`,
+so code that reaches past the `Buffer` into its underlying `ArrayBuffer` must
+take the offset into account, as it must for pooled `Buffer`s.
+
+The alignment is a property of the returned `Buffer` and is preserved for its
+whole lifetime, but it is not inherited by other views: [`buf.subarray`][],
+[`buf.slice()`][] and `structuredClone()` may all produce unaligned `Buffer`s.
+
+Alignment also does not survive being captured in a startup snapshot: memory does
+not keep its address across serialization, so a `Buffer` allocated while
+[`--build-snapshot`][] is in effect is not aligned in the deserialized process.
+Allocate inside a [`v8.startupSnapshot.setDeserializeMainFunction()`][] callback,
+or after startup, if the alignment has to hold at run time.
+
 [ASCII]: https://en.wikipedia.org/wiki/ASCII
+[Aligned allocations]: #aligned-allocations
 [Base64]: https://en.wikipedia.org/wiki/Base64
 [ISO-8859-1]: https://en.wikipedia.org/wiki/ISO-8859-1
 [RFC 4648, Section 5]: https://tools.ietf.org/html/rfc4648#section-5
 [UTF-16]: https://en.wikipedia.org/wiki/UTF-16
 [UTF-8]: https://en.wikipedia.org/wiki/UTF-8
 [WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/
+[`--build-snapshot`]: cli.md#--build-snapshot
 [`Buffer.alloc()`]: #static-method-bufferallocsize-fill-encoding
-[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize
-[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize-alignment
+[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.concat()`]: #static-method-bufferconcatlist-totallength
 [`Buffer.copyBytesFrom()`]: #static-method-buffercopybytesfromview-offset-length
 [`Buffer.from(array)`]: #static-method-bufferfromarray
@@ -5639,6 +5727,7 @@ introducing security vulnerabilities into an application.
 [`TypedArray.prototype.subarray()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray
 [`blob.stream()`]: #blobstream
 [`buf.buffer`]: #bufbuffer
+[`buf.byteOffset`]: #bufbyteoffset
 [`buf.compare()`]: #bufcomparetarget-targetstart-targetend-sourcestart-sourceend
 [`buf.entries()`]: #bufentries
 [`buf.fill()`]: #buffillvalue-offset-end-encoding
@@ -5653,6 +5742,7 @@ introducing security vulnerabilities into an application.
 [`buffer.constants.MAX_STRING_LENGTH`]: #bufferconstantsmax_string_length
 [`buffer.kMaxLength`]: #bufferkmaxlength
 [`util.inspect()`]: util.md#utilinspectobject-options
+[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
 [`v8::Uint8Array::kMaxLength`]: https://v8.github.io/api/head/classv8_1_1Uint8Array.html#a7677e3d0c9c92e4d40bef7212f5980c6
 [base64url]: https://tools.ietf.org/html/rfc4648#section-5
 [endianness]: https://en.wikipedia.org/wiki/Endianness

doc/api/deprecations.md

@@ -4624,7 +4624,7 @@ will throw an error in a future version.
 [`--pending-deprecation`]: cli.md#--pending-deprecation
 [`--throw-deprecation`]: cli.md#--throw-deprecation
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
-[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.from(array)`]: buffer.md#static-method-bufferfromarray
 [`Buffer.from(buffer)`]: buffer.md#static-method-bufferfrombuffer
 [`Buffer.isBuffer()`]: buffer.md#static-method-bufferisbufferobj
@@ -4770,7 +4770,7 @@ will throw an error in a future version.
 [`writable.writableLength`]: stream.md#writablewritablelength
 [`zlib.bytesWritten`]: zlib.md#zlibbyteswritten
 [alloc]: buffer.md#static-method-bufferallocsize-fill-encoding
-[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize
+[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize-alignment
 [caveats of asynchronous customization hooks]: module.md#caveats-of-asynchronous-customization-hooks
 [from_arraybuffer]: buffer.md#static-method-bufferfromarraybuffer-byteoffset-length
 [from_string_encoding]: buffer.md#static-method-bufferfromstring-encoding

doc/api/worker_threads.md

@@ -2234,7 +2234,7 @@ thread spawned will spawn another until the application crashes.
 [`--max-old-space-size`]:cli.md#--max-old-space-sizesize-in-mib
 [`--max-semi-space-size`]:cli.md#--max-semi-space-sizesize-in-mib
 [`AsyncResource`]:async_hooks.md#class-asyncresource
-[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize
+[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize-alignment
 [`ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST`]:errors.md#err_missing_message_port_in_transfer_list
 [`ERR_WORKER_MESSAGING_ERRORED`]:errors.md#err_worker_messaging_errored
 [`ERR_WORKER_MESSAGING_FAILED`]:errors.md#err_worker_messaging_failed

lib/buffer.js

@@ -140,6 +140,7 @@ const {
  markAsUntransferable,
  addBufferPrototypeMethods,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  asciiWrite,
  latin1Write,
  utf8Write,
@@ -171,13 +172,27 @@ const constants = ObjectDefineProperties({}, {
 },
 });
 
+// The largest alignment accepted by `Buffer.allocUnsafeSlow()`. Any plausible
+// I/O alignment requirement (logical block size, memory page size, huge page
+// size) is well below this.
+constkMaxAlignment=2**30;
+
+// Slices handed out of the pool are 8 byte aligned relative to the start of the
+// pool, so aligning the pool itself to a cache line keeps them from straddling
+// one more cache line than their size requires.
+constkPoolAlignment=64;
+
 Buffer.poolSize=64*1024;
-letpoolSize,poolOffset,allocPool,allocBuffer;
+// `poolOffset` is relative to `poolBase`, which is where the pool starts inside
+// `allocPool`. The pool is over-allocated to be able to align it, so `poolBase`
+// is not necessarily 0.
+letpoolSize,poolOffset,poolBase,allocPool,allocBuffer;
 
 functioncreatePool(){
 poolSize=Buffer.poolSize;
-allocBuffer=createUnsafeBuffer(poolSize);
+allocBuffer=createUnsafeAlignedBuffer(poolSize,kPoolAlignment);
 allocPool=allocBuffer.buffer;
+poolBase=TypedArrayPrototypeGetByteOffset(allocBuffer);
 markAsUntransferable(allocPool);
 poolOffset=0;
 }
@@ -444,40 +459,92 @@ Buffer.alloc = function alloc(size, fill, encoding) {
 /**
  * Equivalent to Buffer(num), by default creates a non-zero-filled Buffer
  * instance. If `--zero-fill-buffers` is set, will zero-fill the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`. See `Buffer.allocUnsafeSlow()`.
+ * @param {number} size
+ * @param {number} [alignment] A power of two, at most 2 ** 30
  * @returns {FastBuffer}
  */
-Buffer.allocUnsafe=functionallocUnsafe(size){
+Buffer.allocUnsafe=functionallocUnsafe(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returnallocate(size);
+if(alignment===undefined){
+returnallocate(size);
+}
+validateAlignment(size,alignment);
+returnallocateAligned(size,alignment);
 };
 
 /**
  * By default creates a non-zero-filled Buffer instance that is not allocated
  * off the pre-initialized pool. If `--zero-fill-buffers` is set, will zero-fill
  * the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`, which is required by e.g. reads
+ * and writes on file descriptors opened with `O_DIRECT`. Note that up to
+ * `alignment - 1` extra bytes are allocated to satisfy the request, and that
+ * the returned buffer's `byteOffset` is therefore usually non-zero.
  * @param {number} size
- * @returns {FastBuffer|undefined}
+ * @param {number} [alignment] A power of two, at most 2 ** 30
+ * @returns {FastBuffer}
  */
-Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size){
+Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returncreateUnsafeBuffer(size);
+if(alignment===undefined){
+returncreateUnsafeBuffer(size);
+}
+validateAlignment(size,alignment);
+returncreateUnsafeAlignedBuffer(size,alignment);
 };
 
+functionvalidateAlignment(size,alignment){
+validateInteger(alignment,'alignment',1,kMaxAlignment);
+if((alignment&(alignment-1))!==0){
+thrownewERR_INVALID_ARG_VALUE(
+'alignment',alignment,'must be a power of two');
+}
+// Satisfying the alignment costs up to `alignment - 1` extra bytes.
+if(size>kMaxLength-(alignment-1)){
+thrownewERR_OUT_OF_RANGE(
+'size',`<= ${kMaxLength-(alignment-1)}`,size);
+}
+}
+
 functionallocate(size){
 if(size<=0){
 returnnewFastBuffer();
 }
 if(size<(Buffer.poolSize>>>1)){
 if(size>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,size);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
 poolOffset+=size;
 alignPool();
 returnb;
 }
 returncreateUnsafeBuffer(size);
 }
 
+functionallocateAligned(size,alignment){
+if(size<=0){
+returnnewFastBuffer();
+}
+// The pool starts at a `kPoolAlignment` aligned address, so any alignment up
+// to that can be satisfied by padding the offset into the pool. Stricter
+// alignments need an allocation of their own.
+if(alignment>kPoolAlignment||size>=(Buffer.poolSize>>>1)){
+returncreateUnsafeAlignedBuffer(size,alignment);
+}
+poolOffset=(poolOffset+alignment-1)&~(alignment-1);
+if(size>(poolSize-poolOffset))
+createPool();
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
+poolOffset+=size;
+alignPool();
+returnb;
+}
+
 functionfromStringFast(string,ops){
 constmaxLength=Buffer.poolSize>>>1;
 
@@ -498,7 +565,7 @@ function fromStringFast(string, ops) {
 createPool();
 
 constactual=ops.write(allocBuffer,string,poolOffset,length);
-constb=newFastBuffer(allocPool,poolOffset,actual);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,actual);
 
 poolOffset+=actual;
 alignPool();
@@ -560,7 +627,7 @@ function fromArrayLike(obj) {
 if(length<(Buffer.poolSize>>>1)){
 if(length>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,length);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,length);
 TypedArrayPrototypeSet(b,obj,0);
 poolOffset+=length;
 alignPool();

lib/internal/buffer.js

@@ -33,6 +33,7 @@ const {
  hexWrite,
  ucs2Write,
  utf8WriteStatic,
+ arrayBufferAlignedOffset,
  createUnsafeArrayBuffer,
  setDetachKey,
 }=internalBinding('buffer');
@@ -1104,12 +1105,28 @@ function createUnsafeBuffer(size) {
 returnnewFastBuffer(createUnsafeArrayBuffer(size));
 }
 
+// Returns an uninitialized buffer of `size` bytes whose first byte is located at
+// a memory address that is a multiple of `alignment`. `alignment` must be a
+// power of two, and `size + alignment - 1` must not exceed the maximum buffer
+// length. Since the address of a backing store cannot be chosen, `alignment - 1`
+// extra bytes are allocated and skipped, which leaves the returned buffer with a
+// non-zero `byteOffset` into a larger ArrayBuffer.
+functioncreateUnsafeAlignedBuffer(size,alignment){
+if(size===0){
+returnnewFastBuffer();
+}
+
+constab=createUnsafeArrayBuffer(size+alignment-1);
+returnnewFastBuffer(ab,arrayBufferAlignedOffset(ab,alignment),size);
+}
+
 module.exports={
  FastBuffer,
  addBufferPrototypeMethods,
  markAsUntransferable,
  isMarkedAsUntransferable,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  readUInt16BE,
  readUInt32BE,
  asciiWrite,

doc/api/buffer.md

@@ -791,11 +791,14 @@ data that might not have been allocated for `Buffer`s.
 
 A `TypeError` will be thrown if `size` is not a number.
 
-### Static method: `Buffer.allocUnsafe(size)`
+### Static method: `Buffer.allocUnsafe(size[, alignment])`
 
 <!-- YAML
 added: v5.10.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -810,6 +813,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -865,11 +871,14 @@ pool, while `Buffer.allocUnsafe(size).fill(fill)` _will_ use the internal
 difference is subtle but can be important when an application requires the
 additional performance that [`Buffer.allocUnsafe()`][] provides.
 
-### Static method: `Buffer.allocUnsafeSlow(size)`
+### Static method: `Buffer.allocUnsafeSlow(size[, alignment])`
 
 <!-- YAML
 added: v5.12.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -881,6 +890,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -5608,16 +5620,92 @@ While there are clear performance advantages to using
 [`Buffer.allocUnsafe()`][], extra care _must_ be taken in order to avoid
 introducing security vulnerabilities into an application.
 
+### Aligned allocations
+
+Some operating system interfaces require the memory they operate on to be
+aligned, and on some hardware alignment is merely faster. The most common
+example of the former is unbuffered ("direct") file I/O, which on Linux requires
+the buffer address, the file offset and the transfer length to all be multiples
+of the logical block size of the underlying device:
+
+```mjs
+import { open } from'node:fs/promises';
+import { constants } from'node:fs';
+import { Buffer } from'node:buffer';
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constfile=awaitopen('/dev/sda', constants.O_RDONLY|constants.O_DIRECT);
+try {
+awaitfile.read(buf, 0, blockSize, 0);
+} finally {
+awaitfile.close();
+}
+```
+
+```cjs
+constfs=require('node:fs');
+const { Buffer } =require('node:buffer');
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constflags=fs.constants.O_RDONLY|fs.constants.O_DIRECT;
+fs.open('/dev/sda', flags, (err, fd) => {
+if (err) throw err;
+fs.read(fd, buf, 0, blockSize, 0, (err) => {
+fs.close(fd, () => {});
+if (err) throw err;
+ });
+});
+```
+
+Alignment can also be worth requesting purely for performance, even when no
+interface demands it. Aligning a hot `Buffer` to the cache line size (64 bytes on
+most contemporary CPUs) keeps it from straddling one more cache line than it
+needs to, so that a small structure is fetched with one cache miss instead of
+two, and page-aligned (4096 bytes) allocations similarly help interfaces that map
+or pin memory. These are micro-optimizations: measure before reaching for them,
+since the extra bytes are not free.
+
+Because the address of a `Buffer`'s memory cannot be chosen directly, extra bytes
+have to be allocated or skipped to reach an aligned address.
+[`Buffer.allocUnsafeSlow()`][] over-allocates up to `alignment - 1` bytes and
+positions the returned `Buffer` at the first suitably aligned byte within them.
+[`Buffer.allocUnsafe()`][] instead pads its offset into the shared internal pool,
+whose start is always aligned to 64 bytes, and only falls back to an allocation
+of its own when `alignment` is larger than that. Either way,
+[`buf.byteOffset`][] is usually not 0 and [`buf.buffer`][] is larger than `size`,
+so code that reaches past the `Buffer` into its underlying `ArrayBuffer` must
+take the offset into account, as it must for pooled `Buffer`s.
+
+The alignment is a property of the returned `Buffer` and is preserved for its
+whole lifetime, but it is not inherited by other views: [`buf.subarray`][],
+[`buf.slice()`][] and `structuredClone()` may all produce unaligned `Buffer`s.
+
+Alignment also does not survive being captured in a startup snapshot: memory does
+not keep its address across serialization, so a `Buffer` allocated while
+[`--build-snapshot`][] is in effect is not aligned in the deserialized process.
+Allocate inside a [`v8.startupSnapshot.setDeserializeMainFunction()`][] callback,
+or after startup, if the alignment has to hold at run time.
+
 [ASCII]: https://en.wikipedia.org/wiki/ASCII
+[Aligned allocations]: #aligned-allocations
 [Base64]: https://en.wikipedia.org/wiki/Base64
 [ISO-8859-1]: https://en.wikipedia.org/wiki/ISO-8859-1
 [RFC 4648, Section 5]: https://tools.ietf.org/html/rfc4648#section-5
 [UTF-16]: https://en.wikipedia.org/wiki/UTF-16
 [UTF-8]: https://en.wikipedia.org/wiki/UTF-8
 [WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/
+[`--build-snapshot`]: cli.md#--build-snapshot
 [`Buffer.alloc()`]: #static-method-bufferallocsize-fill-encoding
-[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize
-[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize-alignment
+[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.concat()`]: #static-method-bufferconcatlist-totallength
 [`Buffer.copyBytesFrom()`]: #static-method-buffercopybytesfromview-offset-length
 [`Buffer.from(array)`]: #static-method-bufferfromarray
@@ -5639,6 +5727,7 @@ introducing security vulnerabilities into an application.
 [`TypedArray.prototype.subarray()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray
 [`blob.stream()`]: #blobstream
 [`buf.buffer`]: #bufbuffer
+[`buf.byteOffset`]: #bufbyteoffset
 [`buf.compare()`]: #bufcomparetarget-targetstart-targetend-sourcestart-sourceend
 [`buf.entries()`]: #bufentries
 [`buf.fill()`]: #buffillvalue-offset-end-encoding
@@ -5653,6 +5742,7 @@ introducing security vulnerabilities into an application.
 [`buffer.constants.MAX_STRING_LENGTH`]: #bufferconstantsmax_string_length
 [`buffer.kMaxLength`]: #bufferkmaxlength
 [`util.inspect()`]: util.md#utilinspectobject-options
+[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
 [`v8::Uint8Array::kMaxLength`]: https://v8.github.io/api/head/classv8_1_1Uint8Array.html#a7677e3d0c9c92e4d40bef7212f5980c6
 [base64url]: https://tools.ietf.org/html/rfc4648#section-5
 [endianness]: https://en.wikipedia.org/wiki/Endianness

doc/api/deprecations.md

@@ -4624,7 +4624,7 @@ will throw an error in a future version.
 [`--pending-deprecation`]: cli.md#--pending-deprecation
 [`--throw-deprecation`]: cli.md#--throw-deprecation
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
-[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.from(array)`]: buffer.md#static-method-bufferfromarray
 [`Buffer.from(buffer)`]: buffer.md#static-method-bufferfrombuffer
 [`Buffer.isBuffer()`]: buffer.md#static-method-bufferisbufferobj
@@ -4770,7 +4770,7 @@ will throw an error in a future version.
 [`writable.writableLength`]: stream.md#writablewritablelength
 [`zlib.bytesWritten`]: zlib.md#zlibbyteswritten
 [alloc]: buffer.md#static-method-bufferallocsize-fill-encoding
-[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize
+[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize-alignment
 [caveats of asynchronous customization hooks]: module.md#caveats-of-asynchronous-customization-hooks
 [from_arraybuffer]: buffer.md#static-method-bufferfromarraybuffer-byteoffset-length
 [from_string_encoding]: buffer.md#static-method-bufferfromstring-encoding

doc/api/worker_threads.md

@@ -2234,7 +2234,7 @@ thread spawned will spawn another until the application crashes.
 [`--max-old-space-size`]:cli.md#--max-old-space-sizesize-in-mib
 [`--max-semi-space-size`]:cli.md#--max-semi-space-sizesize-in-mib
 [`AsyncResource`]:async_hooks.md#class-asyncresource
-[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize
+[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize-alignment
 [`ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST`]:errors.md#err_missing_message_port_in_transfer_list
 [`ERR_WORKER_MESSAGING_ERRORED`]:errors.md#err_worker_messaging_errored
 [`ERR_WORKER_MESSAGING_FAILED`]:errors.md#err_worker_messaging_failed

lib/buffer.js

@@ -140,6 +140,7 @@ const {
  markAsUntransferable,
  addBufferPrototypeMethods,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  asciiWrite,
  latin1Write,
  utf8Write,
@@ -171,13 +172,27 @@ const constants = ObjectDefineProperties({}, {
 },
 });
 
+// The largest alignment accepted by `Buffer.allocUnsafeSlow()`. Any plausible
+// I/O alignment requirement (logical block size, memory page size, huge page
+// size) is well below this.
+constkMaxAlignment=2**30;
+
+// Slices handed out of the pool are 8 byte aligned relative to the start of the
+// pool, so aligning the pool itself to a cache line keeps them from straddling
+// one more cache line than their size requires.
+constkPoolAlignment=64;
+
 Buffer.poolSize=64*1024;
-letpoolSize,poolOffset,allocPool,allocBuffer;
+// `poolOffset` is relative to `poolBase`, which is where the pool starts inside
+// `allocPool`. The pool is over-allocated to be able to align it, so `poolBase`
+// is not necessarily 0.
+letpoolSize,poolOffset,poolBase,allocPool,allocBuffer;
 
 functioncreatePool(){
 poolSize=Buffer.poolSize;
-allocBuffer=createUnsafeBuffer(poolSize);
+allocBuffer=createUnsafeAlignedBuffer(poolSize,kPoolAlignment);
 allocPool=allocBuffer.buffer;
+poolBase=TypedArrayPrototypeGetByteOffset(allocBuffer);
 markAsUntransferable(allocPool);
 poolOffset=0;
 }
@@ -444,40 +459,92 @@ Buffer.alloc = function alloc(size, fill, encoding) {
 /**
  * Equivalent to Buffer(num), by default creates a non-zero-filled Buffer
  * instance. If `--zero-fill-buffers` is set, will zero-fill the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`. See `Buffer.allocUnsafeSlow()`.
+ * @param {number} size
+ * @param {number} [alignment] A power of two, at most 2 ** 30
  * @returns {FastBuffer}
  */
-Buffer.allocUnsafe=functionallocUnsafe(size){
+Buffer.allocUnsafe=functionallocUnsafe(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returnallocate(size);
+if(alignment===undefined){
+returnallocate(size);
+}
+validateAlignment(size,alignment);
+returnallocateAligned(size,alignment);
 };
 
 /**
  * By default creates a non-zero-filled Buffer instance that is not allocated
  * off the pre-initialized pool. If `--zero-fill-buffers` is set, will zero-fill
  * the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`, which is required by e.g. reads
+ * and writes on file descriptors opened with `O_DIRECT`. Note that up to
+ * `alignment - 1` extra bytes are allocated to satisfy the request, and that
+ * the returned buffer's `byteOffset` is therefore usually non-zero.
  * @param {number} size
- * @returns {FastBuffer|undefined}
+ * @param {number} [alignment] A power of two, at most 2 ** 30
+ * @returns {FastBuffer}
  */
-Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size){
+Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returncreateUnsafeBuffer(size);
+if(alignment===undefined){
+returncreateUnsafeBuffer(size);
+}
+validateAlignment(size,alignment);
+returncreateUnsafeAlignedBuffer(size,alignment);
 };
 
+functionvalidateAlignment(size,alignment){
+validateInteger(alignment,'alignment',1,kMaxAlignment);
+if((alignment&(alignment-1))!==0){
+thrownewERR_INVALID_ARG_VALUE(
+'alignment',alignment,'must be a power of two');
+}
+// Satisfying the alignment costs up to `alignment - 1` extra bytes.
+if(size>kMaxLength-(alignment-1)){
+thrownewERR_OUT_OF_RANGE(
+'size',`<= ${kMaxLength-(alignment-1)}`,size);
+}
+}
+
 functionallocate(size){
 if(size<=0){
 returnnewFastBuffer();
 }
 if(size<(Buffer.poolSize>>>1)){
 if(size>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,size);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
 poolOffset+=size;
 alignPool();
 returnb;
 }
 returncreateUnsafeBuffer(size);
 }
 
+functionallocateAligned(size,alignment){
+if(size<=0){
+returnnewFastBuffer();
+}
+// The pool starts at a `kPoolAlignment` aligned address, so any alignment up
+// to that can be satisfied by padding the offset into the pool. Stricter
+// alignments need an allocation of their own.
+if(alignment>kPoolAlignment||size>=(Buffer.poolSize>>>1)){
+returncreateUnsafeAlignedBuffer(size,alignment);
+}
+poolOffset=(poolOffset+alignment-1)&~(alignment-1);
+if(size>(poolSize-poolOffset))
+createPool();
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
+poolOffset+=size;
+alignPool();
+returnb;
+}
+
 functionfromStringFast(string,ops){
 constmaxLength=Buffer.poolSize>>>1;
 
@@ -498,7 +565,7 @@ function fromStringFast(string, ops) {
 createPool();
 
 constactual=ops.write(allocBuffer,string,poolOffset,length);
-constb=newFastBuffer(allocPool,poolOffset,actual);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,actual);
 
 poolOffset+=actual;
 alignPool();
@@ -560,7 +627,7 @@ function fromArrayLike(obj) {
 if(length<(Buffer.poolSize>>>1)){
 if(length>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,length);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,length);
 TypedArrayPrototypeSet(b,obj,0);
 poolOffset+=length;
 alignPool();

lib/internal/buffer.js

@@ -33,6 +33,7 @@ const {
  hexWrite,
  ucs2Write,
  utf8WriteStatic,
+ arrayBufferAlignedOffset,
  createUnsafeArrayBuffer,
  setDetachKey,
 }=internalBinding('buffer');
@@ -1104,12 +1105,28 @@ function createUnsafeBuffer(size) {
 returnnewFastBuffer(createUnsafeArrayBuffer(size));
 }
 
+// Returns an uninitialized buffer of `size` bytes whose first byte is located at
+// a memory address that is a multiple of `alignment`. `alignment` must be a
+// power of two, and `size + alignment - 1` must not exceed the maximum buffer
+// length. Since the address of a backing store cannot be chosen, `alignment - 1`
+// extra bytes are allocated and skipped, which leaves the returned buffer with a
+// non-zero `byteOffset` into a larger ArrayBuffer.
+functioncreateUnsafeAlignedBuffer(size,alignment){
+if(size===0){
+returnnewFastBuffer();
+}
+
+constab=createUnsafeArrayBuffer(size+alignment-1);
+returnnewFastBuffer(ab,arrayBufferAlignedOffset(ab,alignment),size);
+}
+
 module.exports={
  FastBuffer,
  addBufferPrototypeMethods,
  markAsUntransferable,
  isMarkedAsUntransferable,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  readUInt16BE,
  readUInt32BE,
  asciiWrite,

doc/api/buffer.md

@@ -791,11 +791,14 @@ data that might not have been allocated for `Buffer`s.
 
 A `TypeError` will be thrown if `size` is not a number.
 
-### Static method: `Buffer.allocUnsafe(size)`
+### Static method: `Buffer.allocUnsafe(size[, alignment])`
 
 <!-- YAML
 added: v5.10.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -810,6 +813,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -865,11 +871,14 @@ pool, while `Buffer.allocUnsafe(size).fill(fill)` _will_ use the internal
 difference is subtle but can be important when an application requires the
 additional performance that [`Buffer.allocUnsafe()`][] provides.
 
-### Static method: `Buffer.allocUnsafeSlow(size)`
+### Static method: `Buffer.allocUnsafeSlow(size[, alignment])`
 
 <!-- YAML
 added: v5.12.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -881,6 +890,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -5608,16 +5620,92 @@ While there are clear performance advantages to using
 [`Buffer.allocUnsafe()`][], extra care _must_ be taken in order to avoid
 introducing security vulnerabilities into an application.
 
+### Aligned allocations
+
+Some operating system interfaces require the memory they operate on to be
+aligned, and on some hardware alignment is merely faster. The most common
+example of the former is unbuffered ("direct") file I/O, which on Linux requires
+the buffer address, the file offset and the transfer length to all be multiples
+of the logical block size of the underlying device:
+
+```mjs
+import { open } from'node:fs/promises';
+import { constants } from'node:fs';
+import { Buffer } from'node:buffer';
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constfile=awaitopen('/dev/sda', constants.O_RDONLY|constants.O_DIRECT);
+try {
+awaitfile.read(buf, 0, blockSize, 0);
+} finally {
+awaitfile.close();
+}
+```
+
+```cjs
+constfs=require('node:fs');
+const { Buffer } =require('node:buffer');
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constflags=fs.constants.O_RDONLY|fs.constants.O_DIRECT;
+fs.open('/dev/sda', flags, (err, fd) => {
+if (err) throw err;
+fs.read(fd, buf, 0, blockSize, 0, (err) => {
+fs.close(fd, () => {});
+if (err) throw err;
+ });
+});
+```
+
+Alignment can also be worth requesting purely for performance, even when no
+interface demands it. Aligning a hot `Buffer` to the cache line size (64 bytes on
+most contemporary CPUs) keeps it from straddling one more cache line than it
+needs to, so that a small structure is fetched with one cache miss instead of
+two, and page-aligned (4096 bytes) allocations similarly help interfaces that map
+or pin memory. These are micro-optimizations: measure before reaching for them,
+since the extra bytes are not free.
+
+Because the address of a `Buffer`'s memory cannot be chosen directly, extra bytes
+have to be allocated or skipped to reach an aligned address.
+[`Buffer.allocUnsafeSlow()`][] over-allocates up to `alignment - 1` bytes and
+positions the returned `Buffer` at the first suitably aligned byte within them.
+[`Buffer.allocUnsafe()`][] instead pads its offset into the shared internal pool,
+whose start is always aligned to 64 bytes, and only falls back to an allocation
+of its own when `alignment` is larger than that. Either way,
+[`buf.byteOffset`][] is usually not 0 and [`buf.buffer`][] is larger than `size`,
+so code that reaches past the `Buffer` into its underlying `ArrayBuffer` must
+take the offset into account, as it must for pooled `Buffer`s.
+
+The alignment is a property of the returned `Buffer` and is preserved for its
+whole lifetime, but it is not inherited by other views: [`buf.subarray`][],
+[`buf.slice()`][] and `structuredClone()` may all produce unaligned `Buffer`s.
+
+Alignment also does not survive being captured in a startup snapshot: memory does
+not keep its address across serialization, so a `Buffer` allocated while
+[`--build-snapshot`][] is in effect is not aligned in the deserialized process.
+Allocate inside a [`v8.startupSnapshot.setDeserializeMainFunction()`][] callback,
+or after startup, if the alignment has to hold at run time.
+
 [ASCII]: https://en.wikipedia.org/wiki/ASCII
+[Aligned allocations]: #aligned-allocations
 [Base64]: https://en.wikipedia.org/wiki/Base64
 [ISO-8859-1]: https://en.wikipedia.org/wiki/ISO-8859-1
 [RFC 4648, Section 5]: https://tools.ietf.org/html/rfc4648#section-5
 [UTF-16]: https://en.wikipedia.org/wiki/UTF-16
 [UTF-8]: https://en.wikipedia.org/wiki/UTF-8
 [WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/
+[`--build-snapshot`]: cli.md#--build-snapshot
 [`Buffer.alloc()`]: #static-method-bufferallocsize-fill-encoding
-[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize
-[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize-alignment
+[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.concat()`]: #static-method-bufferconcatlist-totallength
 [`Buffer.copyBytesFrom()`]: #static-method-buffercopybytesfromview-offset-length
 [`Buffer.from(array)`]: #static-method-bufferfromarray
@@ -5639,6 +5727,7 @@ introducing security vulnerabilities into an application.
 [`TypedArray.prototype.subarray()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray
 [`blob.stream()`]: #blobstream
 [`buf.buffer`]: #bufbuffer
+[`buf.byteOffset`]: #bufbyteoffset
 [`buf.compare()`]: #bufcomparetarget-targetstart-targetend-sourcestart-sourceend
 [`buf.entries()`]: #bufentries
 [`buf.fill()`]: #buffillvalue-offset-end-encoding
@@ -5653,6 +5742,7 @@ introducing security vulnerabilities into an application.
 [`buffer.constants.MAX_STRING_LENGTH`]: #bufferconstantsmax_string_length
 [`buffer.kMaxLength`]: #bufferkmaxlength
 [`util.inspect()`]: util.md#utilinspectobject-options
+[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
 [`v8::Uint8Array::kMaxLength`]: https://v8.github.io/api/head/classv8_1_1Uint8Array.html#a7677e3d0c9c92e4d40bef7212f5980c6
 [base64url]: https://tools.ietf.org/html/rfc4648#section-5
 [endianness]: https://en.wikipedia.org/wiki/Endianness

doc/api/deprecations.md

@@ -4624,7 +4624,7 @@ will throw an error in a future version.
 [`--pending-deprecation`]: cli.md#--pending-deprecation
 [`--throw-deprecation`]: cli.md#--throw-deprecation
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
-[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.from(array)`]: buffer.md#static-method-bufferfromarray
 [`Buffer.from(buffer)`]: buffer.md#static-method-bufferfrombuffer
 [`Buffer.isBuffer()`]: buffer.md#static-method-bufferisbufferobj
@@ -4770,7 +4770,7 @@ will throw an error in a future version.
 [`writable.writableLength`]: stream.md#writablewritablelength
 [`zlib.bytesWritten`]: zlib.md#zlibbyteswritten
 [alloc]: buffer.md#static-method-bufferallocsize-fill-encoding
-[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize
+[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize-alignment
 [caveats of asynchronous customization hooks]: module.md#caveats-of-asynchronous-customization-hooks
 [from_arraybuffer]: buffer.md#static-method-bufferfromarraybuffer-byteoffset-length
 [from_string_encoding]: buffer.md#static-method-bufferfromstring-encoding

doc/api/worker_threads.md

@@ -2234,7 +2234,7 @@ thread spawned will spawn another until the application crashes.
 [`--max-old-space-size`]:cli.md#--max-old-space-sizesize-in-mib
 [`--max-semi-space-size`]:cli.md#--max-semi-space-sizesize-in-mib
 [`AsyncResource`]:async_hooks.md#class-asyncresource
-[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize
+[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize-alignment
 [`ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST`]:errors.md#err_missing_message_port_in_transfer_list
 [`ERR_WORKER_MESSAGING_ERRORED`]:errors.md#err_worker_messaging_errored
 [`ERR_WORKER_MESSAGING_FAILED`]:errors.md#err_worker_messaging_failed

lib/buffer.js

@@ -140,6 +140,7 @@ const {
  markAsUntransferable,
  addBufferPrototypeMethods,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  asciiWrite,
  latin1Write,
  utf8Write,
@@ -171,13 +172,27 @@ const constants = ObjectDefineProperties({}, {
 },
 });
 
+// The largest alignment accepted by `Buffer.allocUnsafeSlow()`. Any plausible
+// I/O alignment requirement (logical block size, memory page size, huge page
+// size) is well below this.
+constkMaxAlignment=2**30;
+
+// Slices handed out of the pool are 8 byte aligned relative to the start of the
+// pool, so aligning the pool itself to a cache line keeps them from straddling
+// one more cache line than their size requires.
+constkPoolAlignment=64;
+
 Buffer.poolSize=64*1024;
-letpoolSize,poolOffset,allocPool,allocBuffer;
+// `poolOffset` is relative to `poolBase`, which is where the pool starts inside
+// `allocPool`. The pool is over-allocated to be able to align it, so `poolBase`
+// is not necessarily 0.
+letpoolSize,poolOffset,poolBase,allocPool,allocBuffer;
 
 functioncreatePool(){
 poolSize=Buffer.poolSize;
-allocBuffer=createUnsafeBuffer(poolSize);
+allocBuffer=createUnsafeAlignedBuffer(poolSize,kPoolAlignment);
 allocPool=allocBuffer.buffer;
+poolBase=TypedArrayPrototypeGetByteOffset(allocBuffer);
 markAsUntransferable(allocPool);
 poolOffset=0;
 }
@@ -444,40 +459,92 @@ Buffer.alloc = function alloc(size, fill, encoding) {
 /**
  * Equivalent to Buffer(num), by default creates a non-zero-filled Buffer
  * instance. If `--zero-fill-buffers` is set, will zero-fill the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`. See `Buffer.allocUnsafeSlow()`.
+ * @param {number} size
+ * @param {number} [alignment] A power of two, at most 2 ** 30
  * @returns {FastBuffer}
  */
-Buffer.allocUnsafe=functionallocUnsafe(size){
+Buffer.allocUnsafe=functionallocUnsafe(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returnallocate(size);
+if(alignment===undefined){
+returnallocate(size);
+}
+validateAlignment(size,alignment);
+returnallocateAligned(size,alignment);
 };
 
 /**
  * By default creates a non-zero-filled Buffer instance that is not allocated
  * off the pre-initialized pool. If `--zero-fill-buffers` is set, will zero-fill
  * the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`, which is required by e.g. reads
+ * and writes on file descriptors opened with `O_DIRECT`. Note that up to
+ * `alignment - 1` extra bytes are allocated to satisfy the request, and that
+ * the returned buffer's `byteOffset` is therefore usually non-zero.
  * @param {number} size
- * @returns {FastBuffer|undefined}
+ * @param {number} [alignment] A power of two, at most 2 ** 30
+ * @returns {FastBuffer}
  */
-Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size){
+Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returncreateUnsafeBuffer(size);
+if(alignment===undefined){
+returncreateUnsafeBuffer(size);
+}
+validateAlignment(size,alignment);
+returncreateUnsafeAlignedBuffer(size,alignment);
 };
 
+functionvalidateAlignment(size,alignment){
+validateInteger(alignment,'alignment',1,kMaxAlignment);
+if((alignment&(alignment-1))!==0){
+thrownewERR_INVALID_ARG_VALUE(
+'alignment',alignment,'must be a power of two');
+}
+// Satisfying the alignment costs up to `alignment - 1` extra bytes.
+if(size>kMaxLength-(alignment-1)){
+thrownewERR_OUT_OF_RANGE(
+'size',`<= ${kMaxLength-(alignment-1)}`,size);
+}
+}
+
 functionallocate(size){
 if(size<=0){
 returnnewFastBuffer();
 }
 if(size<(Buffer.poolSize>>>1)){
 if(size>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,size);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
 poolOffset+=size;
 alignPool();
 returnb;
 }
 returncreateUnsafeBuffer(size);
 }
 
+functionallocateAligned(size,alignment){
+if(size<=0){
+returnnewFastBuffer();
+}
+// The pool starts at a `kPoolAlignment` aligned address, so any alignment up
+// to that can be satisfied by padding the offset into the pool. Stricter
+// alignments need an allocation of their own.
+if(alignment>kPoolAlignment||size>=(Buffer.poolSize>>>1)){
+returncreateUnsafeAlignedBuffer(size,alignment);
+}
+poolOffset=(poolOffset+alignment-1)&~(alignment-1);
+if(size>(poolSize-poolOffset))
+createPool();
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
+poolOffset+=size;
+alignPool();
+returnb;
+}
+
 functionfromStringFast(string,ops){
 constmaxLength=Buffer.poolSize>>>1;
 
@@ -498,7 +565,7 @@ function fromStringFast(string, ops) {
 createPool();
 
 constactual=ops.write(allocBuffer,string,poolOffset,length);
-constb=newFastBuffer(allocPool,poolOffset,actual);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,actual);
 
 poolOffset+=actual;
 alignPool();
@@ -560,7 +627,7 @@ function fromArrayLike(obj) {
 if(length<(Buffer.poolSize>>>1)){
 if(length>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,length);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,length);
 TypedArrayPrototypeSet(b,obj,0);
 poolOffset+=length;
 alignPool();

lib/internal/buffer.js

@@ -33,6 +33,7 @@ const {
  hexWrite,
  ucs2Write,
  utf8WriteStatic,
+ arrayBufferAlignedOffset,
  createUnsafeArrayBuffer,
  setDetachKey,
 }=internalBinding('buffer');
@@ -1104,12 +1105,28 @@ function createUnsafeBuffer(size) {
 returnnewFastBuffer(createUnsafeArrayBuffer(size));
 }
 
+// Returns an uninitialized buffer of `size` bytes whose first byte is located at
+// a memory address that is a multiple of `alignment`. `alignment` must be a
+// power of two, and `size + alignment - 1` must not exceed the maximum buffer
+// length. Since the address of a backing store cannot be chosen, `alignment - 1`
+// extra bytes are allocated and skipped, which leaves the returned buffer with a
+// non-zero `byteOffset` into a larger ArrayBuffer.
+functioncreateUnsafeAlignedBuffer(size,alignment){
+if(size===0){
+returnnewFastBuffer();
+}
+
+constab=createUnsafeArrayBuffer(size+alignment-1);
+returnnewFastBuffer(ab,arrayBufferAlignedOffset(ab,alignment),size);
+}
+
 module.exports={
  FastBuffer,
  addBufferPrototypeMethods,
  markAsUntransferable,
  isMarkedAsUntransferable,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  readUInt16BE,
  readUInt32BE,
  asciiWrite,

doc/api/buffer.md

@@ -791,11 +791,14 @@ data that might not have been allocated for `Buffer`s.
 
 A `TypeError` will be thrown if `size` is not a number.
 
-### Static method: `Buffer.allocUnsafe(size)`
+### Static method: `Buffer.allocUnsafe(size[, alignment])`
 
 <!-- YAML
 added: v5.10.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -810,6 +813,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -865,11 +871,14 @@ pool, while `Buffer.allocUnsafe(size).fill(fill)` _will_ use the internal
 difference is subtle but can be important when an application requires the
 additional performance that [`Buffer.allocUnsafe()`][] provides.
 
-### Static method: `Buffer.allocUnsafeSlow(size)`
+### Static method: `Buffer.allocUnsafeSlow(size[, alignment])`
 
 <!-- YAML
 added: v5.12.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -881,6 +890,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -5608,16 +5620,92 @@ While there are clear performance advantages to using
 [`Buffer.allocUnsafe()`][], extra care _must_ be taken in order to avoid
 introducing security vulnerabilities into an application.
 
+### Aligned allocations
+
+Some operating system interfaces require the memory they operate on to be
+aligned, and on some hardware alignment is merely faster. The most common
+example of the former is unbuffered ("direct") file I/O, which on Linux requires
+the buffer address, the file offset and the transfer length to all be multiples
+of the logical block size of the underlying device:
+
+```mjs
+import { open } from'node:fs/promises';
+import { constants } from'node:fs';
+import { Buffer } from'node:buffer';
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constfile=awaitopen('/dev/sda', constants.O_RDONLY|constants.O_DIRECT);
+try {
+awaitfile.read(buf, 0, blockSize, 0);
+} finally {
+awaitfile.close();
+}
+```
+
+```cjs
+constfs=require('node:fs');
+const { Buffer } =require('node:buffer');
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constflags=fs.constants.O_RDONLY|fs.constants.O_DIRECT;
+fs.open('/dev/sda', flags, (err, fd) => {
+if (err) throw err;
+fs.read(fd, buf, 0, blockSize, 0, (err) => {
+fs.close(fd, () => {});
+if (err) throw err;
+ });
+});
+```
+
+Alignment can also be worth requesting purely for performance, even when no
+interface demands it. Aligning a hot `Buffer` to the cache line size (64 bytes on
+most contemporary CPUs) keeps it from straddling one more cache line than it
+needs to, so that a small structure is fetched with one cache miss instead of
+two, and page-aligned (4096 bytes) allocations similarly help interfaces that map
+or pin memory. These are micro-optimizations: measure before reaching for them,
+since the extra bytes are not free.
+
+Because the address of a `Buffer`'s memory cannot be chosen directly, extra bytes
+have to be allocated or skipped to reach an aligned address.
+[`Buffer.allocUnsafeSlow()`][] over-allocates up to `alignment - 1` bytes and
+positions the returned `Buffer` at the first suitably aligned byte within them.
+[`Buffer.allocUnsafe()`][] instead pads its offset into the shared internal pool,
+whose start is always aligned to 64 bytes, and only falls back to an allocation
+of its own when `alignment` is larger than that. Either way,
+[`buf.byteOffset`][] is usually not 0 and [`buf.buffer`][] is larger than `size`,
+so code that reaches past the `Buffer` into its underlying `ArrayBuffer` must
+take the offset into account, as it must for pooled `Buffer`s.
+
+The alignment is a property of the returned `Buffer` and is preserved for its
+whole lifetime, but it is not inherited by other views: [`buf.subarray`][],
+[`buf.slice()`][] and `structuredClone()` may all produce unaligned `Buffer`s.
+
+Alignment also does not survive being captured in a startup snapshot: memory does
+not keep its address across serialization, so a `Buffer` allocated while
+[`--build-snapshot`][] is in effect is not aligned in the deserialized process.
+Allocate inside a [`v8.startupSnapshot.setDeserializeMainFunction()`][] callback,
+or after startup, if the alignment has to hold at run time.
+
 [ASCII]: https://en.wikipedia.org/wiki/ASCII
+[Aligned allocations]: #aligned-allocations
 [Base64]: https://en.wikipedia.org/wiki/Base64
 [ISO-8859-1]: https://en.wikipedia.org/wiki/ISO-8859-1
 [RFC 4648, Section 5]: https://tools.ietf.org/html/rfc4648#section-5
 [UTF-16]: https://en.wikipedia.org/wiki/UTF-16
 [UTF-8]: https://en.wikipedia.org/wiki/UTF-8
 [WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/
+[`--build-snapshot`]: cli.md#--build-snapshot
 [`Buffer.alloc()`]: #static-method-bufferallocsize-fill-encoding
-[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize
-[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize-alignment
+[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.concat()`]: #static-method-bufferconcatlist-totallength
 [`Buffer.copyBytesFrom()`]: #static-method-buffercopybytesfromview-offset-length
 [`Buffer.from(array)`]: #static-method-bufferfromarray
@@ -5639,6 +5727,7 @@ introducing security vulnerabilities into an application.
 [`TypedArray.prototype.subarray()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray
 [`blob.stream()`]: #blobstream
 [`buf.buffer`]: #bufbuffer
+[`buf.byteOffset`]: #bufbyteoffset
 [`buf.compare()`]: #bufcomparetarget-targetstart-targetend-sourcestart-sourceend
 [`buf.entries()`]: #bufentries
 [`buf.fill()`]: #buffillvalue-offset-end-encoding
@@ -5653,6 +5742,7 @@ introducing security vulnerabilities into an application.
 [`buffer.constants.MAX_STRING_LENGTH`]: #bufferconstantsmax_string_length
 [`buffer.kMaxLength`]: #bufferkmaxlength
 [`util.inspect()`]: util.md#utilinspectobject-options
+[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
 [`v8::Uint8Array::kMaxLength`]: https://v8.github.io/api/head/classv8_1_1Uint8Array.html#a7677e3d0c9c92e4d40bef7212f5980c6
 [base64url]: https://tools.ietf.org/html/rfc4648#section-5
 [endianness]: https://en.wikipedia.org/wiki/Endianness

doc/api/deprecations.md

@@ -4624,7 +4624,7 @@ will throw an error in a future version.
 [`--pending-deprecation`]: cli.md#--pending-deprecation
 [`--throw-deprecation`]: cli.md#--throw-deprecation
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
-[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.from(array)`]: buffer.md#static-method-bufferfromarray
 [`Buffer.from(buffer)`]: buffer.md#static-method-bufferfrombuffer
 [`Buffer.isBuffer()`]: buffer.md#static-method-bufferisbufferobj
@@ -4770,7 +4770,7 @@ will throw an error in a future version.
 [`writable.writableLength`]: stream.md#writablewritablelength
 [`zlib.bytesWritten`]: zlib.md#zlibbyteswritten
 [alloc]: buffer.md#static-method-bufferallocsize-fill-encoding
-[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize
+[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize-alignment
 [caveats of asynchronous customization hooks]: module.md#caveats-of-asynchronous-customization-hooks
 [from_arraybuffer]: buffer.md#static-method-bufferfromarraybuffer-byteoffset-length
 [from_string_encoding]: buffer.md#static-method-bufferfromstring-encoding

doc/api/worker_threads.md

@@ -2234,7 +2234,7 @@ thread spawned will spawn another until the application crashes.
 [`--max-old-space-size`]:cli.md#--max-old-space-sizesize-in-mib
 [`--max-semi-space-size`]:cli.md#--max-semi-space-sizesize-in-mib
 [`AsyncResource`]:async_hooks.md#class-asyncresource
-[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize
+[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize-alignment
 [`ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST`]:errors.md#err_missing_message_port_in_transfer_list
 [`ERR_WORKER_MESSAGING_ERRORED`]:errors.md#err_worker_messaging_errored
 [`ERR_WORKER_MESSAGING_FAILED`]:errors.md#err_worker_messaging_failed

lib/buffer.js

@@ -140,6 +140,7 @@ const {
  markAsUntransferable,
  addBufferPrototypeMethods,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  asciiWrite,
  latin1Write,
  utf8Write,
@@ -171,13 +172,27 @@ const constants = ObjectDefineProperties({}, {
 },
 });
 
+// The largest alignment accepted by `Buffer.allocUnsafeSlow()`. Any plausible
+// I/O alignment requirement (logical block size, memory page size, huge page
+// size) is well below this.
+constkMaxAlignment=2**30;
+
+// Slices handed out of the pool are 8 byte aligned relative to the start of the
+// pool, so aligning the pool itself to a cache line keeps them from straddling
+// one more cache line than their size requires.
+constkPoolAlignment=64;
+
 Buffer.poolSize=64*1024;
-letpoolSize,poolOffset,allocPool,allocBuffer;
+// `poolOffset` is relative to `poolBase`, which is where the pool starts inside
+// `allocPool`. The pool is over-allocated to be able to align it, so `poolBase`
+// is not necessarily 0.
+letpoolSize,poolOffset,poolBase,allocPool,allocBuffer;
 
 functioncreatePool(){
 poolSize=Buffer.poolSize;
-allocBuffer=createUnsafeBuffer(poolSize);
+allocBuffer=createUnsafeAlignedBuffer(poolSize,kPoolAlignment);
 allocPool=allocBuffer.buffer;
+poolBase=TypedArrayPrototypeGetByteOffset(allocBuffer);
 markAsUntransferable(allocPool);
 poolOffset=0;
 }
@@ -444,40 +459,92 @@ Buffer.alloc = function alloc(size, fill, encoding) {
 /**
  * Equivalent to Buffer(num), by default creates a non-zero-filled Buffer
  * instance. If `--zero-fill-buffers` is set, will zero-fill the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`. See `Buffer.allocUnsafeSlow()`.
+ * @param {number} size
+ * @param {number} [alignment] A power of two, at most 2 ** 30
  * @returns {FastBuffer}
  */
-Buffer.allocUnsafe=functionallocUnsafe(size){
+Buffer.allocUnsafe=functionallocUnsafe(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returnallocate(size);
+if(alignment===undefined){
+returnallocate(size);
+}
+validateAlignment(size,alignment);
+returnallocateAligned(size,alignment);
 };
 
 /**
  * By default creates a non-zero-filled Buffer instance that is not allocated
  * off the pre-initialized pool. If `--zero-fill-buffers` is set, will zero-fill
  * the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`, which is required by e.g. reads
+ * and writes on file descriptors opened with `O_DIRECT`. Note that up to
+ * `alignment - 1` extra bytes are allocated to satisfy the request, and that
+ * the returned buffer's `byteOffset` is therefore usually non-zero.
  * @param {number} size
- * @returns {FastBuffer|undefined}
+ * @param {number} [alignment] A power of two, at most 2 ** 30
+ * @returns {FastBuffer}
  */
-Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size){
+Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returncreateUnsafeBuffer(size);
+if(alignment===undefined){
+returncreateUnsafeBuffer(size);
+}
+validateAlignment(size,alignment);
+returncreateUnsafeAlignedBuffer(size,alignment);
 };
 
+functionvalidateAlignment(size,alignment){
+validateInteger(alignment,'alignment',1,kMaxAlignment);
+if((alignment&(alignment-1))!==0){
+thrownewERR_INVALID_ARG_VALUE(
+'alignment',alignment,'must be a power of two');
+}
+// Satisfying the alignment costs up to `alignment - 1` extra bytes.
+if(size>kMaxLength-(alignment-1)){
+thrownewERR_OUT_OF_RANGE(
+'size',`<= ${kMaxLength-(alignment-1)}`,size);
+}
+}
+
 functionallocate(size){
 if(size<=0){
 returnnewFastBuffer();
 }
 if(size<(Buffer.poolSize>>>1)){
 if(size>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,size);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
 poolOffset+=size;
 alignPool();
 returnb;
 }
 returncreateUnsafeBuffer(size);
 }
 
+functionallocateAligned(size,alignment){
+if(size<=0){
+returnnewFastBuffer();
+}
+// The pool starts at a `kPoolAlignment` aligned address, so any alignment up
+// to that can be satisfied by padding the offset into the pool. Stricter
+// alignments need an allocation of their own.
+if(alignment>kPoolAlignment||size>=(Buffer.poolSize>>>1)){
+returncreateUnsafeAlignedBuffer(size,alignment);
+}
+poolOffset=(poolOffset+alignment-1)&~(alignment-1);
+if(size>(poolSize-poolOffset))
+createPool();
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
+poolOffset+=size;
+alignPool();
+returnb;
+}
+
 functionfromStringFast(string,ops){
 constmaxLength=Buffer.poolSize>>>1;
 
@@ -498,7 +565,7 @@ function fromStringFast(string, ops) {
 createPool();
 
 constactual=ops.write(allocBuffer,string,poolOffset,length);
-constb=newFastBuffer(allocPool,poolOffset,actual);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,actual);
 
 poolOffset+=actual;
 alignPool();
@@ -560,7 +627,7 @@ function fromArrayLike(obj) {
 if(length<(Buffer.poolSize>>>1)){
 if(length>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,length);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,length);
 TypedArrayPrototypeSet(b,obj,0);
 poolOffset+=length;
 alignPool();

lib/internal/buffer.js

@@ -33,6 +33,7 @@ const {
  hexWrite,
  ucs2Write,
  utf8WriteStatic,
+ arrayBufferAlignedOffset,
  createUnsafeArrayBuffer,
  setDetachKey,
 }=internalBinding('buffer');
@@ -1104,12 +1105,28 @@ function createUnsafeBuffer(size) {
 returnnewFastBuffer(createUnsafeArrayBuffer(size));
 }
 
+// Returns an uninitialized buffer of `size` bytes whose first byte is located at
+// a memory address that is a multiple of `alignment`. `alignment` must be a
+// power of two, and `size + alignment - 1` must not exceed the maximum buffer
+// length. Since the address of a backing store cannot be chosen, `alignment - 1`
+// extra bytes are allocated and skipped, which leaves the returned buffer with a
+// non-zero `byteOffset` into a larger ArrayBuffer.
+functioncreateUnsafeAlignedBuffer(size,alignment){
+if(size===0){
+returnnewFastBuffer();
+}
+
+constab=createUnsafeArrayBuffer(size+alignment-1);
+returnnewFastBuffer(ab,arrayBufferAlignedOffset(ab,alignment),size);
+}
+
 module.exports={
  FastBuffer,
  addBufferPrototypeMethods,
  markAsUntransferable,
  isMarkedAsUntransferable,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  readUInt16BE,
  readUInt32BE,
  asciiWrite,

doc/api/buffer.md

@@ -791,11 +791,14 @@ data that might not have been allocated for `Buffer`s.
 
 A `TypeError` will be thrown if `size` is not a number.
 
-### Static method: `Buffer.allocUnsafe(size)`
+### Static method: `Buffer.allocUnsafe(size[, alignment])`
 
 <!-- YAML
 added: v5.10.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -810,6 +813,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -865,11 +871,14 @@ pool, while `Buffer.allocUnsafe(size).fill(fill)` _will_ use the internal
 difference is subtle but can be important when an application requires the
 additional performance that [`Buffer.allocUnsafe()`][] provides.
 
-### Static method: `Buffer.allocUnsafeSlow(size)`
+### Static method: `Buffer.allocUnsafeSlow(size[, alignment])`
 
 <!-- YAML
 added: v5.12.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/65003
+ description: Added the `alignment` argument.
  - version: v20.0.0
  pr-url: https://github.com/nodejs/node/pull/45796
  description: Throw ERR_INVALID_ARG_TYPE or ERR_OUT_OF_RANGE instead of
@@ -881,6 +890,9 @@ changes:
 -->
 
 *`size` {integer} The desired length of the new `Buffer`.
+*`alignment` {integer} If given, the memory backing the new `Buffer` will start
+ at an address that is a multiple of `alignment`. Must be a power of two no
+ larger than `2 ** 30`. See [Aligned allocations][].
 * Returns: {Buffer}
 
 Allocates a new `Buffer` of `size` bytes. If `size` is larger than
@@ -5608,16 +5620,92 @@ While there are clear performance advantages to using
 [`Buffer.allocUnsafe()`][], extra care _must_ be taken in order to avoid
 introducing security vulnerabilities into an application.
 
+### Aligned allocations
+
+Some operating system interfaces require the memory they operate on to be
+aligned, and on some hardware alignment is merely faster. The most common
+example of the former is unbuffered ("direct") file I/O, which on Linux requires
+the buffer address, the file offset and the transfer length to all be multiples
+of the logical block size of the underlying device:
+
+```mjs
+import { open } from'node:fs/promises';
+import { constants } from'node:fs';
+import { Buffer } from'node:buffer';
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constfile=awaitopen('/dev/sda', constants.O_RDONLY|constants.O_DIRECT);
+try {
+awaitfile.read(buf, 0, blockSize, 0);
+} finally {
+awaitfile.close();
+}
+```
+
+```cjs
+constfs=require('node:fs');
+const { Buffer } =require('node:buffer');
+
+constblockSize=4096;
+
+// The buffer address must be block-aligned for O_DIRECT to accept it.
+constbuf=Buffer.allocUnsafeSlow(blockSize, blockSize);
+
+constflags=fs.constants.O_RDONLY|fs.constants.O_DIRECT;
+fs.open('/dev/sda', flags, (err, fd) => {
+if (err) throw err;
+fs.read(fd, buf, 0, blockSize, 0, (err) => {
+fs.close(fd, () => {});
+if (err) throw err;
+ });
+});
+```
+
+Alignment can also be worth requesting purely for performance, even when no
+interface demands it. Aligning a hot `Buffer` to the cache line size (64 bytes on
+most contemporary CPUs) keeps it from straddling one more cache line than it
+needs to, so that a small structure is fetched with one cache miss instead of
+two, and page-aligned (4096 bytes) allocations similarly help interfaces that map
+or pin memory. These are micro-optimizations: measure before reaching for them,
+since the extra bytes are not free.
+
+Because the address of a `Buffer`'s memory cannot be chosen directly, extra bytes
+have to be allocated or skipped to reach an aligned address.
+[`Buffer.allocUnsafeSlow()`][] over-allocates up to `alignment - 1` bytes and
+positions the returned `Buffer` at the first suitably aligned byte within them.
+[`Buffer.allocUnsafe()`][] instead pads its offset into the shared internal pool,
+whose start is always aligned to 64 bytes, and only falls back to an allocation
+of its own when `alignment` is larger than that. Either way,
+[`buf.byteOffset`][] is usually not 0 and [`buf.buffer`][] is larger than `size`,
+so code that reaches past the `Buffer` into its underlying `ArrayBuffer` must
+take the offset into account, as it must for pooled `Buffer`s.
+
+The alignment is a property of the returned `Buffer` and is preserved for its
+whole lifetime, but it is not inherited by other views: [`buf.subarray`][],
+[`buf.slice()`][] and `structuredClone()` may all produce unaligned `Buffer`s.
+
+Alignment also does not survive being captured in a startup snapshot: memory does
+not keep its address across serialization, so a `Buffer` allocated while
+[`--build-snapshot`][] is in effect is not aligned in the deserialized process.
+Allocate inside a [`v8.startupSnapshot.setDeserializeMainFunction()`][] callback,
+or after startup, if the alignment has to hold at run time.
+
 [ASCII]: https://en.wikipedia.org/wiki/ASCII
+[Aligned allocations]: #aligned-allocations
 [Base64]: https://en.wikipedia.org/wiki/Base64
 [ISO-8859-1]: https://en.wikipedia.org/wiki/ISO-8859-1
 [RFC 4648, Section 5]: https://tools.ietf.org/html/rfc4648#section-5
 [UTF-16]: https://en.wikipedia.org/wiki/UTF-16
 [UTF-8]: https://en.wikipedia.org/wiki/UTF-8
 [WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/
+[`--build-snapshot`]: cli.md#--build-snapshot
 [`Buffer.alloc()`]: #static-method-bufferallocsize-fill-encoding
-[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize
-[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize-alignment
+[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.concat()`]: #static-method-bufferconcatlist-totallength
 [`Buffer.copyBytesFrom()`]: #static-method-buffercopybytesfromview-offset-length
 [`Buffer.from(array)`]: #static-method-bufferfromarray
@@ -5639,6 +5727,7 @@ introducing security vulnerabilities into an application.
 [`TypedArray.prototype.subarray()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray
 [`blob.stream()`]: #blobstream
 [`buf.buffer`]: #bufbuffer
+[`buf.byteOffset`]: #bufbyteoffset
 [`buf.compare()`]: #bufcomparetarget-targetstart-targetend-sourcestart-sourceend
 [`buf.entries()`]: #bufentries
 [`buf.fill()`]: #buffillvalue-offset-end-encoding
@@ -5653,6 +5742,7 @@ introducing security vulnerabilities into an application.
 [`buffer.constants.MAX_STRING_LENGTH`]: #bufferconstantsmax_string_length
 [`buffer.kMaxLength`]: #bufferkmaxlength
 [`util.inspect()`]: util.md#utilinspectobject-options
+[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
 [`v8::Uint8Array::kMaxLength`]: https://v8.github.io/api/head/classv8_1_1Uint8Array.html#a7677e3d0c9c92e4d40bef7212f5980c6
 [base64url]: https://tools.ietf.org/html/rfc4648#section-5
 [endianness]: https://en.wikipedia.org/wiki/Endianness

doc/api/deprecations.md

@@ -4624,7 +4624,7 @@ will throw an error in a future version.
 [`--pending-deprecation`]: cli.md#--pending-deprecation
 [`--throw-deprecation`]: cli.md#--throw-deprecation
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
-[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize
+[`Buffer.allocUnsafeSlow(size)`]: buffer.md#static-method-bufferallocunsafeslowsize-alignment
 [`Buffer.from(array)`]: buffer.md#static-method-bufferfromarray
 [`Buffer.from(buffer)`]: buffer.md#static-method-bufferfrombuffer
 [`Buffer.isBuffer()`]: buffer.md#static-method-bufferisbufferobj
@@ -4770,7 +4770,7 @@ will throw an error in a future version.
 [`writable.writableLength`]: stream.md#writablewritablelength
 [`zlib.bytesWritten`]: zlib.md#zlibbyteswritten
 [alloc]: buffer.md#static-method-bufferallocsize-fill-encoding
-[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize
+[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize-alignment
 [caveats of asynchronous customization hooks]: module.md#caveats-of-asynchronous-customization-hooks
 [from_arraybuffer]: buffer.md#static-method-bufferfromarraybuffer-byteoffset-length
 [from_string_encoding]: buffer.md#static-method-bufferfromstring-encoding

doc/api/worker_threads.md

@@ -2234,7 +2234,7 @@ thread spawned will spawn another until the application crashes.
 [`--max-old-space-size`]:cli.md#--max-old-space-sizesize-in-mib
 [`--max-semi-space-size`]:cli.md#--max-semi-space-sizesize-in-mib
 [`AsyncResource`]:async_hooks.md#class-asyncresource
-[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize
+[`Buffer.allocUnsafe()`]:buffer.md#static-method-bufferallocunsafesize-alignment
 [`ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST`]:errors.md#err_missing_message_port_in_transfer_list
 [`ERR_WORKER_MESSAGING_ERRORED`]:errors.md#err_worker_messaging_errored
 [`ERR_WORKER_MESSAGING_FAILED`]:errors.md#err_worker_messaging_failed

lib/buffer.js

@@ -140,6 +140,7 @@ const {
  markAsUntransferable,
  addBufferPrototypeMethods,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  asciiWrite,
  latin1Write,
  utf8Write,
@@ -171,13 +172,27 @@ const constants = ObjectDefineProperties({}, {
 },
 });
 
+// The largest alignment accepted by `Buffer.allocUnsafeSlow()`. Any plausible
+// I/O alignment requirement (logical block size, memory page size, huge page
+// size) is well below this.
+constkMaxAlignment=2**30;
+
+// Slices handed out of the pool are 8 byte aligned relative to the start of the
+// pool, so aligning the pool itself to a cache line keeps them from straddling
+// one more cache line than their size requires.
+constkPoolAlignment=64;
+
 Buffer.poolSize=64*1024;
-letpoolSize,poolOffset,allocPool,allocBuffer;
+// `poolOffset` is relative to `poolBase`, which is where the pool starts inside
+// `allocPool`. The pool is over-allocated to be able to align it, so `poolBase`
+// is not necessarily 0.
+letpoolSize,poolOffset,poolBase,allocPool,allocBuffer;
 
 functioncreatePool(){
 poolSize=Buffer.poolSize;
-allocBuffer=createUnsafeBuffer(poolSize);
+allocBuffer=createUnsafeAlignedBuffer(poolSize,kPoolAlignment);
 allocPool=allocBuffer.buffer;
+poolBase=TypedArrayPrototypeGetByteOffset(allocBuffer);
 markAsUntransferable(allocPool);
 poolOffset=0;
 }
@@ -444,40 +459,92 @@ Buffer.alloc = function alloc(size, fill, encoding) {
 /**
  * Equivalent to Buffer(num), by default creates a non-zero-filled Buffer
  * instance. If `--zero-fill-buffers` is set, will zero-fill the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`. See `Buffer.allocUnsafeSlow()`.
+ * @param {number} size
+ * @param {number} [alignment] A power of two, at most 2 ** 30
  * @returns {FastBuffer}
  */
-Buffer.allocUnsafe=functionallocUnsafe(size){
+Buffer.allocUnsafe=functionallocUnsafe(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returnallocate(size);
+if(alignment===undefined){
+returnallocate(size);
+}
+validateAlignment(size,alignment);
+returnallocateAligned(size,alignment);
 };
 
 /**
  * By default creates a non-zero-filled Buffer instance that is not allocated
  * off the pre-initialized pool. If `--zero-fill-buffers` is set, will zero-fill
  * the buffer.
+ *
+ * If `alignment` is given, the memory backing the returned buffer starts at an
+ * address that is a multiple of `alignment`, which is required by e.g. reads
+ * and writes on file descriptors opened with `O_DIRECT`. Note that up to
+ * `alignment - 1` extra bytes are allocated to satisfy the request, and that
+ * the returned buffer's `byteOffset` is therefore usually non-zero.
  * @param {number} size
- * @returns {FastBuffer|undefined}
+ * @param {number} [alignment] A power of two, at most 2 ** 30
+ * @returns {FastBuffer}
  */
-Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size){
+Buffer.allocUnsafeSlow=functionallocUnsafeSlow(size,alignment){
 validateNumber(size,'size',0,kMaxLength);
-returncreateUnsafeBuffer(size);
+if(alignment===undefined){
+returncreateUnsafeBuffer(size);
+}
+validateAlignment(size,alignment);
+returncreateUnsafeAlignedBuffer(size,alignment);
 };
 
+functionvalidateAlignment(size,alignment){
+validateInteger(alignment,'alignment',1,kMaxAlignment);
+if((alignment&(alignment-1))!==0){
+thrownewERR_INVALID_ARG_VALUE(
+'alignment',alignment,'must be a power of two');
+}
+// Satisfying the alignment costs up to `alignment - 1` extra bytes.
+if(size>kMaxLength-(alignment-1)){
+thrownewERR_OUT_OF_RANGE(
+'size',`<= ${kMaxLength-(alignment-1)}`,size);
+}
+}
+
 functionallocate(size){
 if(size<=0){
 returnnewFastBuffer();
 }
 if(size<(Buffer.poolSize>>>1)){
 if(size>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,size);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
 poolOffset+=size;
 alignPool();
 returnb;
 }
 returncreateUnsafeBuffer(size);
 }
 
+functionallocateAligned(size,alignment){
+if(size<=0){
+returnnewFastBuffer();
+}
+// The pool starts at a `kPoolAlignment` aligned address, so any alignment up
+// to that can be satisfied by padding the offset into the pool. Stricter
+// alignments need an allocation of their own.
+if(alignment>kPoolAlignment||size>=(Buffer.poolSize>>>1)){
+returncreateUnsafeAlignedBuffer(size,alignment);
+}
+poolOffset=(poolOffset+alignment-1)&~(alignment-1);
+if(size>(poolSize-poolOffset))
+createPool();
+constb=newFastBuffer(allocPool,poolBase+poolOffset,size);
+poolOffset+=size;
+alignPool();
+returnb;
+}
+
 functionfromStringFast(string,ops){
 constmaxLength=Buffer.poolSize>>>1;
 
@@ -498,7 +565,7 @@ function fromStringFast(string, ops) {
 createPool();
 
 constactual=ops.write(allocBuffer,string,poolOffset,length);
-constb=newFastBuffer(allocPool,poolOffset,actual);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,actual);
 
 poolOffset+=actual;
 alignPool();
@@ -560,7 +627,7 @@ function fromArrayLike(obj) {
 if(length<(Buffer.poolSize>>>1)){
 if(length>(poolSize-poolOffset))
 createPool();
-constb=newFastBuffer(allocPool,poolOffset,length);
+constb=newFastBuffer(allocPool,poolBase+poolOffset,length);
 TypedArrayPrototypeSet(b,obj,0);
 poolOffset+=length;
 alignPool();

lib/internal/buffer.js

@@ -33,6 +33,7 @@ const {
  hexWrite,
  ucs2Write,
  utf8WriteStatic,
+ arrayBufferAlignedOffset,
  createUnsafeArrayBuffer,
  setDetachKey,
 }=internalBinding('buffer');
@@ -1104,12 +1105,28 @@ function createUnsafeBuffer(size) {
 returnnewFastBuffer(createUnsafeArrayBuffer(size));
 }
 
+// Returns an uninitialized buffer of `size` bytes whose first byte is located at
+// a memory address that is a multiple of `alignment`. `alignment` must be a
+// power of two, and `size + alignment - 1` must not exceed the maximum buffer
+// length. Since the address of a backing store cannot be chosen, `alignment - 1`
+// extra bytes are allocated and skipped, which leaves the returned buffer with a
+// non-zero `byteOffset` into a larger ArrayBuffer.
+functioncreateUnsafeAlignedBuffer(size,alignment){
+if(size===0){
+returnnewFastBuffer();
+}
+
+constab=createUnsafeArrayBuffer(size+alignment-1);
+returnnewFastBuffer(ab,arrayBufferAlignedOffset(ab,alignment),size);
+}
+
 module.exports={
  FastBuffer,
  addBufferPrototypeMethods,
  markAsUntransferable,
  isMarkedAsUntransferable,
  createUnsafeBuffer,
+ createUnsafeAlignedBuffer,
  readUInt16BE,
  readUInt32BE,
  asciiWrite,