JsSharedDataBlock Class

A Shared Data Block (https://tc39.es/ecma262/#sec-data-blocks): the memory of a SharedArrayBuffer. It can be shared by several engines (agents) running on different threads, e.g. by the structured clone of a SharedArrayBuffer sent to a worker. The memory is a managed array allocated once for the maximum byte length on the pinned object heap: a growable block never moves, its byte length grows atomically. The bytes are 16-byte aligned (the atomic operations of 64-bit values are aligned). The spans, references and memories of the block reference the array, so they keep the memory alive by themselves, even once no SharedArrayBuffer references the block.

public sealed class JsSharedDataBlock

Properties

NameDescription
AddressGets the address of the first byte of the block, which never changes: the memory is pinned and allocated for the maximum byte length, so that native code can share it (e.g. the memory of a WebAssembly runtime). The address is valid while the block is alive.
ByteLengthGets the byte length ([[ArrayBufferByteLengthData]], read with the seq-cst order).
IsGrowableGets whether the block is growable.
MaxByteLengthGets the maximum byte length of a growable block, or null for a fixed-length block.
WaitersGets or sets the waiters of another runtime that shares the memory of the block (e.g. a shared WebAssembly memory), which Atomics.wait, Atomics.waitAsync and Atomics.notify then use instead of the waiter lists of the engines; null (the default) for the waiter lists of the engines. Set it before the SharedArrayBuffer objects of the block are given to the scripts: the waiters of the engines are not moved.

Gets the address of the first byte of the block, which never changes: the memory is pinned and allocated for the maximum byte length, so that native code can share it (e.g. the memory of a WebAssembly runtime). The address is valid while the block is alive.

public nint Address { get; }

Property value

nint

Gets the byte length ([[ArrayBufferByteLengthData]], read with the seq-cst order).

public int ByteLength { get; }

Property value

int

Gets whether the block is growable.

public bool IsGrowable { get; }

Property value

bool

Gets the maximum byte length of a growable block, or null for a fixed-length block.

public int? MaxByteLength { get; }

Property value

int?

Gets or sets the waiters of another runtime that shares the memory of the block (e.g. a shared WebAssembly memory), which Atomics.wait, Atomics.waitAsync and Atomics.notify then use instead of the waiter lists of the engines; null (the default) for the waiter lists of the engines. Set it before the SharedArrayBuffer objects of the block are given to the scripts: the waiters of the engines are not moved.

public JsSharedDataBlockWaiters? Waiters { get; set; }

Methods

NameDescription
GetMemory()Gets the bytes of the block (its current byte length) as a Memory<T>, which keeps the memory alive.
GetReference(int)Gets a reference to a byte of the block (for the atomic operations); the index is less than the byte length.
GetReference(int, int)Gets a reference to the first byte of a range of the block, for an access of byteCount bytes (e.g. an atomic operation on a 64-bit value); the range is within the byte length. The first byte of the block is 16-byte aligned, so the alignment of the reference is the alignment of byteIndex.
GetSpan()Gets the bytes of the block (its current byte length).
TryCreate(int, int?)CreateSharedByteDataBlock(size): a zeroed block, or null when the memory cannot be allocated.
TryGrow(int)Grows the block (SharedArrayBuffer.prototype.grow): false when the new length is less than the current length or greater than the maximum byte length. The new bytes are zeroed before the new length is published.
TryGrowBy(int, int)Grows the block by deltaByteLength bytes, and returns its previous byte length, atomically (e.g. the grow(delta) of a shared WebAssembly.Memory: the concurrent calls of several agents each grow the block by their delta). False when the delta is negative or the new length is greater than the maximum byte length. The new bytes are zeroed before the new length is published.

Gets the bytes of the block (its current byte length) as a Memory<T>, which keeps the memory alive.

public Memory<byte> GetMemory()

GetReference overloads

GetReference(int)

JsSharedDataBlock.cs

Gets a reference to a byte of the block (for the atomic operations); the index is less than the byte length.

public ref byte GetReference(int byteIndex)
Parameters
byteIndex int
Returns

byte

GetReference(int, int)

JsSharedDataBlock.cs

Gets a reference to the first byte of a range of the block, for an access of byteCount bytes (e.g. an atomic operation on a 64-bit value); the range is within the byte length. The first byte of the block is 16-byte aligned, so the alignment of the reference is the alignment of byteIndex.

public ref byte GetReference(int byteIndex, int byteCount)
Parameters
byteIndex int
byteCount int
Returns

byte

Exceptions
ArgumentOutOfRangeException
byteCount is not positive, or the range is outside the block.

Gets the bytes of the block (its current byte length).

public Span<byte> GetSpan()

Returns

Span<byte>

TryCreate(int, int?)

JsSharedDataBlock.cs

CreateSharedByteDataBlock(size): a zeroed block, or null when the memory cannot be allocated.

public static JsSharedDataBlock? TryCreate(int byteLength, int? maxByteLength)

Parameters

byteLength int
The initial byte length.
maxByteLength int?
The maximum byte length of a growable block, or null for a fixed-length block.

Returns

JsSharedDataBlock?

Grows the block (SharedArrayBuffer.prototype.grow): false when the new length is less than the current length or greater than the maximum byte length. The new bytes are zeroed before the new length is published.

public bool TryGrow(int newByteLength)

Parameters

newByteLength int

Returns

bool

TryGrowBy(int, int)

JsSharedDataBlock.cs

Grows the block by deltaByteLength bytes, and returns its previous byte length, atomically (e.g. the grow(delta) of a shared WebAssembly.Memory: the concurrent calls of several agents each grow the block by their delta). False when the delta is negative or the new length is greater than the maximum byte length. The new bytes are zeroed before the new length is published.

public bool TryGrowBy(int deltaByteLength, out int previousByteLength)

Parameters

deltaByteLength int
The number of bytes to add to the block.
previousByteLength int
The byte length of the block before it grew; the current byte length when the block cannot grow.

Returns

bool