Change ArrayBuffer implementation from copyBuffer to moveBuffer (#56691)

Summary:
Pull Request resolved: #56691

Switches the `jsi::ArrayBuffer ⇄ native byte buffer` bridge in TurboModules from a copy-based implementation (`OwnedMutableBuffer`) to a zero-copy borrow implementation (`BorrowedMutableBuffer`) on the paths where the caller can guarantee the source memory's lifetime, eliminating an O(N) copy on every ArrayBuffer that crosses the JS/native boundary.

**`ReactCommon/react/bridging/ArrayBuffer.h`** — adds `BorrowedMutableBuffer`: holds a raw `uint8_t*` + size, plus an optional `std::function<void()>` release callback invoked from the destructor. Caller is responsible for keeping the underlying memory alive — typically by capturing a JNI `global_ref` or ARC-retained ObjC object in the release lambda. Non-copyable; documents thread-safety requirements (release may fire on the JS GC thread). `OwnedMutableBuffer` and the `Bridging<std::vector<uint8_t>>` specialization are preserved for paths where the source lifetime cannot be guaranteed.

**Android — `JavaTurboModule.cpp`** — wraps the Java `ByteBuffer`'s direct memory in a `BorrowedMutableBuffer`. Pins the buffer with `jni::make_global(jByteBuffer)` and captures the global ref in the release lambda so Java GC cannot collect it while the JS ArrayBuffer is alive. Tightens the `Ljava/nio/ByteBuffer;` argument check from `isObject()` to `isObject() && isArrayBuffer()`.

**iOS — `RCTTurboModule.mm`** — `convertJSIObjectToObjCObject` (sync arg path) returns `NSMutableData dataWithBytesNoCopy:length:freeWhenDone:NO` instead of copying via `[NSData dataWithBytes:length:]`. Safe because the JS ArrayBuffer outlives the synchronous call. `convertReturnIdToJSIValue` `ArrayBufferKind` (sync return path) wraps `NSMutableData.mutableBytes` with `BorrowedMutableBuffer`, retaining the `NSMutableData` via the block capture for the lifetime of the JS ArrayBuffer. `convertObjCObjectToJSIValue` (async/promise path) adds an `NSData → ArrayBuffer` branch that still copies via `OwnedMutableBuffer`, since the source NSData lifetime cannot be guaranteed past the async callback.

**Codegen — `serializeMethod.js` + snapshot** — ObjC++ spec generator now emits `NSMutableData *` (instead of `NSData *`) for `ArrayBufferTypeAnnotation`, both for parameters and return types. Module authors must update their ObjC implementations.

Changelog:
[General][Changed] - TurboModule ArrayBuffer transfers between JS and native are now zero-copy where caller lifetime can be guaranteed; ObjC TurboModule specs now use `NSMutableData *` for `ArrayBufferTypeAnnotation` parameters and return types

Differential Revision: D96034456

Author: christophpurrer

packages/react-native-codegen/src/generators/modules/GenerateModuleObjCpp/serializeMethod.js

@@ -221,7 +221,7 @@ function getParamObjCType(
       return notStruct(wrapOptional('NSArray *', !nullable));
     }
     case 'ArrayBufferTypeAnnotation': {
-      return notStruct(wrapOptional('NSData *', !nullable));
+      return notStruct(wrapOptional('NSMutableData *', !nullable));
     }
   }
 
