RFC: ArrayBuffer support in TurboModules

[paradowstack]

Proposal: Adding first-class ArrayBuffer support to Codegen and TurboModules to enable zero-copy binary data exchange between JavaScript and Native modules.

View the rendered RFC

[kraenhansen]

Firstly - congrats on a very thorough and well written RFC!

do we need to implement any additional synchronization mechanism to make this change thread-safe?

It's my understanding that the JS engine and JSI itself isn't thread-safe either.
In which case, I'd consider the limitation of thread-safely for ArrayBuffer an extension of that.

Should we introduce two kinds of buffers, mutable and read-only

I think that could be a nice addition indeed. I'd actually imagine a read-only variant would be used in most cases 🤔

Should this RFC focus on introducing only the basic and most valuable synchronous support for ArrayBuffer

Personally - I'd apply the 80-20 rule here and go for the least amount of work bringing most of the value and stick with the basic sync support.

---

Did you consider "views"? (DataView and typed arrays) and how those would interact with this feature? Could these be passed between JS and Native, if not - what's the failure case like? And should typed arrays be supported in codegen?

[gmemmy]

i really like this. for real-time media or GPU pipelines, say camera ---> ML ---> WebRTC, efficient ArrayBuffer bridging would make a world of difference. it'd enable moving small binary payloads(LUTs, masks, uniform buffers) without having to serialize or clone data just to cross the bridge.

a few things worth clarifying though:

• thread safety: how do concurrent module calls handle shared buffers? media pipelines often run multiple workers in parallel, so locking semantics matter.

• read-only vs writable: some data(e.g frame masks or GPU uploads) should likely be immutable once passed to JS; being explicit here could save a lot of edge-case debugging imo.

[paradowstack]

Firstly - congrats on a very thorough and well written RFC!

Thanks ❤️

do we need to implement any additional synchronization mechanism to make this change thread-safe?

It's my understanding that the JS engine and JSI itself isn't thread-safe either. In which case, I'd consider the limitation of thread-safely for ArrayBuffer an extension of that.

Agree with that.

Should we introduce two kinds of buffers, mutable and read-only

I think that could be a nice addition indeed. I'd actually imagine a read-only variant would be used in most cases 🤔

I agree with that, but after deeper investigation I couldn't find an easy and clean way to achieve that. One way would be to create a read-only view over the buffer when processing it, but that's on the developers. Also there is an active TC39 proposal for an Immutable ArrayBuffer which would provide a standardized, runtime-enforced way to prevent modifications to the buffer contents.

Should this RFC focus on introducing only the basic and most valuable synchronous support for ArrayBuffer

Personally - I'd apply the 80-20 rule here and go for the least amount of work bringing most of the value and stick with the basic sync support.

👍

Did you consider "views"? (DataView and typed arrays) and how those would interact with this feature? Could these be passed between JS and Native, if not - what's the failure case like? And should typed arrays be supported in codegen?

My idea is to have this solution type-agnostic as the underlying native classes, such as NSMutableData, java.nio.ByteBuffer and jsi::ArrayBuffer are an opaque containers for raw, uninterpreted bytes. If DataView or TypedArray is passed instead of ArrayBuffer, the developer should receive an appropriate warning.

[tom-sherman]

The semantics around memory ownership seem to deviate from the spec of ArrayBuffer in regards to transferring/detaching. I'm not sure of what the material consequences are, especially with existing code that handles ArrayBuffers, but it seems like this could break developer expectations in many ways.

I'd expect the buffer to be moved, not borrowed, when passing between JS and native (in both directions).

ArrayBuffer implementations are not thread-safe; if multiple threads simultaneously read from or write to an ArrayBuffer, race conditions can occur. To prevent this, developers must ensure that an ArrayBuffer is not accessed concurrently from different threads

This problem goes away if ownership is moved to the receiving thread. You shouldn't be able to even read an ArrayBuffer from multiple threads.

1. Thread-safety of the ArrayBuffer - do we need to implement any additional synchronization mechanism to make this change thread-safe?

So in summary and to answer this unresolved question, I would say absolutely yes. And to do so by using moves and not borrows.

[paradowstack]

Thanks @tom-sherman for your input!

Regarding this:

