Struct ScyllaStackDOTS<T>

Burst/DOTS-compatible fixed-capacity LIFO (last-in, first-out) stack backed by a Unity.Collections.NativeArray<T> of unmanaged elements.

Implements
Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
[BurstCompile]
public struct ScyllaStackDOTS<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), which is required for use with Unity.Collections.NativeArray<T> and Burst compilation.
Remarks

This type is the DOTS-native counterpart to the managed ScyllaStack<T>. Because it is a struct backed by a Unity.Collections.NativeArray<T>, it can be used safely inside Burst-compiled job code and passed across job boundaries (subject to the usual Unity job system ownership rules).

Capacity: The stack is always fixed-capacity - the backing Unity.Collections.NativeArray<T> is allocated once at construction time and never resized. Capacity is rounded up to a minimum of 1 if zero or negative is provided.

Overwrite-on-full mode: When overwriteOnFull is true (enabled via the constructor or OverwriteOnFull(bool)), pushing onto a full stack drops the oldest (bottom) element by shifting all existing elements one index toward index 0 and writing the new item at the top. When false (the default), TryAdd(T) returns false without modifying the stack.

Lifetime management: Call Dispose() when the stack is no longer needed to release the underlying native memory. Failing to dispose will leak native memory. Check IsCreated before use when lifetime management is unclear. All mutating methods call Scylla.Core.Structures.ScyllaStackDOTS<T>.RequireCreated() internally and throw InvalidOperationException if the buffer is not allocated.

Thread safety: Unsynchronized by default, matching the broader Scylla collection pattern. Do not share a single ScyllaStackDOTS<T> instance between concurrent jobs without appropriate synchronization. 

// Direct construction
var stack = new ScyllaStackDOTS<int>(capacity: 64, allocator: Allocator.Persistent);

// Using fluent builder for complex configuration
var stack = ScyllaStackDOTS<int>.CreateBuilder()
.WithCapacity(128)
.WithAllocator(Allocator.Persistent)
.OverwriteOnFull()
.Build();


// Always dispose when done
stack.Dispose();

Constructors

ScyllaStackDOTS(int, Allocator, bool, NativeArrayOptions)

Initializes a new ScyllaStackDOTS<T> with the specified capacity, allocator, and overflow behavior.

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

The fixed capacity of the stack - the total number of elements it can hold. Values less than 1 are silently clamped to 1.
Allocator allocator

The Unity memory allocator used to allocate the internal Unity.Collections.NativeArray<T>. Must not be Unity.Collections.Allocator.None. Common choices:

  • Unity.Collections.Allocator.Persistent - for stacks that live across multiple frames.
  • Unity.Collections.Allocator.TempJob - for stacks used within a single frame across jobs.
  • Unity.Collections.Allocator.Temp - for stacks used only within a single frame on the main thread.
bool overwriteOnFull

When true, pushing onto a full stack drops the bottom (oldest) element to make room, keeping the stack size constant at capacity. When false (the default), TryAdd(T) returns false if the stack is full and the element is not added.
NativeArrayOptions options

Initialization options for the native array. Defaults to Unity.Collections.NativeArrayOptions.UninitializedMemory for maximum performance; pass Unity.Collections.NativeArrayOptions.ClearMemory to zero-initialize the buffer.
Exceptions
Type Condition
ArgumentException

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

Properties

Capabilities

Gets the ScyllaCollectionCapabilities flags describing the optional operations supported by this stack. Reports HasCapacity, SupportsPeek, and SupportsCopyTo. Unlike ScyllaStack<T>, this type does not report SupportsContains because the DOTS variant omits the O(n) contains search to keep the API minimal.

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

Capacity

Gets the fixed capacity of the stack - the maximum number of elements it can hold. Returns 0 if the underlying buffer is not yet allocated (i.e. IsCreated is false).

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

Count

Gets the number of elements currently stored in the stack.

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

FreeCount

Gets the number of additional elements that can be pushed before the stack is full. Returns 0 if the buffer is not yet allocated. When OverwriteOnFull is true, this value reaching zero does not prevent further pushes; it merely indicates that the next push will drop the bottom element.

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

IsCreated

Gets a value indicating whether the underlying Unity.Collections.NativeArray<T> has been allocated. Returns false after Dispose() is called or if the struct was default-initialized without using the constructor.

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

IsEmpty

Gets a value indicating whether the stack contains no elements.

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

IsFull

Gets a value indicating whether the stack is currently full, i.e. Count equals Capacity. Returns false if the buffer is not yet allocated.

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

OverwriteOnFull

Gets a value indicating whether pushing onto a full stack is allowed by dropping the oldest (bottom) element to make room for the new top element. When false, pushing onto a full stack fails silently and returns false.

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

