Struct ScyllaQueueDOTS<T>

Burst/DOTS-compatible fixed-capacity FIFO queue backed by a Unity.Collections.NativeArray<T> circular buffer.

Implements
Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
[BurstCompile]
public struct ScyllaQueueDOTS<T> : IScyllaCollection<T>, IScyllaCollection, IDisposable where T : unmanaged
Type Parameters
Name Description
T

The element type. Must be an unmanaged value type (satisfies the unmanaged constraint) so that the type is safe to store in native memory and accessible from Burst-compiled jobs.
Remarks

Relationship to ScyllaQueue<T>: This type is the DOTS/Burst counterpart of the managed ScyllaQueue<T> class. It is intentionally kept separate so that the managed type can support arbitrary reference types and auto-growing buffers, while this type focuses on zero-allocation, Burst-safe, fixed- capacity operation. Choose ScyllaQueue<T> when you need dynamic growth or reference-type elements; choose ScyllaQueueDOTS<T> when you are working inside Unity jobs or Burst-compiled contexts.

Circular buffer mechanics: The queue maintains a _head pointer (index of the oldest element) and a _tail pointer (index of the next write position). Both advance forward modulo Capacity on every enqueue or dequeue. Unlike ScyllaQueue<T>, this type always uses a modulo expression rather than conditional branches, which is preferred in Burst contexts where branch misprediction can be costly.

Overwrite-on-full mode: When constructed with overwriteOnFull: true, enqueueing into a full queue silently overwrites the oldest element: the new element is written at _tail, both _tail and _head advance by one, and Count stays at Capacity. This matches the ring-buffer semantics of ScyllaRingBufferDOTS<T> and is useful for sliding-window data capture.

Ownership and disposal: This struct owns the Unity.Collections.NativeArray<T> allocated in its constructor. Call Dispose() when the queue is no longer needed to release native memory. Dispose() is idempotent - calling it again after the first call is safe.

Shallow copy hazard: Because this is a struct, assignment creates an alias to the same underlying Unity.Collections.NativeArray<T>. Always pass by reference (ref) or ensure only one copy is active at a time.

Thread safety: Unsynchronized by default, matching the Scylla collection pattern. Use Unity's job system ownership and safety handles for concurrent access. 

// Direct construction - persistent allocator, overwrite-on-full disabled
var queue = new ScyllaQueueDOTS<int>(capacity: 64, allocator: Allocator.Persistent);

// Builder - persistent allocator, overwrite-on-full enabled, zero-initialized memory
var queue = ScyllaQueueDOTS<int>.CreateBuilder()
.WithCapacity(128)
.WithAllocator(Allocator.Persistent)
.OverwriteOnFull()
.WithNativeArrayOptions(NativeArrayOptions.ClearMemory)
.Build();


// Basic FIFO usage
queue.TryAdd(42);
if (queue.TryRemove(out var value))
UnityEngine.Debug.Log(value); // 42


queue.Dispose();

Constructors

ScyllaQueueDOTS(int, Allocator, bool, NativeArrayOptions)

Initializes a new ScyllaQueueDOTS<T> with the specified fixed capacity, allocator, overwrite policy, and native array initialization options.

Declaration
public ScyllaQueueDOTS(int capacity, Allocator allocator, bool overwriteOnFull = false, NativeArrayOptions options = NativeArrayOptions.UninitializedMemory)
Parameters
Type Name Description
int capacity

The fixed number of elements the queue can hold. Values less than 1 are clamped to 1. Unlike ScyllaQueue<T>, this capacity is permanent - the buffer never grows after construction.
Allocator allocator

The Unity native allocator to use for the internal buffer. Must not be Unity.Collections.Allocator.None. Common choices:

  • Unity.Collections.Allocator.Persistent - for queues that live across frames.
  • Unity.Collections.Allocator.TempJob - for queues used within a single-frame job chain.
  • Unity.Collections.Allocator.Temp - for very short-lived queues within a single frame on the main thread.
bool overwriteOnFull

When true, enqueueing into a full queue silently discards the oldest element and writes the new element in its place, so the queue always accepts new items and maintains a sliding window of the most recent capacity elements. When false (the default), TryAdd(T) returns false without modifying the queue when it is full.
NativeArrayOptions options

Native array initialization options forwarded to the Unity.Collections.NativeArray<T> constructor. Use Unity.Collections.NativeArrayOptions.UninitializedMemory (the default) for maximum performance when all slots will be written before being read. Use Unity.Collections.NativeArrayOptions.ClearMemory to zero-initialize the buffer for deterministic initial state.
Exceptions
Type Condition
ArgumentException

