Alignment or initialization requirements for Node-API external buffers

[overlookmotel]

Affected URL(s)

https://nodejs.org/dist/latest-v19.x/docs/api/n-api.html#napi_create_external_arraybuffer

Description of the problem

I am wondering if there are any requirements not stated in the docs for napi_create_external_buffer / napi_create_external_arraybuffer:

1. Is there an alignment requirement for pointers passed to napi_create_external_buffer etc?
2. If not, is there still a performance penalty for misalignment?
3. Must the memory which is used for the buffer be initialized?

On JS side alignment does not appear to be enforced - new DataView(new ArrayBuffer(8)).setUint32(1, 255) works fine.

However, all new ArrayBuffers created in JS appear to have their allocations aligned on 16 (at least on my Mac OS machine). So I wonder if a certain alignment allows optimal performance? Maybe, for example, reading a series of 4 x Uint16s is faster if buffer is aligned to at least 8?

Concerning whether memory should be initialized, I assume it doesn't have to be, since NodeJS provides a facility for this Buffer.allocUnsafe.

Either way, it'd be great if the requirements (or lack thereof) could be made explicit in the docs).

I couldn't find any comments in Node's source code which answer these questions, or I'd be making a PR for the docs, not opening an issue!

[parmishh]

There is no strict alignment requirement for pointers passed to napi_create_external_buffer.. However, it is generally a good practice to align data structures to improve performance, especially on architectures with strict alignment requirements. Misaligned data access can result in performance penalties, such as extra memory accesses..

As for initializing the memory used for the buffer, it is not strictly necessary, but it is recommended to avoid potential issues with uninitialized memory.

[overlookmotel]

Thanks for coming back. Can I ask: is your reply based on specific knowledge of the inner workings of Node-API/V8, or advice on good practice more generally?

If the first, could you possibly point me in the direction of what in the code base (or perhaps a comment from one of the maintainers in another issue) gives you confidence in these conclusions (as they apply specifically to Node-API)?

[parmishh]

The answer is based on my experience and I have read about it somewhere but currently unable to locate where. But a comment from a maintainer would be great. You can tag the maintainers to comment on this.

[questgugou]

thankyou

[bnoordhuis]

Is there an alignment requirement for pointers passed to napi_create_external_buffer etc?

Not for arraybuffers but there is (or can be) when the arraybuffer is used to back a typed array.

If not, is there still a performance penalty for misalignment?

Yes. Even on e.g. x86_64, where misaligned loads and stores are usually free, except when they cross a cache line boundary.

Must the memory which is used for the buffer be initialized?

Yes. GIGO.

[overlookmotel]

Thanks very much for your reply. One more question concerning initialization:

If some bytes in the memory backing the ArrayBuffer are initialized, is it safe to read only those bytes on JS side?

To hopefully make the question clearer, here's the context:

I'm trying to build a serializer in Rust which copies Rust types into a block of memory, and I'd like to pass that data to JS as an ArrayBuffer.

use std::{mem, ptr};

// Foo has size of 8 bytes, but last 3 bytes are uninitialized padding
#[repr(C)]
struct Foo {
  big: u32,
  small: u8,
}

const SIZE_OF_FOO: usize = mem::size_of::<Foo>();

let foo = Foo { big: 0x01020304, small: 5 };

let mut bytes = Box::new([mem::MaybeUninit::<u8>::uninit(); SIZE_OF_FOO]);
let bytes_ptr = bytes.as_mut_ptr();
ptr::copy_nonoverlapping(&foo as *const Foo, bytes_ptr as *mut Foo, 1);
mem::forget(bytes);
// `bytes` now contains a copy of `foo`. 1st 5 bytes initalized, last 3 not.

If a bytes_ptr is passed to napi_create_external_array_buffer, can the resulting ArrayBuffer be safely read from on JS side, if the uninitialized bytes are not touched?

let big = new Uint32Array(buf)[0];
let small = new Uint8Array(buf)[4];
assert( big === 0x01020304 );
assert( small === 5 );

And if the uninitialized bytes are read from, does that produce memory unsafety, or will it just return unpredictable values?

Basically, I'm asking how/if Rust's rules around uninitialized memory do/don't translate to Node-API + JS.

I assume Node can deal with uninitialized memory on some level, since there's an API specifically for it Buffer.allocUnsafe().

(apologies example above is in Rust. C++ would probably be clearer, but I don't "speak" C++)

[overlookmotel]

By the way, reason I opened this as an issue, rather than a discussion, is I felt it'd be useful if the answer (whatever it is) was added to the docs. I'd be happy to make a docs PR.

[bnoordhuis]

Yes, that's safe. It's even safe when you create e.g. a Float32Array out of uninitialized memory. V8 canonicalizes nans and infinities so you'll always see "the" NaN and "the" +Infinity or -Infinity in your JS code.

Pull request welcome, of course. :-)