#include <Ultralight/js/Buffer.h>

Overview

Handle to a JavaScript ArrayBuffer for sharing raw binary memory with the page.

ArrayBuffer wraps a JavaScript ArrayBuffer, letting native code and page script share raw binary memory without copying. You can pass native memory directly to the page as an ArrayBuffer, or wrap a buffer received from the page.

Share native memory with the page by wrapping a Buffer in an ArrayBuffer:

RefPtr<Buffer> pixels = Buffer::Create(
    pixel_data, pixel_size, nullptr,
    [](void* user_data, void* data) { FreePixels(data); });
ctx["pixels"] = ctx.MakeArrayBuffer(pixels);

Page script accesses the shared memory through a typed array:

const bytes = new Uint8Array(pixels); // the same memory, no copy

Reading Bytes from the Page

Native code accesses the page's bytes through a Buffer that views the memory without copying:

Accept a RefPtr<Buffer> in a bound function. Page script passes an ArrayBuffer as the argument.
Call ShareBytes() on an ArrayBuffer handle. The method returns a Buffer for an ArrayBuffer you already hold.

Access the bytes from native code:

app["upload"] = [](RefPtr<Buffer> bytes) { Enqueue(bytes); };
 
js::ArrayBuffer save(ctx["saveData"]);  // empty if it isn't an ArrayBuffer
RefPtr<Buffer> save_bytes = save.ShareBytes();

Detaching an ArrayBuffer

Call Detach() to take shared bytes back from the page early so JavaScript can no longer reach the memory.

Once native code reads the bytes (by calling ShareBytes(), receiving a RefPtr<Buffer> or std::span parameter in a bound function, or calling TypedArray::view()), the ArrayBuffer can no longer be detached by native code or by the page, including an ArrayBuffer created from your own Buffer. Calling Detach() then returns false.

Byte Lifetimes

A native Buffer shared with the page follows these lifetime rules:

Shared buffers stay referenced until collection or detachment. The library releases its reference during a later Renderer::Update() after the ArrayBuffer is garbage collected or detached.
The destruction callback runs where the last reference is released. That happens during Renderer::Update() if the ArrayBuffer held the last reference, or wherever native code drops its last one.

Warning: Bytes owned by the page are freed when the page goes away, even while native code holds a Buffer over them. Use Buffer::CreateFromCopy() if the data must outlive the page.

See also: js::Context::MakeArrayBuffer(), js::TypedArray, Buffer::Create(), Buffer::CreateFromCopy()

Inheritance diagram for ArrayBuffer:

Public Member Functions
	ArrayBuffer ()=default
	Create an empty ArrayBuffer wrapper.
	ArrayBuffer (const Value &value)
	Wrap a value if it's an ArrayBuffer (detached ones included), otherwise create an empty wrapper.
RefPtr< ultralight::Buffer >	ShareBytes () const
	Share this ArrayBuffer's bytes with native code without copying.
size_t	byte_length () const
	Get the length in bytes.
bool	Detach () const
	Detach this ArrayBuffer so JavaScript can no longer reach its bytes.
Public Member Functions inherited from Value
	Value ()
	Create an empty Value.
	Value (const Value &other)
	Copy constructor (adds a reference to the same JavaScript value).
	Value (Value &&other) noexcept
	Move constructor (other becomes empty).