Thrown when allocator is Unity.Collections.Allocator.None.

Properties

Capabilities

Gets the feature flags indicating which optional operations this queue supports.

Declaration
public ScyllaCollectionCapabilities Capabilities { get; }
Property Value
Type Description
ScyllaCollectionCapabilities

HasCapacity | SupportsPeek | SupportsCopyTo. Note that SupportsContains is absent because this type does not provide a Contains method (unmanaged types in Burst contexts do not have a standard equality comparer).

Capacity

Gets the fixed capacity of the queue - the maximum number of elements it can hold.

Declaration
public int Capacity { get; }
Property Value
Type Description
int

The length of the underlying Unity.Collections.NativeArray<T>, which equals the value passed to the constructor (clamped to at least 1). Returns 0 when IsCreated is false.

Count

Gets the number of elements currently stored in the queue.

Declaration
public int Count { get; }
Property Value
Type Description
int

A non-negative integer in the range [0, Capacity]. Returns 0 when the queue is empty. In overwrite-on-full mode, this value equals Capacity once the queue has been filled at least once and never decreases below it.

FreeCount

Gets the number of free slots remaining before the queue is full.

Declaration
public int FreeCount { get; }
Property Value
Type Description
int

Capacity - Count when IsCreated is true; 0 otherwise. Useful for determining how many more items can be enqueued before the full-queue policy (OverwriteOnFull) applies.

IsCreated

Gets a value indicating whether the underlying Unity.Collections.NativeArray<T> has been allocated and is ready for use.

Declaration
public bool IsCreated { get; }
Property Value
Type Description
bool

true if the queue was created via the constructor or the builder and Dispose() has not yet been called; false after Dispose() or when the struct is in a default-initialized state. All public methods call Scylla.Core.Structures.ScyllaQueueDOTS<T>.RequireCreated() and throw InvalidOperationException when this property is false.

IsEmpty

Gets a value indicating whether the queue contains no elements.

Declaration
public bool IsEmpty { get; }
Property Value
Type Description
bool

true when Count is 0; false otherwise.

IsFull

Gets a value indicating whether the queue is at full capacity.

Declaration
public bool IsFull { get; }
Property Value
Type Description
bool

true when IsCreated is true and Count equals Capacity. When OverwriteOnFull is true, this condition triggers the overwrite path in TryAdd(T); when false, TryAdd(T) returns false instead.

OverwriteOnFull

Gets a value indicating whether adding to a full queue silently overwrites the oldest element instead of failing.

Declaration
public bool OverwriteOnFull { get; }
Property Value
Type Description
bool

true if the queue was constructed with overwriteOnFull: true. When this is true, TryAdd(T) always returns true - even when the queue is full - and the oldest element is discarded to make room. When false, TryAdd(T) returns false on a full queue without modifying it.

SyncRoot

Gets the synchronization root object for this queue.

Declaration
public object SyncRoot { get; }
Property Value
Type Description
object

Always null. This DOTS type does not support synchronized wrappers. Consult ThreadSafety and Unity's job safety system for concurrency control.

ThreadSafety

Gets the thread-safety level of this queue.

Declaration
public ScyllaCollectionThreadSafety ThreadSafety { get; }
Property Value
Type Description
ScyllaCollectionThreadSafety

Always Unsynchronized. DOTS types do not provide a synchronized wrapper; use Unity's job system scheduling and NativeArray safety handles to coordinate concurrent access.

Methods

Clear()

Removes all elements from the queue and resets it to an empty state without deallocating the underlying native buffer.

Declaration
public void Clear()
Remarks

Resets _head, _tail, and _count to 0. The native buffer is retained at its original capacity and can be reused immediately. For unmanaged value types there are no object references to clear; existing data in the buffer slots is left in place but will be overwritten before it is read again via the normal enqueue/dequeue cycle.

Exceptions
Type Condition
InvalidOperationException

Thrown when IsCreated is false (the queue has not been initialized or has already been disposed).

CopyTo(Span<T>)

Copies elements from the queue into the provided span in FIFO order (oldest element first).

Declaration
public int CopyTo(Span<T> destination)
Parameters
Type Name Description
Span<T> destination

The caller-owned span to receive the elements. If smaller than Count, only the first destination.Length elements are copied and the remainder are silently omitted. An empty span results in zero elements copied.
Returns
Type Description
int

The number of elements copied, equal to min(Count, destination.Length). Returns 0 when the queue is empty or the destination span is zero-length.
Remarks

