buffer: optimize Buffer.prototype.copy

Route the native backing of Buffer.prototype.copy (CopyImpl, the `_copy`
binding) through V8's new v8::ArrayBuffer::CopyArrayBufferBytes API
(added in the preceding commit) instead of materializing an
ArrayBufferViewContents and doing a manual memmove. This speeds up
partial copies (sourceStart > 0). All copies now go through this
binding: the previous %TypedArray%.prototype.set fast-path for
whole-buffer copies is dropped, since it would throw on a detached or
immutable target rather than report a 0-byte no-op, and the benchmarks
below show the native path is comparable for that case.

When both sides are backed by a SharedArrayBuffer the relaxed-atomic
overload is used, which honors the SharedArrayBuffer memory model.
Mixed copies (one SharedArrayBuffer, one ArrayBuffer) use the regular
overload.

copy() now reports the number of bytes actually copied, as returned by
V8: 0 when the target is backed by a detached or immutable ArrayBuffer.
The copy is then a no-op rather than a write to read-only memory.

The native binding now plumbs byte offsets and the copied-byte count
through as size_t, passed across the fast/slow API boundary as doubles
(exact for integer values below 2^53), so copies that cross the 4 GiB
boundary are no longer truncated to 32 bits.

buffer-copy.js vs node v26.3.0 (x64, 30 runs):
  partial=false bytes=1024:  +7.91%  (***)
  partial=false bytes=128:   +0.17%
  partial=false bytes=8:     -0.89%
  partial=true  bytes=1024: +22.33%  (***)
  partial=true  bytes=128:  +19.58%  (***)
  partial=true  bytes=8:    +18.70%  (***)

This supersedes the prototype in
https://github.com/nodejs/node/pull/62491, which added a bespoke
ArrayBufferView::FastCopy instead of using the upstream-friendly
CopyArrayBufferBytes API.

Adds SharedArrayBuffer and immutable-ArrayBuffer coverage to the buffer
copy tests, plus a pummel regression test for copies larger than 2^32
bytes.

Refs: https://github.com/nodejs/node/issues/55422
Signed-off-by: Robert Nagy <ronagy@icloud.com>
Assisted-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
PR-URL: https://github.com/nodejs/node/pull/63828
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

lib/buffer.js

@@ -267,7 +267,7 @@ function copyImpl(source, target, targetStart, sourceStart, sourceEnd) {
   return _copyActual(source, target, targetStart, sourceStart, sourceEnd);
 }
 
