Struct ScyllaRingBufferDOTS<T>

Burst/DOTS-compatible fixed-capacity ring buffer backed by a Unity.Collections.NativeArray<T>. Stores items in FIFO order (oldest-to-newest) and supports O(1) add, remove, and peek operations.

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 ScyllaRingBufferDOTS<T> : IScyllaCollection<T>, IScyllaCollection, IDisposable where T : unmanaged

Type Parameters

Name	Description
T	The element type. Must be an unmanaged value type (e.g., int, float, blittable structs) to satisfy Burst and native-container constraints. For managed types, use ScyllaRingBuffer<T> instead.

Remarks

This type is the unmanaged counterpart to ScyllaRingBuffer<T>. Because the backing store is a Unity.Collections.NativeArray<T>, the buffer can be passed to Burst-compiled jobs and used within DOTS systems without triggering managed-memory restrictions. The element type T is constrained to unmanaged to satisfy this requirement.

Lifecycle: The buffer holds unmanaged native memory and must be explicitly disposed via Dispose() when no longer needed to avoid memory leaks. Before any operation is performed, the buffer must have been successfully constructed (i.e., IsCreated must be true). All public methods that access the backing array call RequireCreated() internally and throw InvalidOperationException if the buffer has not been allocated or has already been disposed.

Overwrite behavior: When overwriteOnFull is true and the buffer is full, a new write discards the oldest element by advancing _head to the new _tail position. When overwriteOnFull is false, the write returns false without modifying the buffer.

Thread-safety: Unsynchronized by default, consistent with other Scylla collection patterns. Do not access the same instance concurrently from multiple threads without external synchronization.

// Direct construction
var ringBuffer = new ScyllaRingBufferDOTS<int>(capacity: 64, allocator: Allocator.Persistent);
// Using fluent builder for complex configuration
var ringBuffer = ScyllaRingBufferDOTS<int>.CreateBuilder()
.WithCapacity(128)
.WithAllocator(Allocator.Persistent)
.OverwriteOnFull()
.Build();

Constructors

ScyllaRingBufferDOTS(int, Allocator, bool, NativeArrayOptions)

Creates a new fixed-capacity DOTS ring buffer, allocating a Unity.Collections.NativeArray<T> of the specified size using the provided allocator.

Declaration

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

Parameters

Type	Name	Description
int	capacity	The maximum number of elements the ring buffer can hold. Values less than 1 are clamped to 1.
Allocator	allocator	The Unity native-memory allocator to use for the backing Unity.Collections.NativeArray<T>. Must not be Unity.Collections.Allocator.None. Common choices: Allocator.Persistent - long-lived buffer (most game scenarios). Allocator.TempJob - buffer used within a single frame across jobs. Allocator.Temp - buffer used within a single frame (must dispose before frame end).
bool	overwriteOnFull	If true, writing to a full buffer silently discards the oldest element and advances the head, ensuring the write always succeeds. If false, writing to a full buffer returns false and leaves the buffer unchanged.
NativeArrayOptions	options	Initialization options for the Unity.Collections.NativeArray<T>. Defaults to Unity.Collections.NativeArrayOptions.UninitializedMemory for maximum allocation speed. Use Unity.Collections.NativeArrayOptions.ClearMemory when zero-initialized memory is required.

Remarks

The buffer must be disposed via Dispose() when no longer needed to free the underlying native memory. Unity.Collections.Allocator.None is not a valid allocator and will throw.

Exceptions

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

Properties

Capabilities

Gets the capability flags supported by this ring buffer instance.

Declaration

public ScyllaCollectionCapabilities Capabilities { get; }

Property Value

Type	Description
ScyllaCollectionCapabilities	A combination of ScyllaCollectionCapabilities flags. This DOTS ring buffer always advertises HasCapacity, SupportsPeek, and SupportsCopyTo. Note that SupportsContains is not advertised because no Contains method is provided on the DOTS variant (linear scan over Unity.Collections.NativeArray<T> is left to the caller when needed).

Capacity

Gets the fixed maximum number of elements this ring buffer can hold.

Declaration

public int Capacity { get; }

Property Value

Type	Description
int	The length of the underlying Unity.Collections.NativeArray<T>, set at construction time. Returns 0 if the buffer has not been created or has been disposed.

Count

Gets the current number of elements stored in the ring buffer.

Declaration

public int Count { get; }

Property Value

Type	Description
int	A value in the range [0, Capacity]. Incremented by successful writes; decremented by reads.

FreeCount

Gets the number of additional elements that can be written before the buffer is full.

Declaration

public int FreeCount { get; }

Property Value

Type	Description
int	Equivalent to Capacity - Count. Returns 0 when the buffer is full or not created.

IsCreated