Uses a per-element loop with modulo arithmetic ((_head + i) % Capacity) rather than two-segment block copy, for Burst compatibility. This is slightly less efficient than the two-segment Copy(Array, Array, int) approach used by the managed CopyTo(Span<T>), but is safe in Burst-compiled code.

Exceptions
Type Condition
InvalidOperationException

Thrown when IsCreated is false.

CopyTo(T[], int)

Copies elements from the queue into the provided array starting at destinationIndex, in FIFO order (oldest element first).

Declaration
public int CopyTo(T[] destination, int destinationIndex)
Parameters
Type Name Description
T[] destination

The array to copy elements into. Must not be null.
int destinationIndex

The zero-based index in destination at which copying begins. Must be in the range [0, destination.Length].
Returns
Type Description
int

The number of elements copied, equal to min(Count, destination.Length - destinationIndex). Returns 0 when the queue is empty or there is no available space at destinationIndex.
Remarks

Uses a per-element loop with modulo arithmetic for Burst compatibility. Prefer the CopyTo(Span<T>) overload in synchronous, non-Burst contexts for slightly cleaner call sites.

Exceptions
Type Condition
ArgumentNullException

Thrown when destination is null.
ArgumentOutOfRangeException

Thrown when destinationIndex is negative or greater than destination.Length.
InvalidOperationException

Thrown when IsCreated is false.

CreateBuilder()

Creates and returns a new fluent ScyllaQueueDOTS<T>.Builder for constructing a ScyllaQueueDOTS<T> with a discoverable, named-parameter configuration API.

Declaration
public static ScyllaQueueDOTS<T>.Builder CreateBuilder()
Returns
Type Description
ScyllaQueueDOTS<T>.Builder

A new ScyllaQueueDOTS<T>.Builder instance initialized with default settings (capacity = 4, no allocator set, overwrite-on-full disabled, Unity.Collections.NativeArrayOptions.UninitializedMemory).
Remarks

WithAllocator(Allocator) must be called before Build() or BuildConcrete(); omitting it causes an InvalidOperationException at build time.

See Also

Dispose()

Releases the underlying Unity.Collections.NativeArray<T> and resets all state fields to their zero values.

Declaration
public void Dispose()
Remarks

This method is idempotent - calling it more than once is safe because it checks IsCreated before attempting to dispose the native array. After disposal, IsCreated returns false and all public methods will throw InvalidOperationException if called.

TryAdd(T)

Attempts to add an item to the back of the queue, applying the overwrite policy when the queue is full. This method implements TryAdd(T) and is the primary enqueue operation for this type.

Declaration
public bool TryAdd(T item)
Parameters
Type Name Description
T item

The unmanaged value to enqueue.
Returns
Type Description
bool

true if the item was successfully added. When OverwriteOnFull is true, this method always returns true - even if the oldest element was discarded to make room. When OverwriteOnFull is false, returns false if the queue is currently full without modifying it.
Remarks

Normal path (queue not full): Writes item at _tail, advances _tail modulo Capacity, and increments _count.

Overwrite path (queue full, OverwriteOnFull is true): Writes item at _tail, advances both _tail and _head by one modulo Capacity (so _head points to the new oldest element), and leaves _count unchanged at Capacity.

Exceptions
Type Condition
InvalidOperationException

Thrown when IsCreated is false.

TryPeek(out T)

Attempts to inspect the oldest (front) element without removing it, implementing TryPeek(out T).

Declaration
public bool TryPeek(out T item)
Parameters
Type Name Description
T item

When this method returns true, contains the element at the front of the queue - the same element that would be returned by the next TryRemove(out T) call, provided no modifications occur in between. When false, contains default(T).
Returns
Type Description
bool

true if an element was available; false if the queue is empty.
Exceptions
Type Condition
InvalidOperationException

Thrown when IsCreated is false.

TryRemove(out T)

Attempts to remove and return the oldest (front) element from the queue, implementing TryRemove(out T).

Declaration
public bool TryRemove(out T item)
Parameters
Type Name Description
T item

When this method returns true, contains the oldest element that was at the front of the queue. When false, contains default(T).
Returns
Type Description
bool

true if an element was successfully dequeued; false if the queue is empty.
Remarks

On success, _head advances by one modulo Capacity and _count is decremented. Unlike the managed TryDequeue(out T), the vacated slot is not cleared to default - for unmanaged value types there are no object references to release.

Exceptions
Type Condition
InvalidOperationException

Thrown when IsCreated is false.

Implements

See Also