ArrayBuffer implementations are not thread-safe; if multiple threads simultaneously read from or write to an ArrayBuffer, race conditions can occur. To prevent this, developers must ensure that an ArrayBuffer is not accessed concurrently from different threads

This problem goes away if ownership is moved to the receiving thread. You shouldn't be able to even read an ArrayBuffer from multiple threads.

1. Thread-safety of the ArrayBuffer - do we need to implement any additional synchronization mechanism to make this change thread-safe?

So in summary and to answer this unresolved question, I would say absolutely yes. And to do so by using moves and not borrows.

I agree that moving (transferring ownership) an ArrayBuffer coul be fundamentally safer and cleaner than borrowing it. However, the primary technical challenge remains: the current JSI and Hermes Runtime implementations do not expose a dedicated API for "detaching" an ArrayBuffer from the JavaScript side. Without true detachment, the only immediate way to transfer ownership is by "moving" the underlying buffer to the native thread and extending its lifetime accordingly. This addresses the memory management aspect but has a critical flaw:

• JS Validity: The ArrayBuffer remains valid on the JS side. Its properties, such as byteLength, are not cleared.
• Thread Safety Risk: The buffer can still be read or written to simultaneously from the JS thread while it is being used natively. This creates an easy opportunity for developers to violate thread-safety rules, even if documentation warns against post-transfer access.

I currently do not see a clean, safe path to fully implement buffer transfers that invalidate the JS reference. Achieving this requires dedicated changes to both the JSI specification and the underlying Hermes engine to introduce a proper detachment mechanism. Since I don't have a deep expertise in this topic, output from more experienced developers is really welcome and highly appreciated.

[gmaclennan]

I don't have any expertise as to how to solve the invalidation of JS references in Hermes and JSI, but I wanted to add another voice highlighting the importance of ownership transfer. As far as I am aware, JS does not have other instances where a developer needs to think about thread-safety - it is always thread safe by default. When working with threads (e.g. a Worker in node or a WebWorker in the browser), references are either copied or transferred (e.g. zero-copy, but the reference is removed in the source thread). A JS developer needing to be aware that they cannot modify an ArrayBuffer while it is being written in the native thread is a big ask, especially as we are likely talking about developers who are consuming native modules which use this code, and may not be familiar with thread-safety as a concept at all. This might be a really hard problem to solve though as @paradowstack says!

[grabbou]

Thanks for this RFC. Excited to get this going. Leaving some comments for consideration when it comes to the RFC document itself.

[grabbou]

Should we extend the RFC with some notes on asynchronous functions? I know there was discussion beforehand whether to implement asynchronous code in the first PR, however, I would treat that separate from the RFC itself, which could cover broader use case.

[paradowstack]

I unnecessarily coupled this RFC with the first PR in my head. Asynchronous functions are mentioned a bit later, but they should be outlined here as well as this is the final API we would like to have.

[grabbou]

I would say current workaround is typically working directly with JSI, which has its own advantages and disadvantages. Great example here is prior art by Marc, who did a lot of this manually before migrating over to Nitro Modules. I also think a lot of Software Mansion libraries go with C++ and work directly with JSI for that reason as well.

[mrousavy]

Yup - both react-native-mmkv (see MMKVManagedBuffer.h) and react-native-vision-camera (see SharedArray.h) use raw JSI access to expose ArrayBuffer data. In VisionCamera I kinda overcomplicated it for a while with TypedArray support (that's primarily for Uint8Array), but still - it's a lot of effort to get right, and even tho I added a ton of code for that, it still has it's bugs. Like thread-safety.
Also; react-native-fast-tflite (see TypedArray.h) and vision-camera-resize-plugin (see ResizePlugin.mm) are using raw JSI ArrayBuffers.

In Nitro, i finally solved all of that - so MMKV benefits from that ✨ for free ✨, but VisionCamera is not on Nitro yet.
I can definitely understand the Motivation here, lol.

[grabbou]

I think great example here would be to use Blob Manager as an example (and likely first candidate to migrate over, once this lands).

Broadly speaking working with binary data in general.

[paradowstack]

Great catch, will add a Blob Manager example to the next version of the RFC.

[grabbou]

The semantics around memory ownership seem to deviate from the spec of ArrayBuffer in regards to transferring/detaching. I'm not sure of what the material consequences are, especially with existing code that handles ArrayBuffers, but it seems like this could break developer expectations in many ways.

That said, it's worth noting that (unless I'm mistaken) this is already how JSI, Expo Modules, and Nitro Modules handle ArrayBuffers today.