Gets whether the underlying native buffer has been allocated and is ready for use.

Declaration

public bool IsCreated { get; }

Property Value

Type	Description
bool	true if the Unity.Collections.NativeArray<T> backing store has been created (i.e., the buffer was successfully constructed and has not yet been disposed); otherwise false. All operations that access the buffer require this to be true.

IsEmpty

Gets whether the ring buffer contains no elements.

Declaration

public bool IsEmpty { get; }

Property Value

Type	Description
bool	true if Count is zero; otherwise false.

IsFull

Gets whether the ring buffer is currently at full capacity.

Declaration

public bool IsFull { get; }

Property Value

Type	Description
bool	true if the buffer is created and Count equals Capacity. Returns false if the buffer has not been created or has been disposed.

OverwriteOnFull

Gets whether writing to a full buffer automatically overwrites the oldest element.

Declaration

public bool OverwriteOnFull { get; }

Property Value

Type	Description
bool	true if writes always succeed by discarding the oldest element when the buffer is full; false if writes return false without modifying the buffer when it is full.

SyncRoot

Gets the synchronization root for externally coordinating operations on this collection.

Declaration

public object SyncRoot { get; }

Property Value

Type	Description
object	Always null for this unsynchronized DOTS struct. There is no synchronized wrapper available for ScyllaRingBufferDOTS<T>; apply external locking when needed.

ThreadSafety

Gets the thread-safety level of this ring buffer instance.

Declaration

public ScyllaCollectionThreadSafety ThreadSafety { get; }

Property Value

Type	Description
ScyllaCollectionThreadSafety	Always Unsynchronized. This struct provides no built-in locking. Apply external synchronization when concurrent access is required.

Methods

AsReversed()

Returns a lightweight wrapper struct that exposes GetEnumerator(), enabling foreach syntax for iterating the buffer contents from newest to oldest.

Declaration

public ScyllaRingBufferDOTS<T>.ReverseEnumerable AsReversed()

Returns

Type	Description
ScyllaRingBufferDOTS<T>.ReverseEnumerable	A ScyllaRingBufferDOTS<T>.ReverseEnumerable struct that wraps this ring buffer for reverse iteration.

Remarks

Usage: foreach (var item in buffer.AsReversed()) { ... }

Clear()

Removes all elements from the ring buffer without deallocating the backing native memory.

Declaration

public void Clear()

Remarks

Resets _head, _tail, and _count to 0. Unlike the managed Clear(), this method does not clear the contents of the backing Unity.Collections.NativeArray<T> because unmanaged types do not hold GC references. Existing data in the native array remains in memory but is logically inaccessible until overwritten by subsequent writes.

Exceptions

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

CopyTo(Span<T>)

Copies elements from the ring buffer into the provided span in oldest-to-newest (FIFO) order.

Declaration

public int CopyTo(Span<T> destination)

Parameters

Type	Name	Description
Span<T>	destination	The span to copy elements into. Copying stops when either all elements have been copied or the destination is full, whichever comes first. An empty span returns 0.

Returns

Type	Description
int	The number of elements copied.

Remarks

Unlike the managed CopyTo(Span<T>) which uses a two-segment block copy, this DOTS variant uses a per-element loop with modulo indexing to remain compatible with Burst-compiled code paths.

Exceptions

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

CopyTo(T[], int)

Copies elements from the ring buffer into the provided array starting at the specified index, in oldest-to-newest (FIFO) order.

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.

Remarks

Uses a per-element loop with modulo indexing for Burst-compatibility, copying at most min(Count, destination.Length - destinationIndex) elements.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the buffer 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 a new fluent builder for configuring and constructing a ScyllaRingBufferDOTS<T> instance.

Declaration

public static ScyllaRingBufferDOTS<T>.Builder CreateBuilder()

Returns

Type	Description
ScyllaRingBufferDOTS<T>.Builder	A new ScyllaRingBufferDOTS<T>.Builder instance with default configuration (capacity 4, no overwrite, uninitialized memory). WithAllocator(Allocator) must be called before Build().

Dispose()

Releases the underlying Unity.Collections.NativeArray<T> and resets all internal state.

Declaration

public void Dispose()

Remarks

After this method returns, IsCreated is false and any further access to the buffer will throw InvalidOperationException. Calling Dispose() on an already-disposed buffer is a no-op (guarded by _buffer.IsCreated). This method resets _head, _tail, and _count to 0 for safety, even though the backing memory has been freed.

GetEnumerator()

Returns a forward enumerator that iterates through all elements in oldest-to-newest (FIFO) order.

Declaration

public ScyllaRingBufferDOTS<T>.Enumerator GetEnumerator()

Returns

