RCTArrayBuffer zero-copy class for ObjC TM (#57879)

Summary:
iOS TurboModules mapped a JS `ArrayBuffer` to `NSData` on arguments and `NSMutableData` on returns, so every crossing copied — and `NSMutableData` cannot alias foreign memory, so there was no way to express "these bytes live somewhere else".

This adds `RCTArrayBuffer` (`packages/react-native/React/Base/`) as the ObjC representation of an `ArrayBuffer`. It carries an `isOwningBytes` flag: an owning buffer can be stored and read from any thread, a non-owning one aliases bytes valid only for the synchronous call that produced it.

Codegen now emits `RCTArrayBuffer *` for `ArrayBufferTypeAnnotation` params (was `NSData *`) and returns (was `NSMutableData *`).

## Changelog:

[IOS] [BREAKING] - Add `RCTArrayBuffer`, the ObjC representation of a JS `ArrayBuffer` for TurboModules, with an explicit byte-ownership contract

Pull Request resolved: #57879

Test Plan:
- `RCTTurboModuleArrayBufferTests` — 9 tests over the sync in-place path, `isOwningBytes` on a sync argument, returning one's own argument, the void/Promise copy paths, nesting, and a zero-length round trip.
 - `RCTTurboModuleTests.mm` adds `testNativeBackedArrayBufferIsAliasedAndKeepsBackingStoreAlive`.
 -  `RCTSampleTurboModule` doubles its argument in place and returns the same buffer, covering the path end to end.
 - Codegen and C++ API snapshots regenerated.

Differential Revision: D115629409

Author: Kamil Paradowski

packages/react-native-codegen/e2e/deep_imports/__tests__/modules/__snapshots__/GenerateModuleObjCpp-test.js.snap

@@ -26,6 +26,7 @@ exports[`GenerateModuleObjCpp can generate a header file NativeModule specs 1`]
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>
@@ -1578,6 +1579,7 @@ exports[`GenerateModuleObjCpp can generate a header file NativeModule specs with
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>

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

@@ -97,6 +97,7 @@ const HeaderFileTemplate = ({
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>

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

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

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

@@ -27,6 +27,7 @@ Map {
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>
@@ -92,6 +93,7 @@ Map {
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>
@@ -102,9 +104,9 @@ Map {
 
 @protocol NativeSampleTurboModuleSpec <RCTBridgeModule, RCTTurboModule>
 
-- (NSMutableData *)getArrayBuffer;
-- (void)voidArrayBuffer:(NSData *)arg;
-- (void)voidNullableArrayBuffer:(NSData * _Nullable)arg;
+- (RCTArrayBuffer *)getArrayBuffer;
+- (void)voidArrayBuffer:(RCTArrayBuffer *)arg;
+- (void)voidNullableArrayBuffer:(RCTArrayBuffer * _Nullable)arg;
 
 @end
 
@@ -159,6 +161,7 @@ Map {
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>
@@ -200,6 +203,7 @@ Map {
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>
@@ -475,6 +479,7 @@ Map {
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>
@@ -516,6 +521,7 @@ Map {
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>
@@ -581,6 +587,7 @@ Map {
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>
@@ -651,6 +658,7 @@ Map {
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>
@@ -836,6 +844,7 @@ Map {
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>
@@ -1104,6 +1113,7 @@ Map {
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>
@@ -1233,6 +1243,7 @@ Map {
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>
@@ -1298,6 +1309,7 @@ Map {
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>
@@ -1389,6 +1401,7 @@ Map {
 #import <RCTRequired/RCTRequired.h>
 #import <RCTTypeSafety/RCTConvertHelpers.h>
 #import <RCTTypeSafety/RCTTypedModuleConstants.h>
+#import <React/RCTArrayBuffer.h>
 #import <React/RCTBridgeModule.h>
 #import <React/RCTCxxConvert.h>
 #import <React/RCTManagedPointer.h>

packages/react-native/React/Base/RCTArrayBuffer.h

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * A fixed-length byte buffer shared between JS `ArrayBuffer`s and ObjC TurboModules. Fixed
+ * length lets the backing store alias JS memory; `NSMutableData` cannot do that.
+ *
+ * `isOwningBytes`:
+ *  - `YES` — safe to retain and use from any thread (synchronize if aliasing JS
+ *     memory).
+ *  - `NO` — valid only during the synchronous call on the calling thread; copy with
+ *    `arrayBufferWithCopiedBytes:length:` to keep the bytes.
+ */
+@interface RCTArrayBuffer : NSObject
+
+/**
+ * NULL when `length` is 0, non-NULL otherwise, matching `NSData.bytes`.
+ */
+@property (nonatomic, readonly, nullable) void *mutableBytes NS_RETURNS_INNER_POINTER;
+
+@property (nonatomic, readonly) NSUInteger length;
+
+/** Whether the buffer owns its bytes. See the class comment. */
+@property (nonatomic, readonly, getter=isOwningBytes) BOOL owningBytes;
+
+/**
+ * A new zero-filled owning buffer.
+ */
++ (instancetype)arrayBufferWithLength:(NSUInteger)length;
+
+/**
+ * A new owning buffer holding a copy of `bytes`. Passing NULL zero-fills.
+ */
++ (instancetype)arrayBufferWithCopiedBytes:(const void *_Nullable)bytes length:(NSUInteger)length;
+
+/**
+ * An owning buffer aliasing `bytes` without copying. If `cleanup` is non-nil, it runs on dealloc,
+ * like `-[NSData dataWithBytesNoCopy:length:freeWhenDone:YES]`; if nil, the caller must keep
+ * `bytes` valid until dealloc. NULL `bytes` with non-zero `length` raises NSInvalidArgumentException.
+ */
++ (instancetype)arrayBufferWithOwnedBytes:(nullable void *)bytes
+                                   length:(NSUInteger)length
+                                  cleanup:(nullable void (^)(void))cleanup;
+
+/**
+ * A non-owning, zero-copy alias of `bytes`. See the class comment for lifetime rules. NULL `bytes`
+ * with non-zero `length` raises NSInvalidArgumentException.
+ */
++ (instancetype)arrayBufferWithUnownedBytes:(nullable void *)bytes length:(NSUInteger)length;
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+@end
+
+NS_ASSUME_NONNULL_END

packages/react-native/React/Base/RCTArrayBuffer.mm

@@ -0,0 +1,127 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "RCTArrayBuffer.h"
+
+#include <cstdint>
+#include <cstring>
+#include <utility>
+#include <vector>
+
+@interface RCTArrayBuffer ()
+
+- (instancetype)initWithBytesNoCopy:(nullable void *)bytes
+                             length:(NSUInteger)length
+                        owningBytes:(BOOL)owningBytes
+                            cleanup:(nullable void (^)(void))cleanup NS_DESIGNATED_INITIALIZER;
+- (instancetype)initWithCopiedBytes:(const void *_Nullable)bytes length:(NSUInteger)length;
+
+@end
+
+@implementation RCTArrayBuffer {
+  void *_bytes;
+  NSUInteger _length;
+  BOOL _owningBytes;
+  void (^_cleanup)(void);
+  std::vector<uint8_t> _copiedBytes;
+}
+
+#pragma mark - Initializers
+
+- (instancetype)initWithBytesNoCopy:(void *)bytes
+                             length:(NSUInteger)length
+                        owningBytes:(BOOL)owningBytes
+                            cleanup:(void (^)(void))cleanup
+{
+  if (bytes == NULL && length != 0) {
+    [NSException raise:NSInvalidArgumentException
+                format:@"RCTArrayBuffer: NULL bytes with length %lu", (unsigned long)length];
+  }
+
+  if (self = [super init]) {
+    _bytes = bytes;
+    _length = length;
+    _owningBytes = owningBytes;
+    _cleanup = [cleanup copy];
+  }
+  return self;
+}
+
+- (instancetype)initWithCopiedBytes:(const void *)bytes length:(NSUInteger)length
+{
+  if (length == 0) {
+    return [self initWithBytesNoCopy:NULL length:0 owningBytes:YES cleanup:nil];
+  }
+
+  std::vector<uint8_t> copy(length);
+  if (bytes != NULL) {
+    std::memcpy(copy.data(), bytes, length);
+  }
+
+  // Moving a vector hands over its heap buffer, so `data()` stays valid in `_copiedBytes`.
+  if (self = [self initWithBytesNoCopy:copy.data() length:length owningBytes:YES cleanup:nil]) {
+    _copiedBytes = std::move(copy);
+  }
+  return self;
+}
+
++ (instancetype)arrayBufferWithLength:(NSUInteger)length
+{
+  return [[self alloc] initWithCopiedBytes:NULL length:length];
+}
+
++ (instancetype)arrayBufferWithCopiedBytes:(const void *)bytes length:(NSUInteger)length
+{
+  return [[self alloc] initWithCopiedBytes:bytes length:length];
+}
+
++ (instancetype)arrayBufferWithOwnedBytes:(void *)bytes
+                                   length:(NSUInteger)length
+                                  cleanup:(nullable void (^)(void))cleanup
+{
+  return [[self alloc] initWithBytesNoCopy:bytes length:length owningBytes:YES cleanup:cleanup];
+}
+
++ (instancetype)arrayBufferWithUnownedBytes:(void *)bytes length:(NSUInteger)length
+{
+  return [[self alloc] initWithBytesNoCopy:bytes length:length owningBytes:NO cleanup:nil];
+}
+
+#pragma mark - Accessors
+
+- (void *)mutableBytes
+{
+  return _bytes;
+}
+
+- (NSUInteger)length
+{
+  return _length;
+}
+
+- (BOOL)isOwningBytes
+{
+  return _owningBytes;
+}
+
+- (NSString *)description
+{
+  return [NSString stringWithFormat:@"<%@: %p; length = %lu; owningBytes = %@>",
+                                    NSStringFromClass([self class]),
+                                    self,
+                                    (unsigned long)_length,
+                                    _owningBytes ? @"YES" : @"NO"];
+}
+
+- (void)dealloc
+{
+  if (_cleanup != nil) {
+    _cleanup();
+  }
+}
+
+@end