Struct ScyllaDequeDOTS<T>

Burst- and DOTS-compatible fixed-capacity double-ended queue (deque) backed by a Unity.Collections.NativeArray<T> circular buffer. Supports O(1) push and pop at both ends with optional overwrite-on-full eviction semantics.

Implements

IScyllaCollection<T>

IScyllaCollection

IDisposable

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Structures

Assembly: ScyllaCore.dll

Syntax

[BurstCompile]
public struct ScyllaDequeDOTS<T> : IScyllaCollection<T>, IScyllaCollection, IDisposable where T : unmanaged

Type Parameters

Name	Description
T	The element type. Must satisfy the `unmanaged` constraint so the struct is safe to use from Burst-compiled jobs. No managed references (classes, arrays, delegates) are permitted.

Remarks

Circular buffer layout: internally the deque maintains a Unity.Collections.NativeArray<T> together with a _head index (pointing to the current front element) and a _tail index (pointing to the first free slot past the back element). All index arithmetic is performed modulo the buffer length so the buffer wraps around correctly.

Fixed capacity: unlike the managed ScyllaDeque<T>, this struct never grows. The capacity is fixed at construction time. When the deque is full, the behavior depends on the OverwriteOnFull flag:

OverwriteOnFull = false (default): push operations return false and no element is added.
OverwriteOnFull = true: the element at the opposite end is silently evicted to make room. Pushing to the front evicts the current back element; pushing to the back evicts the current front. The operation always returns true.

Lifetime management: because this type wraps a Unity.Collections.NativeArray<T>, it must be explicitly disposed when no longer needed. Call Dispose() or wrap usage in a using statement to release the native memory. Check IsCreated before calling any method; all public methods (except Dispose()) call Scylla.Core.Structures.ScyllaDequeDOTS<T>.RequireCreated() and throw InvalidOperationException if the buffer has not been allocated or has already been disposed.

IScyllaCollection convention: TryAdd(T) delegates to TryPushBack(T) and TryRemove(out T) delegates to TryPopFront(out T), so this deque behaves as a FIFO queue when accessed through the abstract interface. Use the explicit TryPush* / TryPop* methods for stack or double-ended access patterns.

Thread safety: this struct is unsynchronized. Do not access it concurrently from multiple threads without external synchronization. In Unity job contexts, assign it to a single job at a time.

// Direct construction
var deque = new ScyllaDequeDOTS<int>(capacity: 64, allocator: Allocator.Persistent);
// Using fluent builder
var deque = ScyllaDequeDOTS<int>.CreateBuilder()
    .WithCapacity(128)
    .WithAllocator(Allocator.Persistent)
    .OverwriteOnFull()
    .Build();
// Always dispose when done
deque.Dispose();

Constructors

ScyllaDequeDOTS(int, Allocator, bool, NativeArrayOptions)

Initializes a new ScyllaDequeDOTS<T> with a fixed native buffer of the specified capacity.

Declaration

public ScyllaDequeDOTS(int capacity, Allocator allocator, bool overwriteOnFull = false, NativeArrayOptions options = NativeArrayOptions.UninitializedMemory)

Parameters

Type	Name	Description
int	capacity	The fixed capacity of the deque. Values less than `1` are silently clamped to `1`. The deque cannot grow beyond this size; it is fixed for the lifetime of the instance.
Allocator	allocator	The Unity Unity.Collections.Allocator used to allocate the internal Unity.Collections.NativeArray<T>. Must not be Unity.Collections.Allocator.None. Unity.Collections.Allocator.Persistent: use for long-lived deques that survive across frames. Unity.Collections.Allocator.TempJob: use for deques passed into jobs that complete within four frames. Unity.Collections.Allocator.Temp: use for very short-lived deques that are created and disposed within a single method call or frame.
bool	overwriteOnFull	When `true`, pushing onto a full deque silently evicts the element at the opposite end (push-front evicts back, push-back evicts front) and always returns `true`. When `false` (the default), pushing onto a full deque fails and returns `false`.
NativeArrayOptions	options	Controls whether the native array memory is zero-initialized at allocation time. Defaults to Unity.Collections.NativeArrayOptions.UninitializedMemory for maximum performance; pass Unity.Collections.NativeArrayOptions.ClearMemory if zero-initialization is required.