On one hand, aligning with existing community behavior might make sense for practical and compatibility reasons. On the other hand, once this behavior becomes part of the core, its reach and visibility will likely expand far beyond those ecosystems, making the current de facto behavior less relevant over time.

Leaving this as an open question and summoning a few folks from the community for feedback!

[javache]

Thanks for putting this together.

Generally, I'm very aligned supporting a type-safe abstraction over the existing ArrayBuffer support in JSI, and there seems to be plenty of use-cases where this would become a good way forward to unlock cheaper data sharing between JS and native.

I agree with the concerns around thread-safety expressed in this thread here. Is there any prior art we can reference? Is the operation model similar to SharedArrayBuffer? Should we consider Atomics as a complementary but necessary capability here?

Making this fully support async JS to native invocation calls will likely increase complexity, as it would require us to keep the JS object alive for the duration of the native memory reference, but not impossible. Alternatively, we'd need to make it really obvious that ArrayBuffer args can only be used in sync calls through codegen.

[javache]

Would recommend we use the existing fbjni abstraction here: https://github.com/facebookincubator/fbjni/blob/main/cxx/fbjni/ByteBuffer.cpp#L84

[paradowstack]

Missed that one - thanks!

[javache]

Why is this so? createArrayBuffer uses a shared_ptr so it should be feasible to implemented shared ownership semantics here.

[mrousavy]

Agreed - ownership can transfer from native to JS here, that's perfectly fine. We use this in a lot of Nitro libraries.

[paradowstack]

I thought that aligning the ownership strategy for both directions would make sense - but of course you are right, it would work fine for case of "native to JS" direction.

[mrousavy]

I really like this RFC - adding ArrayBuffer to react-native core seems like a no-brainer.

I can see that some of this was inspired by Nitro, where we already have nitro::ArrayBuffer (see the ArrayBuffer docs).

I remember implementing ArrayBuffers wasn't super easy, as a lot of work went into the nitro::ArrayBuffer primitives - I think I learned a lot about how this works - I can help with the implementation if any questions arise.

Nitro has owning and non-owning ArrayBuffers, where owning is a native one (we can unwrap that later again), and non-owning is one that was created in JS, or somewhere else.

PROBLEM: If an owning ArrayBuffer (aka one that was created in native) gets passed to JS, and then back from JS to native, the information that it is a native ArrayBuffer gets lost because we don't have .isMutableBuffer() and .getMutableBuffer() in JSI.
I created a feature request for this here: facebook/hermes#1578 - @tmikov said he thinks it's a good idea - I even created a PoC PR that implements this (facebook/hermes#1733), but it's not fully finished - might need a little bit of help here from the Hermes team.

