Table of Contents

Class JCOBridgeDirectBuffer<T>

Namespace
MASES.JCOBridge.C2JBridge
Assembly
C2JBridge.dll

A class to manage shared memory between .NET and JVM using a memory region created from the CLR and shared with the JVM using https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html

public sealed class JCOBridgeDirectBuffer<T> : IJVMBridgeBaseInstance, IEnumerable<T>, IEnumerable, IDisposable where T : unmanaged

Type Parameters

T

The Type to be used: it can be any byte, short, int, long, float, double or a type defined as a struct

Inheritance
JCOBridgeDirectBuffer<T>
Implements
Inherited Members
Extension Methods

Properties

BridgeInstance

The IJavaObject instance

public IJavaObject BridgeInstance { get; }

Property Value

IJavaObject

DynBridgeInstance

The dynamic accessor to BridgeInstance

public dynamic DynBridgeInstance { get; }

Property Value

dynamic

this[long]

Get or set the element at index.

public T this[long index] { get; set; }

Parameters

index long

Property Value

T

JavaObject

The IJavaObject referring to the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html managing the maoping

[Obsolete("Use BridgeInstance instead", true)]
public IJavaObject JavaObject { get; }

Property Value

IJavaObject

Methods

AsSpan()

Returns a zero-copy ReadOnlySpan<T> over the entire buffer, starting at offset zero regardless of the current position.

public ReadOnlySpan<T> AsSpan()

Returns

ReadOnlySpan<T>

A ReadOnlySpan<T> of length buffer size / sizeof(T) backed directly by the native memory buffer.

Exceptions

NotSupportedException

Thrown when the buffer exceeds MaxValue elements. Use CopyTo(IntPtr) for buffers larger than 2 GB.

AsSpanFromIndex(int)

Returns a zero-copy ReadOnlySpan<T> over the buffer starting at the specified element index.

public ReadOnlySpan<T> AsSpanFromIndex(int fromIndex)

Parameters

fromIndex int

Zero-based index of the first element to include in the span.

Returns

ReadOnlySpan<T>

A ReadOnlySpan<T> covering all elements from fromIndex to the end of the buffer, backed directly by the native memory buffer.

Exceptions

ArgumentOutOfRangeException

Thrown when fromIndex is negative or greater than or equal to the element count.

NotSupportedException

Thrown when the number of remaining elements exceeds MaxValue.

AsWritableSpan()

Returns a zero-copy writable Span<T> over the entire buffer, starting at offset zero regardless of the current position.

Contract: if any element is modified through the returned span, FlushOnDispose() MUST be called before Dispose() to ensure changes are written back. Failing to do so results in silent data loss. For single or sparse writes prefer Write(...), which sets the flush flag automatically. 

public Span<T> AsWritableSpan()

Returns

Span<T>

A Span<T> of length buffer limit / sizeof(T) backed directly by the native memory buffer.

Exceptions

NotSupportedException

Thrown when the buffer exceeds MaxValue elements.

AsWritableSpanFromIndex(int)

Returns a zero-copy writable Span<T> over the buffer starting at the specified element index.

Contract: if any element is modified through the returned span, FlushOnDispose() MUST be called before Dispose() to ensure changes are written back. Failing to do so results in silent data loss. For single or sparse writes prefer Write(...), which sets the flush flag automatically. 

public Span<T> AsWritableSpanFromIndex(int fromIndex)

Parameters

fromIndex int

Zero-based index of the first element to include in the span.

Returns

Span<T>

A Span<T> covering all elements from fromIndex to the end of the buffer, backed directly by the native memory buffer.

Exceptions

ArgumentOutOfRangeException

Thrown when fromIndex is negative or greater than or equal to the element count.

NotSupportedException

Thrown when the number of remaining elements exceeds MaxValue.

As<TNew>()

Returns a new instance of JCOBridgeDirectBuffer<T>

public JCOBridgeDirectBuffer<TNew> As<TNew>() where TNew : unmanaged