Type	Description
ScyllaRingBufferDOTS<T>.Enumerator	An ScyllaRingBufferDOTS<T>.Enumerator positioned before the first (oldest) element.

Remarks

The returned ScyllaRingBufferDOTS<T>.Enumerator is a value type and is Burst-compatible, causing no heap allocations. Use a foreach loop directly on ScyllaRingBufferDOTS<T> to take advantage of the struct enumerator pattern.

GetReverseEnumerator()

Returns a reverse enumerator that iterates through all elements in newest-to-oldest order.

Declaration

public ScyllaRingBufferDOTS<T>.ReverseEnumerator GetReverseEnumerator()

Returns

Type	Description
ScyllaRingBufferDOTS<T>.ReverseEnumerator	A ScyllaRingBufferDOTS<T>.ReverseEnumerator positioned before the first (newest) element.

Remarks

The returned ScyllaRingBufferDOTS<T>.ReverseEnumerator is a value type and is Burst-compatible, causing no heap allocations. For foreach loop support, prefer AsReversed().

TryAdd(T)

Attempts to write (enqueue) an item at the tail of the ring buffer. Equivalent to the ring-buffer write/enqueue operation.

Declaration

public bool TryAdd(T item)

Parameters

Type	Name	Description
T	item	The item to write.

Returns

Type	Description
bool	true if the item was written successfully. false if the buffer is full and OverwriteOnFull is false.

Remarks

When the buffer is not full, the item is placed at the physical index _tail, _tail is advanced using modulo arithmetic, and _count is incremented.

When the buffer is full and OverwriteOnFull is true, the item is written at the current _tail position (overwriting the oldest element), _tail advances by one, and _head is set to the new _tail to drop the overwritten oldest element. The count remains at capacity.

Exceptions

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

TryPeek(out T)

Attempts to inspect the oldest item at the head of the ring buffer without removing it. Implements TryPeek(out T) for polymorphic usage; equivalent to TryPeekOldest(out T).

Declaration

public bool TryPeek(out T item)

Parameters

Type	Name	Description
T	item	When this method returns, contains the oldest element if the buffer is non-empty, or default if the buffer is empty.

Returns

Type	Description
bool	true if the buffer is non-empty and item was set; otherwise false.

Exceptions

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

TryPeekAt(int, out T)

Attempts to return the item at the specified logical index without removing it.

Declaration

public bool TryPeekAt(int index, out T item)

Parameters

Type	Name	Description
int	index	The zero-based logical index into the buffer. Values outside [0, Count - 1] cause the method to return false.
T	item	When this method returns, contains the element at index if the index was valid, or default if the index was out of range.

Returns

Type	Description
bool	true if the index was valid and the item was retrieved; false otherwise.

Remarks

Logical index 0 corresponds to the oldest element (head of the FIFO queue) and logical index Count - 1 corresponds to the newest element. The physical index is computed as (_head + index) % Capacity using modulo arithmetic. Unlike PeekAt(int), this variant does not have a throwing overload; use the return value to detect out-of-range indices.

Exceptions

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

TryPeekNewest(out T)

Attempts to inspect the most recently written item at the tail of the ring buffer without removing it.

Declaration

public bool TryPeekNewest(out T item)

Parameters

Type	Name	Description
T	item	When this method returns, contains the newest element if the buffer is non-empty, or default if the buffer is empty.

Returns

Type	Description
bool	true if the buffer is non-empty and item was set; otherwise false.

Remarks

The newest element's physical index is (_tail - 1 + Capacity) % Capacity. This method computes the result using explicit subtraction and a branch-based wraparound rather than a modulo operation to avoid division in Burst-compiled paths.

Exceptions

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

TryPeekOldest(out T)

Attempts to inspect the oldest item at the head of the ring buffer without removing it. Equivalent to TryPeek(out T) with an explicit name for clarity in ring-buffer usage.

Declaration

public bool TryPeekOldest(out T item)

Parameters

Type	Name	Description
T	item	When this method returns, contains the oldest element if the buffer is non-empty, or default if the buffer is empty.

Returns

Type	Description
bool	true if the buffer is non-empty and item was set; otherwise false.

Exceptions

Type	Condition
InvalidOperationException	Thrown (via TryPeek(out T)) when the buffer has not been created or has already been disposed.

TryRemove(out T)

Attempts to read (dequeue) the oldest item from the head of the ring buffer, removing it.

Declaration

public bool TryRemove(out T item)

Parameters

Type	Name	Description
T	item	When this method returns, contains the oldest element if the operation succeeded, or default if the buffer was empty.

Returns

Type	Description
bool	true if an item was read; false if the buffer is empty.

Exceptions

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

Implements

IScyllaCollection<T>

IScyllaCollection

IDisposable