Exceptions

Type	Condition
ArgumentException	Thrown when `allocator` is Unity.Collections.Allocator.None.

Properties

Capabilities

Gets the capability flags advertised by this deque instance.

Declaration

public ScyllaCollectionCapabilities Capabilities { get; }

Property Value

Type	Description
ScyllaCollectionCapabilities	A combination of HasCapacity, SupportsPeek, and SupportsCopyTo. Note that SupportsContains is not included because ScyllaDequeDOTS<T> does not expose a `Contains` method (unmanaged types require a custom equality approach that varies by job context).

Capacity

Gets the fixed capacity of the deque - 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>, or `0` if the buffer has not been created or has already been disposed.

Count

Gets the number of elements currently stored in the deque.

Declaration

public int Count { get; }

Property Value

Type	Description
int	A non-negative integer in the range `[0, Capacity]`.

FreeCount

Gets the number of free slots remaining before the deque reaches full capacity.

Declaration

public int FreeCount { get; }

Property Value

Type	Description
int	`Capacity - Count`, or `0` if the buffer has not been created or has been disposed. When OverwriteOnFull is `true`, this value is informational only; pushes continue to succeed even when `FreeCount` is `0`.

IsCreated

Gets a value indicating whether the underlying Unity.Collections.NativeArray<T> buffer has been allocated and not yet disposed.

Declaration

public bool IsCreated { get; }

Property Value

Type	Description
bool	`true` if the buffer was created and Dispose() has not been called; `false` if the struct was default-initialized or has already been disposed. Always check this property before using the deque if there is any doubt about its lifetime.

IsEmpty

Gets a value indicating whether the deque contains no elements.

Declaration

public bool IsEmpty { get; }

Property Value

Type	Description
bool	`true` when Count is `0`; otherwise `false`.

IsFull

Gets a value indicating whether the deque is currently at full capacity.

Declaration

public bool IsFull { get; }

Property Value

Type	Description
bool	`true` when Count equals Capacity and the buffer has been created. When full and OverwriteOnFull is `false`, push operations fail. When full and OverwriteOnFull is `true`, push operations succeed by evicting the element at the opposite end.

OverwriteOnFull

Gets a value indicating whether pushing onto a full deque will evict an element from the opposite end rather than failing.

Declaration

public bool OverwriteOnFull { get; }

Property Value

Type	Description
bool	`true` if eviction is enabled (push-front evicts back, push-back evicts front); `false` if a push onto a full deque simply returns `false`. This value is set at construction and never changes.

SyncRoot

Gets the synchronization root for this deque. Always null for unsynchronized instances.

Declaration

public object SyncRoot { get; }

Property Value

Type	Description
object	`null`

ThreadSafety

Gets the thread-safety level of this deque, which is always Unsynchronized.

Declaration

public ScyllaCollectionThreadSafety ThreadSafety { get; }

Property Value

Type	Description
ScyllaCollectionThreadSafety	Unsynchronized

Methods

Clear()

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

Declaration

public void Clear()

Remarks

After this call Count is 0, IsEmpty is true, and both _head and _tail are reset to 0. The backing Unity.Collections.NativeArray<T> is not freed; Capacity remains unchanged. The stale element values in the array are not zeroed; they will be silently overwritten by subsequent push operations.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the deque has not been created or has already been disposed.

CopyTo(Span<T>)

Copies elements from the deque into the provided Span<T> in front-to-back order. At most min(Count, destination.Length) elements are written.

Declaration

public int CopyTo(Span<T> destination)

Parameters

Type	Name	Description
Span<T>	destination	A caller-owned span that receives the copied elements. Writing stops when either the deque is exhausted or the span is full, whichever comes first.

