JCOBridgeStreamT Class

public class JCOBridgeStream<T> : UnmanagedMemoryStream, 
	IEnumerable<T>, IEnumerable
where T : struct, new()

Public Class JCOBridgeStream(Of T As {Structure, New})
	Inherits UnmanagedMemoryStream
	Implements IEnumerable(Of T), IEnumerable

Type Parameters

T

The .NET primitive type corresponding to the element type of this IJavaArray. Supported types reflect the JVM primitive type system:

JVM type	.NET type
boolean	bool
byte	byte
short	short
int	int
long	long
float	float
double	double
char	char

Unsigned types (sbyte, ushort, uint, ulong) are not supported as they have no equivalent in the JVM type system. Passing an unsupported type throws NotSupportedException at runtime; passing a type inconsistent with the actual JVM array element type throws InvalidOperationException.

Instances of this class must be obtained through ToStreamT(FileAccess, Boolean); direct instantiation is not supported.

Standard license. The stream operates on a local copy of the JVM array data, consistent with the snapshot already available from ToArray. There are no constraints on JVM interaction or stream lifetime. When opened with write access, any modifications are written back to the JVM array automatically on Dispose. If Dispose is not called explicitly, the finalizer ensures cleanup without adverse effects, though explicit disposal is always preferred.

HPA license — standard access (forceRawMemory = false). The JVM runtime may expose a direct pointer or an internal copy depending on its implementation; in both cases the GC runs freely and JVM interaction is unrestricted. Dispose should be called promptly to release the JVM resource; relying on the finalizer is discouraged as it keeps the resource held for an indeterminate time.

HPA license — raw memory access (forceRawMemory = true). The JVM garbage collector is suspended for the entire lifetime of this stream. No JVM interaction of any kind is permitted while the stream is alive (no object allocation, no method calls, no blocking operations). Dispose is mandatory, must be invoked immediately after the memory operation completes, and must not be left to the finalizer. Violating these constraints may result in a deadlock or a JVM crash. Always use a using block.

Performance characteristics. Per-element access through ItemInt32 or IEnumerableT on JVM-resident memory is inherently slower than equivalent access on a managed .NET array. The JVM heap and the CLR managed heap occupy separate physical memory regions; each element access risks a TLB miss or CPU cache miss because the hardware prefetcher has no prior knowledge of those pages. A managed array, by contrast, is warm in the CPU cache immediately after any copy and benefits from hardware prefetching and JIT optimisations on subsequent accesses.

This class is therefore most appropriate when the buffer is large enough that copying it into managed memory would be prohibitively expensive in time or space (typically hundreds of MB or more), and the access pattern is sparse or random so that only a small fraction of elements are actually read or written. When the entire buffer must be scanned or compared, prefer AsSpan combined with MemoryExtensions.SequenceEqual{T}(ReadOnlySpan{T}, ReadOnlySpan{T}) or another single-pass SIMD operation, which amortises the cache-miss cost over one contiguous traversal. For repeated access to the same data, a local copy via ArrayPool<T>.Shared.Rent is faster overall.

Reference