Value &	operator= (Value other) noexcept
	Assignment (copies or moves other into this Value).
	~Value ()
	Destructor (releases this handle).
	operator bool () const
	Whether or not this Value is valid (it isn't empty and its page is still alive).
bool	IsEmpty () const
	Whether or not this Value holds nothing (see "Handle States" above).
bool	IsAlive () const
	Whether or not this Value's page is still alive (the same test as operator bool).
Type	type () const
	Get the type of the value.
bool	IsUndefined () const
	Whether or not the value is undefined.
bool	IsNull () const
	Whether or not the value is null.
bool	IsNullish () const
	Whether or not the value is null or undefined.
bool	IsBoolean () const
	Whether or not the value is a boolean.
bool	IsNumber () const
	Whether or not the value is a number.
bool	IsBigInt () const
	Whether or not the value is a BigInt (eg, 10n).
bool	IsString () const
	Whether or not the value is a string.
bool	IsObject () const
	Whether or not the value is an object.
bool	IsArray () const
	Whether or not the value is an Array.
bool	IsCallable () const
	Whether or not the value can be called (see Call() and Invoke()).
bool	IsFunction () const
	Whether or not the value is a function.
bool	IsPromise () const
	Whether or not the value is a Promise.
Result< bool >	ToBoolean () const
	Convert to a boolean using JavaScript's rules (this never runs script).
Result< double >	ToNumber () const
	Convert to a number using JavaScript's rules.
Result< std::string >	ToString () const
	Convert to a UTF-8 string using JavaScript's rules.
Result< std::string >	ToJSON (unsigned indent=0) const
	Convert to JSON text like JSON.stringify() does.
Result< Value >	GetProperty (const char *name) const
	Get a property of this object (own or inherited).
bool	Has (const char *name) const
	Whether or not this object has a property (own or inherited).
Result< bool >	HasProperty (const char *name) const
	Whether or not this object has a property (like Has(), but reports failures).
Result< void >	SetProperty (const char *name, const Value &value, PropertyAttributes attributes=PropertyAttributes::None) const
	Set a property of this object.
Result< Value >	Call (const Value &this_value, const Value *args, size_t argc) const
	Call this value as a function.
Result< Value >	Call (const Value &this_value, std::span< const Value > args) const
	Call this value as a function with the arguments in a range (eg, a std::vector<js::Value>).
template<typename T>
Result< T >	To () const
	Convert to a C++ type.
template<typename T>
std::optional< T >	Maybe () const
	Convert to a C++ type like To() but without the failure reason.
template<typename T>
T	Or (T fallback) const
	Convert to a C++ type like To() but with a fallback.
std::string	Or (const char *fallback) const
	Convert to a std::string like To() but with a string-literal fallback.
template<typename R = Value, typename... A>
Result< R >	Invoke (A &&... args) const
	Call this value as a function with typed arguments and result.
template<typename R = Value, typename... A>
Result< R >	InvokeOn (const Value &this_value, A &&... args) const
	Call this value as a function with an explicit this (otherwise the same as Invoke()).
template<typename... A>
Result< Value >	operator() (A &&... args) const
	Call this value as a function: on_save(path) is the same as on_save.Invoke(path).
template<typename F>
bool	Then (F &&on_settled) const
	Wait for this promise to settle without a coroutine.
template<typename T, typename F> requires (!std::is_same_v<T, Value>)
bool	Then (F &&on_settled) const
	Wait for this promise to settle and convert its value to a C++ type.
Ref	operator[] (const char *name) const
	Access a property to read, assign, or call it.
template<typename I> requires (std::is_integral_v<I> && !std::is_same_v<I, bool>)
Ref	operator[] (I index) const
ULJSValue	raw () const
	Get the C API handle without transferring ownership.
ULJSValue	LeakRef ()
	Give up ownership of the C API handle and return it (like RefPtr::LeakRef()).

Additional Inherited Members
Static Public Member Functions inherited from Value
static Value	Adopt (ULJSValue handle)
	Take ownership of a handle from the C API without adding a reference.
static Value	FromBorrowed (ULJSValue handle)
	Add a reference to a handle the library owns (eg, a callback argument) so it can outlive the callback.
Protected Member Functions inherited from Value
	Value (ULJSValue handle)

Constructor & Destructor Documentation

◆ ArrayBuffer() [1/2]

ArrayBuffer ( )

default

Create an empty ArrayBuffer wrapper.

◆ ArrayBuffer() [2/2]

ArrayBuffer ( const Value & value )

inlineexplicit

Wrap a value if it's an ArrayBuffer (detached ones included), otherwise create an empty wrapper.

Parameters

value The value to wrap.

Member Function Documentation

◆ byte_length()

size_t byte_length ( ) const

inline

Get the length in bytes.

The ArrayBuffer can still be detached.

Returns: Returns the byte length (0 if the ArrayBuffer is detached or the wrapper is empty).

◆ Detach()

bool Detach ( ) const

inlinenodiscard

Detach this ArrayBuffer so JavaScript can no longer reach its bytes.

Afterwards its byteLength is 0, typed arrays over it have length 0 (element reads return undefined), and creating a new typed array over it throws a TypeError. If it was created from a Buffer, its reference to that Buffer is released during a later Renderer::Update().

Returns: Returns true if the ArrayBuffer is detached on return (including one that was already detached). Returns false if it can no longer be detached or the wrapper is empty.

◆ ShareBytes()

RefPtr< ultralight::Buffer > ShareBytes ( ) const