In Nitro, I have a workaround for this by simply attaching a NativeState of the jsi::MutableBuffer pointer to my object (https://github.com/mrousavy/nitro/blob/cffffcb91f90fe4823fa7410bdb39c51c4c99125/packages/react-native-nitro-modules/cpp/jsi/JSIConverter%2BArrayBuffer.hpp#L81-L83) - works very well 😄

But; this means it would not detect owning ArrayBuffers that were created natively in TurboModules, since TurboModules will likely not use nitro::MutableBufferNativeState lol. Not a biggie, it'll just be non-owning.
We need the Hermes PR for native support for that.

[mrousavy]

While in C++ and Objective-C data can be easily shared between JS and Native, Java stores the data as a folly::dynamic map on the Native side.

Yea I found the same issue a while ago - folly is quite cool but wrapping everything in dynamic probably has to go at some point in the future.

[paradowstack]

I agree with the concerns around thread-safety expressed in this thread here. Is there any prior art we can reference?

AFAIK other implementations (such as Nitro Modules or Expo Modules) has similar approach - ownership is not transferred from JS to Native, but borrowed. From what I see thread safety is either manual or ensured by copying the content (e.g. Expo Blob) - I am not aware of the other solution to this problem - happy to be corrected.

Is the operation model similar to Single-ownership model where buffers are either borrowed (JS→Native, sync only) or transferred (Native→JS)? Should we consider Atomics as a complementary but necessary capability here?

The proposed operational model isn't similar to SharedArrayBuffer I would say - there is no synchronisation. It's more single-ownership model where buffers are either borrowed (JS→Native, sync only) or transferred (Native→JS). Can we somehow provide using JSI similar mechanism for safe concurrent access as these primitives offers?

Making this fully support async JS to native invocation calls will likely increase complexity, as it would require us to keep the JS object alive for the duration of the native memory reference, but not impossible. Alternatively, we'd need to make it really obvious that ArrayBuffer args can only be used in sync calls through codegen.

Yes, I can see we can do it either way. Would it also be a applicable solution to the "borrowed" vs "moved" discussion? Instead it can be "shared", by keeping JS object alive. It would not eliminate the thread-safety problems, but perhaps could be another solution to the problem.

[paradowstack]

Thank you all for the feedback and discussion on this RFC! I've updated the proposal.

There are two open questions and fundamental design decisions that need input:

1. Transfer vs. Borrowing Semantics
   The current proposal uses borrowing semantics for JS→Native due to JSI/Hermes API limitations. However, as pointed out, this deviates from web standards and places unusual thread-safety burden on developers. Transfer semantics would solve this but from my understanding requires new JSI/Hermes APIs. Should we proceed with borrowing as a pragmatic interim solution? Do you see the other feasible solutions to the problem?
2. Thread-Safety Model
   Related to the above, we need to decide whether to require manual developer coordination or enforce thread-safety through ownership transfer or some synchronisation mechanism.

I'd appreciate guidance from the core team and community on how to proceed with these questions!

[paradowstack]

@javache did you maybe have time to take a look again at this RFC and open questions once again? 😊

[tmikov]

Here are my general thoughts on the matter, and unfortunately I see a couple of fundamental problems (sorry, I should have joined here earlier):

1. ArrayBuffers are simply not very suitable for passing to asynchronous native code because they can be detached or resized. AFAICT, NodeJS doesn't have any asynchronous APIs that operate on ArrayBuffer precisely for that reason.
2. ArrayBuffers are also not suitable because technically there is nothing preventing the engine from allocating the buffer contents in the GC heap, thus making it movable.
3. Using "transfer" semantics when calling native code would be unusual - after all we are not sending the array to another process or runtime. Again, NodeJS doesn't do that. Designing APIs around unusual techniques is questionable.
4. The threading issue is not a concern. Usually it is not the APIs job to protect a buffer from simultaneous access.

Problem 1 has partial workarounds - you can check whether the buffer is resizable and reject it, but you can't prevent it from becoming asynchronously detached. Problem 2 is basically unsolvable.

This is why NodeJS uses Buffer - it can fully control it.

My recommendation: give up on ArrayBuffer. It simply can never work well because of problem 2. It will always be somewhat of a hack. Use Buffer instead, which is well understood by everybody, compatible with NodeJS, etc, etc.

If you folks are dead-set on ArrayBuffer, I think @mrousavy's proposal for getMutableBuffer() is a solution. If the ArrayBuffer was created by native code as a MutableBuffer, then obtaining a shared_ptr to it gives sufficient guarantees, I think. If it wasn't, it should be rejected at runtime by the API. Personally I don't think that would be a great API, but we are going to add getMutableBuffer() anyway.

[javache]

I'm ok with proceeding here with the constraints @tmikov points out - let's enforce that when we bridge ArrayBuffers originating from JS that these are marked as unmovable (and not supported in async calls) and let's pull in facebook/hermes#1733 to avoid copying data when async scenarios are needed in the native layer.

[javache]

Let's remove support for this until we have getMutableBuffer and can provide a safe variant of this.

[javache]

In this scenario (of a shared_ptr), ownership is shared through ref counting, not transferred.

[paradowstack]

I'm ok with proceeding here with the constraints @tmikov points out - let's enforce that when we bridge ArrayBuffers originating from JS that these are marked as unmovable (and not supported in async calls) and let's pull in facebook/hermes#1733 to avoid copying data when async scenarios are needed in the native layer.

Hi @javache, great to hear you're okay with proceeding with the constraints.
I’m currently tied up with other topics, but when I return to this, I’ll make some small adjustments to the RFC to get it into its final shape.