SyncRoot

Gets null because this unsynchronized DOTS stack does not own a lock object. Implements SyncRoot for interface compliance.

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

ThreadSafety

Gets Unsynchronized, indicating that no internal locking is performed. Concurrent access from multiple threads or jobs requires external synchronization.

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

Methods

Clear()

Removes all elements from the stack, resetting the element count to zero. The underlying native buffer is not deallocated; call Dispose() to release native memory when the stack is no longer needed.

Declaration
public void Clear()
Exceptions
Type Condition
InvalidOperationException

Thrown if the underlying native buffer has not been allocated (i.e. IsCreated is false).

CopyTo(Span<T>)

Copies elements from the stack into destination in top-to-bottom order. Element 0 of the destination receives the current top of the stack.

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

The span to write into. A zero-length span causes the method to return 0 immediately.
Returns
Type Description
int

The number of elements actually written to destination. Returns 0 if the stack is empty or the destination has zero length.
Remarks

Copies min(Count, destination.Length) elements. If the destination span is shorter than the stack, only the topmost elements are copied; bottom elements are silently omitted. No elements are removed from the stack.

Exceptions
Type Condition
InvalidOperationException

Thrown if the underlying native buffer has not been allocated (i.e. IsCreated is false).

CopyTo(T[], int)

Copies elements from the stack into destination starting at destinationIndex, in top-to-bottom order. Element at destinationIndex receives the current top of the stack.

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

The managed 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 actually written to destination. Returns 0 if the stack is empty or no space is available from destinationIndex.
Remarks

Copies min(Count, destination.Length - destinationIndex) elements. If the available space is less than Count, only as many elements as will fit are copied (topmost first). No elements are removed from the stack.

Exceptions
Type Condition
InvalidOperationException

Thrown if the underlying native buffer has not been allocated (i.e. IsCreated is false).
ArgumentNullException

Thrown when destination is null.
ArgumentOutOfRangeException

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

CreateBuilder()

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

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

A new, unconfigured ScyllaStackDOTS<T>.Builder instance.
Remarks

The builder provides a discoverable, named-parameter-style API as an alternative to positional constructor arguments. The allocator must be set via WithAllocator(Allocator) before calling Build().

Dispose()

Releases the underlying Unity.Collections.NativeArray<T> and resets the element count to zero. Must be called when the stack is no longer needed to prevent native memory leaks.

Declaration
public void Dispose()
Remarks

This method is safe to call multiple times: if the buffer has already been disposed (or was never allocated), the check on Unity.Collections.NativeArray<T>.IsCreated prevents a double-free. After disposing, IsCreated returns false and all mutating methods will throw InvalidOperationException.

TryAdd(T)

Attempts to push item onto the top of the stack. Implements TryAdd(T) for polymorphic usage.

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

The item to push onto the top of the stack.
Returns
Type Description
bool

true if the item was pushed (either into a non-full stack or by overwriting the bottom element); false if the stack is full and overwrite mode is disabled.
Remarks

When the stack is not full, the element is written at index _count and the count is incremented. When the stack is full and OverwriteOnFull is true, the bottom element is dropped via Scylla.Core.Structures.ScyllaStackDOTS<T>.DropBottomAndAppend(T) and the new item is placed at the top; the count remains at Capacity. When the stack is full and OverwriteOnFull is false, the method returns false without modifying the stack.

Exceptions
Type Condition
InvalidOperationException

Thrown if the underlying native buffer has not been allocated (i.e. IsCreated is false).

TryPeek(out T)

Attempts to read the top element of the stack without removing it. Implements TryPeek(out T) for polymorphic usage.

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

When this method returns true, contains the element currently on top of the stack. The stack is not modified. When this method returns false, contains default.
Returns
Type Description
bool

true if the stack is non-empty and the top element was returned; false if the stack is empty.
Exceptions
Type Condition
InvalidOperationException

Thrown if the underlying native buffer has not been allocated (i.e. IsCreated is false).

TryRemove(out T)

Attempts to pop the top element from the stack, removing it in the process. Implements TryRemove(out T) for polymorphic usage.

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

When this method returns true, contains the element that was on top of the stack. When this method returns false (stack was empty), contains default.
Returns
Type Description
bool

true if an element was successfully removed; false if the stack was empty.
Remarks

Unlike the managed TryPop(out T), the vacated slot in the native buffer is not cleared to default after popping. The native array stores unmanaged value types only, so there are no object references to release.

Exceptions
Type Condition
InvalidOperationException

Thrown if the underlying native buffer has not been allocated (i.e. IsCreated is false).

Implements