Returns

Type	Description
int	The number of elements actually copied. Returns `0` if the deque is empty or `destination.Length` is `0`.

Remarks

Elements are read sequentially from _head with index arithmetic performed modulo the buffer length at each step. This handles both contiguous and wrapped layouts correctly without a branching copy strategy.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the deque has not been created or has already been disposed.

CopyTo(T[], int)

Copies elements from the deque into the provided array starting at the given index, in front-to-back order. At most min(Count, destination.Length - destinationIndex) elements are written.

Declaration

public int CopyTo(T[] destination, int destinationIndex)

Parameters

Type	Name	Description
T[]	destination	The target array. 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 actually copied. Returns `0` if the deque is empty or there is no available space in `destination`.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the deque has not been created or has already been disposed.
ArgumentNullException	Thrown when `destination` is `null`.
ArgumentOutOfRangeException	Thrown when `destinationIndex` is negative or greater than `destination.Length`.

CreateBuilder()

Creates and returns a new fluent ScyllaDequeDOTS<T>.Builder for configuring and constructing a ScyllaDequeDOTS<T> instance.

Declaration

public static ScyllaDequeDOTS<T>.Builder CreateBuilder()

Returns

Type	Description
ScyllaDequeDOTS<T>.Builder	A fresh ScyllaDequeDOTS<T>.Builder instance with default settings: initial capacity of `4`, no allocator set (must be configured via WithAllocator(Allocator) before building), no overwrite-on-full, and Unity.Collections.NativeArrayOptions.UninitializedMemory.

Remarks

The builder provides a named-parameter-style API that is easier to read than positional constructor arguments, especially when multiple options need to be configured together. WithAllocator(Allocator) must be called before Build() or BuildConcrete(); omitting it results in an InvalidOperationException at build time.

Dispose()

Disposes the underlying Unity.Collections.NativeArray<T> buffer, releasing the native memory back to the allocator. Also resets _head, _tail, and _count to 0.

Declaration

public void Dispose()

Remarks

This method is safe to call on a deque that has already been disposed or was never created; Unity.Collections.NativeArray<T>.IsCreated is checked before disposing. After this call, IsCreated returns false and any further method calls (except Dispose()) will throw InvalidOperationException. Always dispose ScyllaDequeDOTS<T> instances created with Unity.Collections.Allocator.Persistent or Unity.Collections.Allocator.TempJob to avoid native memory leaks.

TryAdd(T)

Attempts to add an item to the back of the deque (FIFO convention) by delegating to TryPushBack(T). Implements TryAdd(T) for polymorphic usage through the abstract interface.

Declaration

public bool TryAdd(T item)

Parameters

Type	Name	Description
T	item	The item to push onto the back of the deque.

Returns

Type	Description
bool	`true` if the item was added; `false` if the deque is full and OverwriteOnFull is `false`.

Remarks

Implements the Scylla collection convention for deques: TryAdd(T) == TryPushBack(T).

TryPeek(out T)

Attempts to inspect the front element without removing it by delegating to TryPeekFront(out T). Implements TryPeek(out T) for polymorphic usage through the abstract interface.

Declaration

public bool TryPeek(out T item)

Parameters

Type	Name	Description
T	item	When this method returns `true`, contains the current front element; otherwise `default`.

Returns

Type	Description
bool	`true` if an element was available; `false` if the deque is empty.

Remarks

Implements the Scylla collection convention for deques: TryPeek(out T) == TryPeekFront(out T).

TryPeekBack(out T)

Attempts to inspect the back element without removing it, in O(1) time.

Declaration

public bool TryPeekBack(out T item)

Parameters

Type	Name	Description
T	item	When this method returns `true`, contains the current back element. When this method returns `false`, contains `default(T)`.

Returns

Type	Description
bool	`true` if an element was available; `false` if the deque is empty.

Remarks

Because _tail points one slot past the back element, the back element is read from (_tail - 1 + capacity) % capacity.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the deque has not been created or has already been disposed.