Returns

JCOBridgeDirectBuffer<TNew>

The new instance of JCOBridgeDirectBuffer<T>

Type Parameters

TNew

The new Type to use

CopyTo(IntPtr, long, long, long)

Fills the destination with a copy of the memory this JCOBridgeDirectBuffer<T> instance is holding from the underlying ByteBuffer. The number of bytes actually copied may be less than length if the remaining bytes from startPosition to the buffer limit or destinationSize are smaller.

public long CopyTo(IntPtr destination, long destinationSize, long startPosition, long length)

Parameters

destination IntPtr

The IntPtr describing the memory pointer data shall be written with the content of the ByteBuffer.

destinationSize long

The available memory size in bytes of destination. Must be positive.

startPosition long

The byte offset within the ByteBuffer where the copy shall start. Must be in the range [0, buffer limit).

length long

The number of bytes to be copied from the ByteBuffer into destination. Must be positive.

Returns

long

The bytes copied.

Exceptions

ObjectDisposedException

This instance has already been disposed.

ArgumentOutOfRangeException

startPosition is negative or greater than or equal to the buffer limit, or destinationSize or length are not positive.

CopyTo(T[], int)

Copies the content of the buffer into destination.

On .NET 5+ and .NET Standard 2.1 dispatches to SIMD hardware intrinsics via AsSpan. On .NET Framework uses Buffer.MemoryCopy directly; if System.Memory is available in the AppDomain the SIMD path is activated automatically — see remarks on CopyTo(T[], int) for loading instructions. 

public void CopyTo(T[] destination, int destinationIndex = 0)

Parameters

destination T[]

The target array.

destinationIndex int

Zero-based start index in destination. Defaults to 0.

Exceptions

ArgumentNullException

destination is null.

ArgumentException

destination is too small.

DisableCleanup()

Disable the internal object clean-up upon Dispose()

public void DisableCleanup()

DisableCleanupAndReturn()

Helper method to execute DisableCleanup() and return the internal IJavaObject

public IJavaObject DisableCleanupAndReturn()

Returns

IJavaObject

The IJavaObject managing the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html

Dispose()

Execute Dispose() activities releasing the underlying .NET memory pinned when the JCOBridgeDirectBuffer<T> was requested

public void Dispose()

Remarks

This method removes the underlying memory and if there are operations in the JVM which needs the memory it is possible to encounter some ACCESS VIOLATIONS. Use this method, or a using clause, only if it is completely clear the risks; otherwise leave the task to the .NET GC which will execute a correct clean-up waiting for JVM that ends usage of the memory

EnableCleanup()

Enable the internal object clean-up upon Dispose()

public void EnableCleanup()

FillWithArray<TArray>(TArray[], long)

Copies the content of array into memory managed from this JCOBridgeDirectBuffer<T> instance

public void FillWithArray<TArray>(TArray[] array, long destinationStartIndex = 0)

Parameters

array TArray[]

The TArray array to be copied

destinationStartIndex long

The start index on destination buffer where to copy

Type Parameters

TArray

The Type to be used: it can be any byte, short, int, long, float, double or a type defined as a struct

~JCOBridgeDirectBuffer()

Finalizer

protected ~JCOBridgeDirectBuffer()

FlushOnDispose()

Marks this stream to flush all native memory changes back to the underlying resource on Dispose().

Must be called after any direct write performed through AsWritableSpan() or AsWritableSpanFromIndex(int) before the stream is closed.

This method is idempotent — calling it multiple times has no additional effect. 

public void FlushOnDispose()

GetEnumerator()

Returns an enumerator that iterates through the collection.

public IEnumerator<T> GetEnumerator()

Returns

IEnumerator<T>

An enumerator that can be used to iterate through the collection.

GetValue(int)

Gets the value at the specified position in the one-dimensional Array. The index is specified as a 32-bit integer.

public T GetValue(int index)

Parameters

index int

A 32-bit integer that represents the position of the Array element to get.

Returns

T

