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 : IDisposableRemarks
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. |
IsEmpty()
Returns true if this stream is empty.
Declaration
public 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 : structParameters
| 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 : structParameters
| 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.