@@ -392,7 +392,7 @@ function getReturnObjCType(
     case 'GenericObjectTypeAnnotation':
       return wrapOptional('NSDictionary *', isRequired);
     case 'ArrayBufferTypeAnnotation':
-      return wrapOptional('NSData *', isRequired);
+      return wrapOptional('NSMutableData *', isRequired);
     default:
       typeAnnotation.type as 'MixedTypeAnnotation';
       throw new Error(

packages/react-native-codegen/src/generators/modules/__tests__/__snapshots__/GenerateModuleHObjCpp-test.js.snap

@@ -102,9 +102,9 @@ Map {
 
 @protocol NativeSampleTurboModuleSpec <RCTBridgeModule, RCTTurboModule>
 
-- (NSData *)getArrayBuffer:(NSData *)buffer;
-- (void)saveData:(NSData *)data;
-- (NSData * _Nullable)loadData;
+- (NSMutableData *)getArrayBuffer:(NSMutableData *)buffer;
+- (void)saveData:(NSMutableData *)data;
+- (NSMutableData * _Nullable)loadData;
 
 @end
 

packages/react-native/ReactCommon/react/bridging/ArrayBuffer.h

@@ -10,55 +10,60 @@
 #include <react/bridging/Base.h>
 
 #include <cstring>
-#include <iterator>
-#include <vector>
+#include <functional>
 
 namespace facebook::react {
 
 /**
- * A concrete implementation of jsi::MutableBuffer that owns a copy of the data.
- * Used when creating jsi::ArrayBuffer from native data (e.g., NSData,
- * ByteBuffer) where we need to copy the data to ensure proper memory
- * ownership.
+ * A non-owning implementation of jsi::MutableBuffer that borrows a pointer to
+ * externally-managed memory. The caller MUST ensure the underlying data outlives
+ * the buffer, or provide a release callback that prevents the source from being
+ * deallocated (e.g., a JNI global_ref or an ARC-retained ObjC object).
+ *
+ * When the BorrowedMutableBuffer is destroyed, the optional release callback is
+ * invoked, allowing the prevent-GC reference to be dropped.
+ *
+ * Thread safety: The release callback may be invoked on any thread (typically
+ * the JS thread during garbage collection). Callers must ensure the release
+ * callback is safe to invoke from any thread. JNI DeleteGlobalRef and ARC
+ * release are both thread-safe.
+ *
+ * The release callback must not throw exceptions. Throwing from the destructor
+ * will terminate the process.
  */
-class OwnedMutableBuffer : public jsi::MutableBuffer {
+class BorrowedMutableBuffer : public jsi::MutableBuffer {
  public:
-  OwnedMutableBuffer(const uint8_t *data, size_t size) : data_(data, std::next(data, static_cast<std::ptrdiff_t>(size)))
+  BorrowedMutableBuffer(uint8_t *data, size_t size, std::function<void()> release = nullptr)
+      : data_(data), size_(size), release_(std::move(release))
   {
   }
 
-  explicit OwnedMutableBuffer(size_t size) : data_(size, 0) {}
+  ~BorrowedMutableBuffer() override
+  {
+    if (release_) {
+      release_();
+    }
+  }
 
-  explicit OwnedMutableBuffer(std::vector<uint8_t> data) : data_(std::move(data)) {}
+  BorrowedMutableBuffer(const BorrowedMutableBuffer &) = delete;
+  BorrowedMutableBuffer &operator=(const BorrowedMutableBuffer &) = delete;
+  BorrowedMutableBuffer(BorrowedMutableBuffer &&) = delete;
+  BorrowedMutableBuffer &operator=(BorrowedMutableBuffer &&) = delete;
 
   size_t size() const override
   {
-    return data_.size();
+    return size_;
   }
 
   uint8_t *data() override
   {
-    return data_.data();
+    return data_;
   }
 
  private:
-  std::vector<uint8_t> data_;
-};
-
-template <>
-struct Bridging<std::vector<uint8_t>> {
-  static std::vector<uint8_t> fromJs(jsi::Runtime &rt, const jsi::ArrayBuffer &buffer)
-  {
-    auto size = buffer.size(rt);
-    auto data = buffer.data(rt);
-    return {data, std::next(data, static_cast<std::ptrdiff_t>(size))};
-  }
-
-  static jsi::ArrayBuffer toJs(jsi::Runtime &rt, const std::vector<uint8_t> &data)
-  {
-    auto buffer = std::make_shared<OwnedMutableBuffer>(data.data(), data.size());
-    return {rt, std::move(buffer)};
-  }
+  uint8_t *data_;
+  size_t size_;
+  std::function<void()> release_;
 };
 
 } // namespace facebook::react

packages/react-native/ReactCommon/react/bridging/tests/BridgingTest.cpp

@@ -780,33 +780,43 @@ TEST_F(BridgingTest, dynamicTest) {
   EXPECT_TRUE(undefinedFromJsResult.isNull());
 }
 
-TEST_F(BridgingTest, arrayBufferTest) {
-  // Test round-trip: vector<uint8_t> -> ArrayBuffer -> vector<uint8_t>
-  auto vec = std::vector<uint8_t>({1, 2, 3, 4, 5});
-  auto arrayBuffer = bridging::toJs(rt, vec, invoker);
-  auto result =
-      bridging::fromJs<std::vector<uint8_t>>(rt, arrayBuffer, invoker);
-  EXPECT_EQ(vec, result);
-
-  // Test empty vector round-trip
-  auto emptyVec = std::vector<uint8_t>();
-  auto emptyArrayBuffer = bridging::toJs(rt, emptyVec, invoker);
-  auto emptyResult =
-      bridging::fromJs<std::vector<uint8_t>>(rt, emptyArrayBuffer, invoker);
-  EXPECT_TRUE(emptyResult.empty());
-
-  // Test OwnedMutableBuffer constructed from size
-  auto sizedBuffer = OwnedMutableBuffer(4);
-  EXPECT_EQ(4, sizedBuffer.size());
-  // Should be zero-initialized
-  auto expected_zeros = std::vector<uint8_t>(4, 0);
-  EXPECT_EQ(0, std::memcmp(sizedBuffer.data(), expected_zeros.data(), 4));
-
-  // Test OwnedMutableBuffer constructed from vector
-  auto inputVec = std::vector<uint8_t>({10, 20, 30});
-  auto vecBuffer = OwnedMutableBuffer(inputVec);
-  EXPECT_EQ(3, vecBuffer.size());
-  EXPECT_EQ(0, std::memcmp(vecBuffer.data(), inputVec.data(), inputVec.size()));
+TEST_F(BridgingTest, borrowedMutableBufferTest) {
+  // Test basic construction and accessors
+  std::vector<uint8_t> source = {1, 2, 3, 4, 5};
+  auto borrowed = BorrowedMutableBuffer(source.data(), source.size());
+  EXPECT_EQ(source.size(), borrowed.size());
+  EXPECT_EQ(source.data(), borrowed.data()); // pointer identity, no copy
+
+  // Test that data is readable through the borrowed pointer
+  EXPECT_EQ(0, std::memcmp(borrowed.data(), source.data(), source.size()));
+
+  // Test mutability through borrowed pointer
+  *borrowed.data() = 99;
+  EXPECT_EQ(99, source[0]); // mutation visible through original
+
+  // Test release callback is invoked on destruction
+  bool released = false;
+  {
+    auto buffer = BorrowedMutableBuffer(
+        source.data(), source.size(), [&released]() { released = true; });
+    EXPECT_FALSE(released);
+  }
+  EXPECT_TRUE(released);
+
+  // Test with nullptr release callback (no-op)
+  {
+    auto buffer = BorrowedMutableBuffer(source.data(), source.size());
+    // Should not crash on destruction
+  }
+
+  // Test zero-copy round-trip through jsi::ArrayBuffer
+  source[0] = 1; // restore
+  auto mutableBuffer =
+      std::make_shared<BorrowedMutableBuffer>(source.data(), source.size());
+  auto originalPtr = mutableBuffer->data();
+  auto arrayBuffer = jsi::ArrayBuffer(rt, std::move(mutableBuffer));
+  EXPECT_EQ(source.size(), arrayBuffer.size(rt));
+  EXPECT_EQ(originalPtr, arrayBuffer.data(rt)); // pointer identity preserved
 }
 
 TEST_F(BridgingTest, highResTimeStampTest) {

packages/react-native/ReactCommon/react/nativemodule/core/platform/android/ReactCommon/JavaTurboModule.cpp

@@ -436,7 +436,7 @@ JNIArgs convertJSIArgsToJNIArgs(
       auto jParams = JDynamicNative::newObjectCxxArgs(dynamicFromValue);
       jarg->l = makeGlobalIfNecessary(jParams.release());
     } else if (type == "Ljava/nio/ByteBuffer;") {
-      if (!arg->isObject()) {
+      if (!arg->isObject() || !arg->getObject(rt).isArrayBuffer(rt)) {
         throw JavaTurboModuleArgumentConversionException(
             "ArrayBuffer", static_cast<int>(argIndex), methodName, arg, &rt);
       }
@@ -992,10 +992,16 @@ jsi::Value JavaTurboModule::invokeJavaMethod(
         auto size = jByteBuffer->getDirectSize();
 
         if (size > 0) {
-          // Copy the data from the ByteBuffer into a new ArrayBuffer.
-          // We must copy because the ByteBuffer's lifetime is managed by Java.
-          auto buffer = std::make_shared<OwnedMutableBuffer>(
-              jByteBuffer->getDirectBytes(), static_cast<size_t>(size));
+          // Zero-copy: wrap the ByteBuffer's memory directly. A JNI global
+          // reference prevents Java GC from collecting the ByteBuffer while
+          // the JS ArrayBuffer is alive. The release callback drops the
+          // global ref when the JS GC collects the ArrayBuffer.
+          auto globalRef = jni::make_global(jByteBuffer);
+          auto data = globalRef->getDirectBytes();
+          auto buffer = std::make_shared<BorrowedMutableBuffer>(
+              data,
+              static_cast<size_t>(size),
+              [prevent_gc = std::move(globalRef)]() { (void)prevent_gc; });
           auto arrayBuffer = jsi::ArrayBuffer(runtime, std::move(buffer));
           returnValue = jsi::Value(runtime, arrayBuffer);
         }

packages/react-native/ReactCommon/react/nativemodule/core/platform/ios/ReactCommon/RCTTurboModule.mm

@@ -102,6 +102,17 @@ static int32_t getUniqueId()
     return convertNSDictionaryToJSIObject(runtime, (NSDictionary *)value);
   } else if ([value isKindOfClass:[NSArray class]]) {
     return convertNSArrayToJSIArray(runtime, (NSArray *)value);
+  } else if ([value isKindOfClass:[NSData class]]) {
+    // Zero-copy: wrap the NSData's memory directly. ARC retains the NSData via
+    // the release callback's block capture, preventing deallocation while the
+    // JS ArrayBuffer is alive. The release callback fires when the JS GC
+    // collects the ArrayBuffer.
+    auto data = (NSData *)value;
+    auto buffer = std::make_shared<BorrowedMutableBuffer>(
+        const_cast<uint8_t *>(static_cast<const uint8_t *>(data.bytes)), data.length, [retainedData = data]() {
+          (void)retainedData;
+        });
+    return {runtime, jsi::ArrayBuffer(runtime, std::move(buffer))};
   } else if (value == (id)kCFNull) {
     return jsi::Value::null();
   }
@@ -197,7 +208,11 @@ id convertJSIValueToObjCObject(
     }
     if (o.isArrayBuffer(runtime)) {
       auto ab = o.getArrayBuffer(runtime);
-      return [NSData dataWithBytes:ab.data(runtime) length:ab.size(runtime)];
+      // Zero-copy: wrap the JS ArrayBuffer's memory without copying.
+      // Safe because this is only called during synchronous argument setup,
+      // and the JS ArrayBuffer is alive for the duration of the call.
+      // freeWhenDone:NO ensures NSMutableData does not free the JS-owned memory.
+      return [NSMutableData dataWithBytesNoCopy:(void *)ab.data(runtime) length:ab.size(runtime) freeWhenDone:NO];
     }
     return convertJSIObjectToNSDictionary(runtime, o, jsInvoker, useNSNull);
   }
@@ -531,9 +546,18 @@ TraceSection s(
     case PromiseKind:
       throw jsi::JSError(runtime, "convertReturnIdToJSIValue: PromiseKind wasn't handled properly.");
     case ArrayBufferKind: {
-      auto data = (NSData *)result;
-      auto buffer = std::make_shared<OwnedMutableBuffer>(static_cast<const uint8_t *>(data.bytes), data.length);
-      returnValue = jsi::ArrayBuffer(runtime, std::move(buffer));
+      auto mutableData = (NSMutableData *)result;
+      if (mutableData != nil && mutableData.length > 0) {
+        // Zero-copy: wrap the NSMutableData's memory directly. ARC retains the
+        // NSMutableData via the release callback's block capture, preventing
+        // deallocation while the JS ArrayBuffer is alive. The release callback
+        // fires when the JS GC collects the ArrayBuffer.
+        auto buffer = std::make_shared<BorrowedMutableBuffer>(
+            static_cast<uint8_t *>(mutableData.mutableBytes), mutableData.length, [retainedData = mutableData]() {
+              (void)retainedData;
+            });
+        returnValue = jsi::ArrayBuffer(runtime, std::move(buffer));
+      }
       break;
     }
   }

packages/rn-tester/NativeCxxModuleExample/NativeCxxModuleExample.cpp

@@ -8,6 +8,7 @@
 #include "NativeCxxModuleExample.h"
 #include <react/bridging/ArrayBuffer.h>
 #include <react/debug/react_native_assert.h>
+#include <cstring>
 #include <iomanip>
 #include <ostream>
 #include <sstream>
@@ -269,10 +270,14 @@ AsyncPromise<> NativeCxxModuleExample::promiseAssert(jsi::Runtime& rt) {
 jsi::ArrayBuffer NativeCxxModuleExample::getArrayBuffer(
     jsi::Runtime& rt,
     jsi::ArrayBuffer arg) {
-  // Return a copy of the input ArrayBuffer
+  // Return a copy of the input ArrayBuffer. We copy into a heap-allocated
+  // vector that is kept alive by the BorrowedMutableBuffer release callback.
   auto size = arg.size(rt);
   auto data = arg.data(rt);
-  auto buffer = std::make_shared<OwnedMutableBuffer>(data, size);
+  auto owned = std::make_shared<std::vector<uint8_t>>(size);
+  std::memcpy(owned->data(), data, size);
+  auto buffer = std::make_shared<BorrowedMutableBuffer>(
+      owned->data(), owned->size(), [owned]() { (void)owned; });
   return {rt, std::move(buffer)};
 }
 

packages/rn-tester/NativeCxxModuleExample/tests/NativeCxxModuleExampleTests.cpp

@@ -35,8 +35,8 @@ TEST_F(NativeCxxModuleExampleTests, GetArrayReturnsCorrectValues) {
 TEST_F(NativeCxxModuleExampleTests, GetArrayBufferReturnsCorrectValues) {
   // Create an ArrayBuffer with known data
   std::vector<uint8_t> inputData = {1, 2, 3, 4, 5};
-  auto inputBuffer =
-      std::make_shared<OwnedMutableBuffer>(inputData.data(), inputData.size());
+  auto inputBuffer = std::make_shared<BorrowedMutableBuffer>(
+      inputData.data(), inputData.size());
   jsi::ArrayBuffer arg(*runtime_, std::move(inputBuffer));
 
   auto result = module_->getArrayBuffer(*runtime_, std::move(arg));
@@ -47,7 +47,7 @@ TEST_F(NativeCxxModuleExampleTests, GetArrayBufferReturnsCorrectValues) {
 }
 
 TEST_F(NativeCxxModuleExampleTests, GetArrayBufferEmptyReturnsEmpty) {
-  auto inputBuffer = std::make_shared<OwnedMutableBuffer>(nullptr, 0);
+  auto inputBuffer = std::make_shared<BorrowedMutableBuffer>(nullptr, 0);
   jsi::ArrayBuffer arg(*runtime_, std::move(inputBuffer));
 
   auto result = module_->getArrayBuffer(*runtime_, std::move(arg));

scripts/cxx-api/api-snapshots/ReactAndroidDebugCxx.api

@@ -1838,6 +1838,15 @@ class facebook::react::BlobModuleJSIBindings : public jni::JavaClass<facebook::r
   public static void registerNatives();
 }
 
+class facebook::react::BorrowedMutableBuffer : public facebook::jsi::MutableBuffer {
+  public BorrowedMutableBuffer(const facebook::react::BorrowedMutableBuffer&) = delete;
+  public BorrowedMutableBuffer(uint8_t* data, size_t size, std::function<void()> release = nullptr);
+  public facebook::react::BorrowedMutableBuffer& operator=(const facebook::react::BorrowedMutableBuffer&) = delete;
+  public virtual size_t size() const override;
+  public virtual uint8_t* data() override;
+  public ~BorrowedMutableBuffer() override;
+}
+
 class facebook::react::BridgelessNativeMethodCallInvoker : public facebook::react::NativeMethodCallInvoker {
   public BridgelessNativeMethodCallInvoker(std::shared_ptr<facebook::react::MessageQueueThread> messageQueueThread);
   public virtual void invokeAsync(const std::string& methodName, facebook::react::NativeMethodCallFunc&& func) noexcept override;
@@ -3909,14 +3918,6 @@ class facebook::react::OperatorAnimatedNode : public facebook::react::ValueAnima
   public OperatorAnimatedNode(facebook::react::Tag tag, const folly::dynamic& config, facebook::react::NativeAnimatedNodesManager& manager);
 }
 
-class facebook::react::OwnedMutableBuffer : public facebook::jsi::MutableBuffer {
-  public OwnedMutableBuffer(const uint8_t* data, size_t size);
-  public OwnedMutableBuffer(size_t size);
-  public OwnedMutableBuffer(std::vector<uint8_t> data);
-  public virtual size_t size() const override;
-  public virtual uint8_t* data() override;
-}
-
 class facebook::react::ParagraphAttributes : public facebook::react::DebugStringConvertible {
   public bool adjustsFontSizeToFit;
   public bool includeFontPadding;
@@ -9467,11 +9468,6 @@ struct facebook::react::Bridging<std::string_view> {
   public static facebook::jsi::String toJs(facebook::jsi::Runtime& rt, std::string_view value);
 }
 
-struct facebook::react::Bridging<std::vector<uint8_t>> {
-  public static facebook::jsi::ArrayBuffer toJs(facebook::jsi::Runtime& rt, const std::vector<uint8_t>& data);
-  public static std::vector<uint8_t> fromJs(facebook::jsi::Runtime& rt, const facebook::jsi::ArrayBuffer& buffer);
-}
-
 template <typename R, typename... Args>
 struct facebook::react::Bridging<std::function<R(Args...)>> {
   public static constexpr size_t kArgumentCount;