Class JNetStream<T>

Namespace

MASES.JNet.Specific

Assembly

MASES.JNet.dll

Helper class of JNet to use JCOBridgeStream<T>

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

Type Parameters

T

Inheritance

object

JNetStream<T>

Implements

IDisposable

IEnumerable<T>

IEnumerable

Extension Methods

JavaUtilExtensions.ToJVMCollectionType<TIterableType, TJVMTypeInner, TNetType>(IEnumerable<TNetType>, Func<TNetType, TJVMTypeInner>)

JavaUtilExtensions.ToJVMCollection<TJVMType, TNetType>(IEnumerable<TNetType>, Func<TNetType, TJVMType>)

JavaUtilExtensions.ToNetArray<TNetType, TJVMType>(IEnumerable<TJVMType>)

JavaUtilExtensions.ToNetCollectionType<TEnumerableType, TNetTypeInner, TJVMType>(IEnumerable<TJVMType>, Func<TJVMType, TNetTypeInner>)

JNetCoreExtensions.DisposeIfDisposable(object)

Remarks

Wraps a JCOBridgeStream<T> instance obtained via ToStream<T>(FileAccess, bool). Dispose behavior, license modes, and performance characteristics are inherited from the underlying stream — see JCOBridgeStream<T> remarks for full details.

When the underlying stream is opened with write access, modifications are written back to the JVM array automatically on Dispose(). Explicit disposal is always preferred over relying on the finalizer.

Under HPA license with forceRawMemory = true, the JVM garbage collector is suspended for the entire lifetime of this instance. No JVM interaction of any kind is permitted while this object is alive. Always use a using block — leaving disposal to the finalizer may result in a deadlock or JVM crash.

Methods relying on ReadOnlySpan<T> (such as AsSpan) are only available on .NET 5 and later, due to a conflict between the System.Memory dependency introduced transitively by Microsoft.IO.RecyclableMemoryStream and the JCOBridge shim on .NET Framework.

Constructors

JNetStream(object, FileAccess, bool, bool)

Initialize an instance of JNetStream<T>

public JNetStream(object source, FileAccess mode = FileAccess.Read, bool forceRawMemory = false, bool disposeSource = true)

Parameters

source object

The object to be converted

mode FileAccess

Specifies the intended access pattern for the returned stream. Use Read (default) for read-only access, Write or ReadWrite when modifications must be written back to the JVM array on Dispose().

forceRawMemory bool

When true, requests direct access to the JVM array memory without any intermediate copy. This option is only effective under a JCOBridge High Performance (HPA) license; with a standard license it is silently ignored. See the remarks section for the behaviour and constraints of each combination.

disposeSource bool

Automatically invoke Dispose() on source

Properties

Count

Gets the number of elements of type T in the stream.

public int Count { get; }

Property Value

int

this[int]

Gets or sets the element at the specified index.

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

Parameters

index int

Zero-based index of the element to access.

Property Value

T

The element of type T at index.

Exceptions

ArgumentOutOfRangeException

index is negative or greater than or equal to Count.

NotSupportedException

The stream is read-only and a set operation was attempted.

Methods

CopyTo(T[], int)

Copies all elements into destination starting at destinationIndex.

On .NET 5+ and .NET Standard 2.1 this operation is backed by ReadOnlySpan<T> and dispatches to SIMD hardware intrinsics with no intermediate allocation. On .NET Framework the copy is performed via MemoryCopy(void*, void*, long, long), which uses the OS-level memcpy implementation and is SIMD-accelerated on all supported platforms without requiring any additional dependency. In both cases no intermediate managed allocation occurs.

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

Parameters

destination T[]

The target array to copy elements into.

destinationIndex int

Zero-based index in destination at which copying begins. Defaults to 0.

Exceptions

ArgumentNullException

destination is null.

ArgumentOutOfRangeException

destinationIndex is negative or greater than or equal to the length of destination.

ArgumentException

destination does not have enough capacity from destinationIndex to hold Count elements.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

FlushOnDispose()

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

Must be called after any direct write performed through AsWritableSpan() or AsWritableSpanFromPosition() 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.

Write(byte[], int, int)

Writes a block of bytes to the current stream using data from a buffer.

public void Write(byte[] buffer, int offset, int count)

Parameters

buffer byte[]

The byte array from which to copy bytes to the current stream.

offset int

The offset in the buffer at which to begin copying bytes to the current stream.

count int

The number of bytes to write to the current stream.

Exceptions

ObjectDisposedException

The stream is closed.

NotSupportedException

The underlying memory does not support writing. - or -An attempt is made to write to the stream and the CanWrite property is false.- or -The count value is greater than the capacity of the stream.- or -The position is at the end of the stream capacity.

IOException

An I/O error occurs.

ArgumentOutOfRangeException

One of the specified parameters is less than zero.

ArgumentException

The offset parameter minus the length of the buffer parameter is less than the count parameter.

ArgumentNullException

The buffer parameter is null.

WriteAsync(byte[], int, int, CancellationToken)

Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests.Available starting in .NET Framework 4.6

public Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)

Parameters

buffer byte[]

The buffer to write data from.

offset int

The zero-based byte offset in buffer from which to begin copying bytes to the stream.

count int

The maximum number of bytes to write.

cancellationToken CancellationToken

The token to monitor for cancellation requests. The default value is None.

Returns

Task

A task that represents the asynchronous write operation.

WriteByte(byte)

Writes a byte to the current position in the file stream.

public void WriteByte(byte value)

Parameters

value byte

A byte value written to the stream.

Exceptions

ObjectDisposedException

The stream is closed.

NotSupportedException

The underlying memory does not support writing.- or -An attempt is made to write to the stream and the CanWrite property is false.- or - The current position is at the end of the capacity of the stream.

IOException

The supplied value causes the stream exceed its maximum capacity.