The value at the specified position in the one-dimensional Array.

Exceptions

ArgumentException

The current Array does not have exactly one dimension.

IndexOutOfRangeException

index is outside the range of valid indexes for the current Array.

GetValue(long)

Gets the value at the specified position in the one-dimensional Array. The index is specified as a 64-bit integer.

public T GetValue(long index)

Parameters

index long

A 64-bit integer that represents the position of the Array element to get.

Returns

T

The value at the specified position in the one-dimensional Array.

Exceptions

ArgumentException

The current Array does not have exactly one dimension.

ArgumentOutOfRangeException

index is outside the range of valid indexes for the current Array.

Initialize()

Initializes every element of the value-type Array by calling the default constructor of the value type.

public void Initialize()

SetValue(T, int)

Sets a value to the element at the specified position in the one-dimensional Array. The index is specified as a 32-bit integer.

public void SetValue(T value, int index)

Parameters

value T

The new value for the specified element.

index int

A 32-bit integer that represents the position of the Array element to set.

Exceptions

ArgumentException

The current Array does not have exactly one dimension.

InvalidCastException

value cannot be cast to the element type of the current Array.

IndexOutOfRangeException

index is outside the range of valid indexes for the current Array.

SetValue(T, long)

Sets a value to the element at the specified position in the one-dimensional Array. The index is specified as a 64-bit integer.

public void SetValue(T value, long index)

Parameters

value T

The new value for the specified element.

index long

A 64-bit integer that represents the position of the Array element to set.

Exceptions

ArgumentException

The current Array does not have exactly one dimension.

InvalidCastException

value cannot be cast to the element type of the current Array.

ArgumentOutOfRangeException

index is outside the range of valid indexes for the current Array.

ToArray(ref T[], bool)

Fills array with a reinterpreted copy of the memory this JCOBridgeDirectBuffer<T> instance is holding. Use only when TArray differs from T; for same-type copies prefer CopyTo(T[], int).

public void ToArray(ref T[] array, bool resizeToFill = true)

Parameters

array T[]

The array to be filled with the content of the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html

resizeToFill bool

Resize array to contain all data available in the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html

ToArray<TArray>()

Returns a TArray array which is the copy of the memory this JCOBridgeDirectBuffer<T> instance is holding

public TArray[] ToArray<TArray>()

Returns

TArray[]

A TArray array which is the copy of the memory this instance is holding

Type Parameters

TArray

The Type to be used: it can be any byte, short, int, long, float, double or a type defined as a struct

ToArray<TArray>(ref TArray[], bool)

Fills array with a reinterpreted copy of the memory this JCOBridgeDirectBuffer<T> instance is holding. Use only when TArray differs from T; for same-type copies prefer CopyTo(T[], int).

public void ToArray<TArray>(ref TArray[] array, bool resizeToFill = true)

Parameters

array TArray[]

The array to be filled with the content of the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html

resizeToFill bool

Resize array to contain all data available in the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html

Type Parameters

TArray

The Type to be used: it can be any byte, short, int, long, float, double or a type defined as a struct

ToStream()

Converts this instance to a Stream can be used to manage directly the underlying memory without make intermediate array copy

public Stream ToStream()

Returns

Stream

A new instance of Stream

Operators

implicit operator Stream(JCOBridgeDirectBuffer<T>)

Converts this instance to a Stream can be used to manage directly the underlying memory without make intermediate array copy

public static implicit operator Stream(JCOBridgeDirectBuffer<T> t)

Parameters

t JCOBridgeDirectBuffer<T>

The JCOBridgeDirectBuffer<T> to be converted

Returns

Stream

A Stream

implicit operator T[](JCOBridgeDirectBuffer<T>)

Returns a T array which is the copy of the memory the t instance is holding

public static implicit operator T[](JCOBridgeDirectBuffer<T> t)

Parameters

t JCOBridgeDirectBuffer<T>

The JCOBridgeDirectBuffer<T> to be converted

Returns

T[]

An array of T