Struct NativeStream

A set of untyped, append-only buffers. Allows for concurrent reading and concurrent writing without synchronization.

Namespace: Unity.Collections

Syntax

[NativeContainer]
public struct NativeStream : INativeDisposable, IDisposable

Remarks

As long as each individual buffer is written in one thread and read in one thread, multiple threads can read and write the stream concurrently, e.g. while thread A reads from buffer X of a stream, thread B can read from buffer Y of the same stream.

Each buffer is stored as a chain of blocks. When a write exceeds a buffer's current capacity, another block is allocated and added to the end of the chain. Effectively, expanding the buffer never requires copying the existing data (unlike with NativeList<T>, for example).

All writing to a stream should be completed before the stream is first read. Do not write to a stream after the first read. Violating these rules won't necessarily cause any problems, but they are the intended usage pattern.

Writing is done with NativeStream.Writer, and reading is done with NativeStream.Reader. An individual reader or writer cannot be used concurrently across threads: each thread must use its own.

The data written to an individual buffer can be heterogeneous in type, and the data written to different buffers of a stream can be entirely different in type, number, and order. Just make sure that the code reading from a particular buffer knows what to expect to read from it.

Constructors

NativeStream(Int32, AllocatorManager.AllocatorHandle)

Initializes and returns an instance of NativeStream.

Declaration

public NativeStream(int bufferCount, AllocatorManager.AllocatorHandle allocator)

Parameters

Type	Name	Description
Int32	bufferCount	The number of buffers to give the stream. You usually want one buffer for each thread that will read or write the stream.
AllocatorManager.AllocatorHandle	allocator	The allocator to use.

Properties

ForEachCount

The number of buffers in this stream.

Declaration

public readonly int ForEachCount { get; }

Property Value

Type	Description
Int32	The number of buffers in this stream.

IsCreated

Whether this stream has been allocated (and not yet deallocated).

Declaration

public readonly bool IsCreated { get; }

Property Value

Type	Description
Boolean	True if this stream has been allocated (and not yet deallocated).

Remarks

Does not necessarily reflect whether the buffers of the stream have themselves been allocated.

Methods

AsReader()

Returns a reader of this stream.

Declaration

public NativeStream.Reader AsReader()

Returns

Type	Description
NativeStream.Reader	A reader of this stream.

AsWriter()

Returns a writer of this stream.

Declaration

public NativeStream.Writer AsWriter()

Returns

Type	Description
NativeStream.Writer	A writer of this stream.

Count()

Returns the total number of items in the buffers of this stream.

Declaration

public int Count()

Returns

Type	Description
Int32	The total number of items in the buffers of this stream.

Remarks

Each Write<T>(T) and Allocate(Int32) call increments this number.

Dispose()

Releases all resources (memory and safety handles).

Declaration

public void Dispose()

Dispose(JobHandle)

Creates and schedules a job that will release all resources (memory and safety handles) of this stream.

Declaration

public JobHandle Dispose(JobHandle inputDeps)

Parameters

Type	Name	Description
JobHandle	inputDeps	A job handle which the newly scheduled job will depend upon.

Returns

Type	Description
JobHandle	The handle of a new job that will release all resources (memory and safety handles) of this stream.

Implements

INativeDisposable.Dispose(JobHandle)

IsEmpty()

Returns true if this stream is empty.

Declaration

public readonly bool IsEmpty()

Returns

Type	Description
Boolean	True if this stream is empty or the stream has not been constructed.

ScheduleConstruct(out NativeStream, NativeArray<Int32>, JobHandle, AllocatorManager.AllocatorHandle)

Creates and schedules a job to allocate a new stream.

Declaration

public static JobHandle ScheduleConstruct(out NativeStream stream, NativeArray<int> bufferCount, JobHandle dependency, AllocatorManager.AllocatorHandle allocator)

Parameters

Type	Name	Description
NativeStream	stream	Outputs the new stream.
NativeArray<Int32>	bufferCount	An array whose value at index 0 determines the number of buffers in the stream.
JobHandle	dependency	A job handle. The new job will depend upon this handle.
AllocatorManager.AllocatorHandle	allocator	The allocator to use.

Returns

Type	Description
JobHandle	The handle of the new job.

Remarks

The stream can be used...

• after completing the returned job
• or in other jobs that depend upon the returned job.

Allocating the buffers in a job can be more efficient, particularly for a stream with many buffers.

ScheduleConstruct<T>(out NativeStream, NativeList<T>, JobHandle, AllocatorManager.AllocatorHandle)

Creates and schedules a job to allocate a new stream.

Declaration

public static JobHandle ScheduleConstruct<T>(out NativeStream stream, NativeList<T> bufferCount, JobHandle dependency, AllocatorManager.AllocatorHandle allocator)
    where T : struct

Parameters

Type	Name	Description
NativeStream	stream	Outputs the new stream.
NativeList<T>	bufferCount	A list whose length determines the number of buffers in the stream.
JobHandle	dependency	A job handle. The new job will depend upon this handle.
AllocatorManager.AllocatorHandle	allocator	The allocator to use.

Returns

Type	Description
JobHandle	The handle of the new job.

Type Parameters

Name	Description
T	Ignored.

Remarks

The stream can be used on the main thread after completing the returned job or used in other jobs that depend upon the returned job.

Using a job to allocate the buffers can be more efficient, particularly for a stream with many buffers.

ToNativeArray<T>(AllocatorManager.AllocatorHandle)

Returns a new NativeArray copy of this stream's data.

Declaration

public NativeArray<T> ToNativeArray<T>(AllocatorManager.AllocatorHandle allocator)
    where T : struct

Parameters

Type	Name	Description
AllocatorManager.AllocatorHandle	allocator	The allocator to use.

Returns

Type	Description
NativeArray<T>	A new NativeArray copy of this stream's data.

Type Parameters

Name	Description
T	The type of values in the array.

Remarks

The length of the array will equal the count of this stream.

Each buffer of this stream is copied to the array, one after the other.