-function _copyActual(source, target, targetStart, sourceStart, sourceEnd, isUint8Copy = false) {
+function _copyActual(source, target, targetStart, sourceStart, sourceEnd) {
   if (sourceEnd - sourceStart > target.byteLength - targetStart)
     sourceEnd = sourceStart + target.byteLength - targetStart;
 
@@ -279,13 +279,10 @@ function _copyActual(source, target, targetStart, sourceStart, sourceEnd, isUint
   if (nb <= 0)
     return 0;
 
-  if (sourceStart === 0 && nb === sourceLen && (isUint8Copy || isUint8Array(target))) {
-    TypedArrayPrototypeSet(target, source, targetStart);
-  } else {
-    _copy(source, target, targetStart, sourceStart, nb);
-  }
-
-  return nb;
+  // `_copy` returns the number of bytes actually copied, which is `nb` except
+  // when the target is backed by a detached or immutable ArrayBuffer, in which
+  // case nothing is copied and it returns 0.
+  return _copy(source, target, targetStart, sourceStart, nb);
 }
 
 /**

src/node_buffer.cc

@@ -597,44 +597,78 @@ void StringSlice(const FunctionCallbackInfo<Value>& args) {
   }
 }
 
-void CopyImpl(Local<Value> source_obj,
-              Local<Value> target_obj,
-              const uint32_t target_start,
-              const uint32_t source_start,
-              const uint32_t to_copy) {
-  ArrayBufferViewContents<char> source(source_obj);
-  SPREAD_BUFFER_ARG(target_obj, target);
+// Returns the number of bytes actually copied. This is normally |to_copy|, but
+// V8 copies nothing (and returns 0) when the target is backed by a detached or
+// immutable ArrayBuffer.
+size_t CopyImpl(Local<Value> source_obj,
+                Local<Value> target_obj,
+                const size_t target_start,
+                const size_t source_start,
+                const size_t to_copy) {
+  Local<ArrayBufferView> source = source_obj.As<ArrayBufferView>();
+  Local<ArrayBufferView> target = target_obj.As<ArrayBufferView>();
 
-  memmove(target_data + target_start, source.data() + source_start, to_copy);
+  Local<ArrayBuffer> source_ab = source->Buffer();
+  Local<ArrayBuffer> target_ab = target->Buffer();
+
+  const size_t source_offset = source->ByteOffset() + source_start;
+  const size_t target_offset = target->ByteOffset() + target_start;
+
+  // Defer byte-range clamping and detached/immutable handling to V8. When both
+  // sides are backed by a SharedArrayBuffer the relaxed atomic overload is
+  // used, which honors the SharedArrayBuffer memory model. Any other
+  // combination (both regular, or one of each) goes through the ArrayBuffer
+  // overload: it operates on the underlying backing store regardless of
+  // shared-ness, so a plain memmove is performed (matching the historical
+  // behavior for SharedArrayBuffer-backed buffers). The V8 API has no overload
+  // that mixes ArrayBuffer and SharedArrayBuffer, so the two must never be
+  // cross-cast.
+  if (source_ab->IsSharedArrayBuffer() && target_ab->IsSharedArrayBuffer()) {
+    return source_ab.As<SharedArrayBuffer>()->CopyArrayBufferBytes(
+        source_offset,
+        to_copy,
+        target_ab.As<SharedArrayBuffer>(),
+        target_offset);
+  }
+  return source_ab->CopyArrayBufferBytes(
+      source_offset, to_copy, target_ab, target_offset);
 }
 
 // Assume caller has properly validated args.
 void SlowCopy(const FunctionCallbackInfo<Value>& args) {
   Local<Value> source_obj = args[0];
   Local<Value> target_obj = args[1];
-  const uint32_t target_start = args[2].As<Uint32>()->Value();
-  const uint32_t source_start = args[3].As<Uint32>()->Value();
-  const uint32_t to_copy = args[4].As<Uint32>()->Value();
+  // Byte offsets and lengths can exceed uint32 for buffers larger than 4 GiB,
+  // so they are passed and returned as doubles (exact for integers < 2^53).
+  const size_t target_start =
+      static_cast<size_t>(args[2].As<Number>()->Value());
+  const size_t source_start =
+      static_cast<size_t>(args[3].As<Number>()->Value());
+  const size_t to_copy = static_cast<size_t>(args[4].As<Number>()->Value());
 
-  CopyImpl(source_obj, target_obj, target_start, source_start, to_copy);
+  const size_t copied =
+      CopyImpl(source_obj, target_obj, target_start, source_start, to_copy);
 
-  args.GetReturnValue().Set(to_copy);
+  args.GetReturnValue().Set(static_cast<double>(copied));
 }
 
 // Assume caller has properly validated args.
-uint32_t FastCopy(Local<Value> receiver,
-                  Local<Value> source_obj,
-                  Local<Value> target_obj,
-                  uint32_t target_start,
-                  uint32_t source_start,
-                  uint32_t to_copy,
-                  // NOLINTNEXTLINE(runtime/references)
-                  FastApiCallbackOptions& options) {
+double FastCopy(Local<Value> receiver,
+                Local<Value> source_obj,
+                Local<Value> target_obj,
+                double target_start,
+                double source_start,
+                double to_copy,
+                // NOLINTNEXTLINE(runtime/references)
+                FastApiCallbackOptions& options) {
+  TRACK_V8_FAST_API_CALL("buffer.copy");
   HandleScope scope(options.isolate);
 
-  CopyImpl(source_obj, target_obj, target_start, source_start, to_copy);
-
-  return to_copy;
+  return static_cast<double>(CopyImpl(source_obj,
+                                      target_obj,
+                                      static_cast<size_t>(target_start),
+                                      static_cast<size_t>(source_start),
+                                      static_cast<size_t>(to_copy)));
 }
 
 static CFunction fast_copy(CFunction::Make(FastCopy));

test/parallel/test-buffer-copy-immutable.js

@@ -0,0 +1,48 @@
+// Flags: --js-immutable-arraybuffer
+'use strict';
+const common = require('../common');
+const assert = require('assert');
+
+// transferToImmutable is gated behind --js-immutable-arraybuffer (set above).
+// Skip if this V8 build does not expose the API even with the flag set.
+if (typeof ArrayBuffer.prototype.transferToImmutable !== 'function')
+  common.skip('ArrayBuffer.prototype.transferToImmutable is not available');
+
+// Copying *into* a buffer backed by an immutable ArrayBuffer must not write to
+// the read-only backing store. The copy is a no-op and reports 0 bytes copied.
+{
+  const ab = new ArrayBuffer(8);
+  new Uint8Array(ab).set([1, 2, 3, 4, 5, 6, 7, 8]);
+  const target = Buffer.from(ab.transferToImmutable());
+  const source = Buffer.from([9, 9, 9, 9, 9, 9, 9, 9]);
+
+  assert.strictEqual(source.copy(target), 0);
+  assert.deepStrictEqual([...target], [1, 2, 3, 4, 5, 6, 7, 8]);
+
+  // A partial / offset copy is also a no-op.
+  assert.strictEqual(source.copy(target, 2, 0, 4), 0);
+  assert.deepStrictEqual([...target], [1, 2, 3, 4, 5, 6, 7, 8]);
+}
+
+// Copying *from* a buffer backed by an immutable ArrayBuffer is allowed (reads
+// do not require a writable backing store) and reports the bytes copied.
+{
+  const ab = new ArrayBuffer(8);
+  new Uint8Array(ab).set([10, 20, 30, 40, 50, 60, 70, 80]);
+  const source = Buffer.from(ab.transferToImmutable());
+  const target = Buffer.alloc(8);
+
+  assert.strictEqual(source.copy(target), 8);
+  assert.deepStrictEqual([...target], [10, 20, 30, 40, 50, 60, 70, 80]);
+}
+
+// A mutable Uint8Array view onto an immutable ArrayBuffer is still a read-only
+// target through Buffer.prototype.copy.
+{
+  const ab = new ArrayBuffer(4);
+  new Uint8Array(ab).set([100, 101, 102, 103]);
+  const target = new Uint8Array(ab.transferToImmutable());
+
+  assert.strictEqual(Buffer.from([1, 2, 3, 4]).copy(target), 0);
+  assert.deepStrictEqual([...target], [100, 101, 102, 103]);
+}

test/parallel/test-buffer-copy.js

@@ -251,3 +251,54 @@ assert.deepStrictEqual(c, b.slice(0, c.length));
   // No copying took place:
   assert.deepStrictEqual(c.toString(), 'C'.repeat(c.length));
 }
+
+// Copying to/from SharedArrayBuffer-backed buffers. The relaxed-atomic copy
+// path is used only when both sides are backed by a SharedArrayBuffer; mixed
+// copies (one shared, one not) go through the regular non-atomic overload.
+{
+  // SharedArrayBuffer -> SharedArrayBuffer.
+  const src = Buffer.from(new SharedArrayBuffer(512)).fill(0x61);
+  const dst = Buffer.from(new SharedArrayBuffer(512)).fill(0x62);
+  const copied = src.copy(dst, 0, 0, 512);
+  assert.strictEqual(copied, 512);
+  assert.deepStrictEqual(Buffer.from(dst), Buffer.from(src));
+}
+
+{
+  // SharedArrayBuffer source -> regular Buffer target (mixed).
+  const src = Buffer.from(new SharedArrayBuffer(256)).fill(0x63);
+  const dst = Buffer.allocUnsafe(256).fill(0x64);
+  assert.strictEqual(src.copy(dst), 256);
+  assert.deepStrictEqual(dst, Buffer.from(src));
+}
+
+{
+  // Regular Buffer source -> SharedArrayBuffer target (mixed).
+  const src = Buffer.allocUnsafe(256).fill(0x65);
+  const dst = Buffer.from(new SharedArrayBuffer(256)).fill(0x66);
+  assert.strictEqual(src.copy(dst), 256);
+  assert.deepStrictEqual(Buffer.from(dst), src);
+}
+
+{
+  // Views with a non-zero byteOffset over a SharedArrayBuffer. The native copy
+  // is relative to the underlying ArrayBuffer, so the view's byteOffset must be
+  // accounted for.
+  const sab = new SharedArrayBuffer(16);
+  const whole = Buffer.from(sab);
+  for (let i = 0; i < 16; i++) whole[i] = i;
+  const src = Buffer.from(sab, 4, 8);   // sab bytes 4..11
+  const dst = Buffer.from(sab, 12, 4);  // sab bytes 12..15
+  assert.strictEqual(src.copy(dst, 0, 0, 4), 4);
+  assert.deepStrictEqual(
+    [...whole],
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 4, 5, 6, 7]);
+}
+
+{
+  // Overlapping copy within a single SharedArrayBuffer uses memmove semantics.
+  const buf = Buffer.from(new SharedArrayBuffer(8));
+  for (let i = 0; i < 8; i++) buf[i] = i + 1; // [1,2,3,4,5,6,7,8]
+  assert.strictEqual(buf.copy(buf, 2, 0, 6), 6);
+  assert.deepStrictEqual([...buf], [1, 2, 1, 2, 3, 4, 5, 6]);
+}

test/pummel/test-buffer-large-size-copy.js

@@ -0,0 +1,40 @@
+'use strict';
+const common = require('../common');
+
+// Buffer.prototype.copy with offsets and a byte count > 2 ** 32. Regression
+// test for the .copy() side of https://github.com/nodejs/node/issues/55422,
+// where the byte count and the return value were truncated to 32 bits.
+common.skipIf32Bits();
+
+const assert = require('node:assert');
+
+// A little past the 2 ** 32 boundary, with headroom for the shift below.
+const size = 2 ** 32 + 16;
+
+let buf;
+try {
+  buf = Buffer.alloc(size);
+} catch (e) {
+  if (
+    e.code === 'ERR_MEMORY_ALLOCATION_FAILED' ||
+    /Array buffer allocation failed/.test(e.message)
+  ) {
+    common.skip('insufficient memory for Buffer.alloc');
+  }
+
+  throw e;
+}
+
+// Place a marker near the end of the source range, at an index > 2 ** 32.
+const marker = 0x42;
+buf[size - 9] = marker;
+
+// Shift the whole buffer right by 8 bytes within itself. `to_copy` is
+// size - 8 (> 2 ** 32), so a truncated count would copy only 8 bytes. The
+// source byte at size - 9 must land at size - 1.
+const copied = buf.copy(buf, 8, 0, size - 8);
+
+// The return value must not be truncated to 32 bits ...
+assert.strictEqual(copied, size - 8);
+// ... and the byte must actually have moved across the 2 ** 32 boundary.
+assert.strictEqual(buf[size - 1], marker);