TryPeekFront(out T)

Attempts to inspect the front element without removing it, in O(1) time.

Declaration

public bool TryPeekFront(out T item)

Parameters

Type	Name	Description
T	item	When this method returns `true`, contains the current front element. When this method returns `false`, contains `default(T)`.

Returns

Type	Description
bool	`true` if an element was available; `false` if the deque is empty.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the deque has not been created or has already been disposed.

TryPopBack(out T)

Attempts to remove and return the back element of the deque in O(1) time.

Declaration

public bool TryPopBack(out T item)

Parameters

Type	Name	Description
T	item	When this method returns `true`, contains the removed back element. When this method returns `false`, contains `default(T)`.

Returns

Type	Description
bool	`true` if an element was removed; `false` if the deque is empty.

Remarks

Before reading the element, _tail is decremented modulo the buffer length so that it points to the back element itself (recall that _tail normally points one slot past the back element). When the last element is removed (_count reaches 0), both _head and _tail are reset to 0 to maintain the canonical empty state.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the deque has not been created or has already been disposed.

TryPopFront(out T)

Attempts to remove and return the front element of the deque in O(1) time.

Declaration

public bool TryPopFront(out T item)

Parameters

Type	Name	Description
T	item	When this method returns `true`, contains the removed front element. When this method returns `false`, contains `default(T)`.

Returns

Type	Description
bool	`true` if an element was removed; `false` if the deque is empty.

Remarks

After removal, _head is incremented modulo the buffer length. When the last element is removed (_count reaches 0), both _head and _tail are reset to 0 to keep the buffer in a canonical empty state and avoid head/tail drift over many push/pop cycles.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the deque has not been created or has already been disposed.

TryPushBack(T)

Attempts to append an item at the back of the deque in O(1) time.

Declaration

public bool TryPushBack(T item)

Parameters

Type	Name	Description
T	item	The item to place at the back of the deque.

Returns

Type	Description
bool	`true` if the item was added. `false` if the deque is full and OverwriteOnFull is `false`. When OverwriteOnFull is `true`, always returns `true` - the current front element is silently evicted to make room.

Remarks

When the deque is not full, the item is written to the slot at _tail, then _tail is incremented modulo the buffer length. _count is incremented.

When the deque is full and OverwriteOnFull is true, the front element is discarded by incrementing _head modulo the buffer length (advancing it past the evicted slot), then the new item is written to the old _tail slot and _tail is incremented. _count remains at Capacity.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the deque has not been created or has already been disposed.

TryPushFront(T)

Attempts to insert an item at the front of the deque in O(1) time.

Declaration

public bool TryPushFront(T item)

Parameters

Type	Name	Description
T	item	The item to place at the front of the deque.

Returns

Type	Description
bool	`true` if the item was added. `false` if the deque is full and OverwriteOnFull is `false`. When OverwriteOnFull is `true`, always returns `true` - the current back element is silently evicted to make room.

Remarks

When the deque is not full, _head is decremented modulo the buffer length and the item is written to the new _head slot. _count is incremented.

When the deque is full and OverwriteOnFull is true, the back element is discarded by decrementing _tail modulo the buffer length (stepping it back to the now-evicted slot), then _head is decremented and the new item is written there. _count remains at Capacity.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the deque has not been created or has already been disposed.

TryRemove(out T)

Attempts to remove and return the front element of the deque (FIFO convention) by delegating to TryPopFront(out T). Implements TryRemove(out T) for polymorphic usage through the abstract interface.

Declaration

public bool TryRemove(out T item)

Parameters

Type	Name	Description
T	item	When this method returns `true`, contains the removed front element; otherwise `default`.

Returns

Type	Description
bool	`true` if an element was removed; `false` if the deque is empty.

Remarks

Implements the Scylla collection convention for deques: TryRemove(out T) == TryPopFront(out T).

Implements

IScyllaCollection<T>

IScyllaCollection

IDisposable