Struct ScyllaPriorityQueueDOTS<TValue>

Burst/DOTS-compatible, fixed-capacity priority queue backed by a Unity.Collections.NativeArray<T> binary heap. Supports both Min-heap and Max-heap ordering and provides deterministic FIFO tie-breaking for equal priorities.

Implements

IScyllaCollection<ScyllaPriorityQueueNode<TValue>>

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 ScyllaPriorityQueueDOTS<TValue> : IScyllaCollection<ScyllaPriorityQueueNode<TValue>>, IScyllaCollection, IDisposable where TValue : unmanaged

Type Parameters

Name	Description
TValue	The payload type stored alongside each priority value. Must satisfy the `unmanaged` constraint so that it can be stored in a Unity.Collections.NativeArray<T> and used in Burst jobs.

Remarks

This type is intentionally separate from the managed ScyllaPriorityQueue<T>. It uses Unity.Collections.NativeArray<T> as its backing storage so that it is safe to use in Burst-compiled jobs. The [BurstCompile] attribute on the struct and its static helpers allows the Burst compiler to generate optimal native code.

Fixed capacity: unlike ScyllaPriorityQueue<T>, this queue cannot grow. TryEnqueue(int, TValue) returns false when full. Capacity is set at construction time.

Tie-breaking: when two items have the same integer priority, the item inserted first is dequeued first (FIFO). This is guaranteed by an internal monotonically increasing sequence counter stored alongside each item.

Thread-safety: unsynchronized by default, matching Scylla collection conventions. Do not read or write this queue from multiple threads without external synchronization.

Lifetime management: the queue owns a native buffer that must be released by calling Dispose() when it is no longer needed, or by using a using statement. Failing to dispose will cause a native memory leak in the Unity memory profiler.

// Direct construction
var queue = new ScyllaPriorityQueueDOTS<int>(capacity: 64, allocator: Allocator.Persistent);
queue.TryEnqueue(priority: 2, value: 10);
queue.TryEnqueue(priority: 1, value: 20);
queue.TryDequeue(out var p, out var v); // p == 1, v == 20
queue.Dispose();
// Using fluent builder for complex configuration
using var queue = ScyllaPriorityQueueDOTS<int>.CreateBuilder()
.WithCapacity(128)
.WithAllocator(Allocator.Persistent)
.MaxHeap()
.Build();

Constructors

ScyllaPriorityQueueDOTS(int, Allocator, ScyllaPriorityQueueOrder, NativeArrayOptions)

Initializes a new ScyllaPriorityQueueDOTS<TValue> with the specified fixed capacity, allocator, and heap ordering.

Declaration

public ScyllaPriorityQueueDOTS(int capacity, Allocator allocator, ScyllaPriorityQueueOrder order = ScyllaPriorityQueueOrder.Min, NativeArrayOptions options = NativeArrayOptions.UninitializedMemory)

Parameters

Type	Name	Description
int	capacity	The fixed maximum number of elements the queue can hold. Values less than 1 are silently clamped to 1. Unlike ScyllaPriorityQueue<T>, this queue never grows; once full, TryEnqueue(int, TValue) returns `false`.
Allocator	allocator	The Unity native memory allocator for the internal heap buffer. Common choices: `Allocator.Persistent`Long-lived queues that survive multiple frames. `Allocator.TempJob`Queues that exist for up to 4 frames, used across jobs. `Allocator.Temp`Short-lived queues used and disposed within a single frame. `Allocator.None` is not permitted and will throw an ArgumentException.
ScyllaPriorityQueueOrder	order	The heap ordering mode. Min (the default) dequeues the item with the smallest integer priority first; Max dequeues the item with the largest integer priority first.
NativeArrayOptions	options	Native array initialization options. Defaults to Unity.Collections.NativeArrayOptions.UninitializedMemory for best performance; use Unity.Collections.NativeArrayOptions.ClearMemory if zero-initialization of the buffer is required.

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 DOTS priority queue instance.

Declaration

public ScyllaCollectionCapabilities Capabilities { get; }

Property Value

Type	Description
ScyllaCollectionCapabilities	Always includes HasCapacity, SupportsPeek, and SupportsCopyTo. Does not include SupportsContains because the DOTS variant omits the linear-scan `Contains` method to keep the API minimal and Burst-friendly.

Capacity

Gets the fixed maximum number of elements this queue can hold.

Declaration

public int Capacity { get; }

Property Value

Type	Description
int	The length of the internal native buffer, or `0` if IsCreated is `false`. This value is set at construction time and never changes.

Count

Gets the number of elements currently stored in the priority queue.

Declaration

public int Count { get; }

Property Value

Type	Description
int	The element count, in the range `[0, Capacity]`.

FreeCount

Gets the number of slots available before the queue becomes full.

Declaration

public int FreeCount { get; }

Property Value

Type	Description
int	`Capacity - Count` when IsCreated is `true`; `0` otherwise.

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 queue was successfully constructed and Dispose() has not been called; `false` for a default-initialized instance or after disposal.

IsEmpty

Gets a value indicating whether the priority queue contains no elements.

Declaration

public bool IsEmpty { get; }

Property Value

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

IsFull

Gets a value indicating whether the priority queue has no remaining capacity.

Declaration

public bool IsFull { get; }

Property Value

Type	Description
bool	`true` when IsCreated is `true` and Count equals Capacity. When `true`, TryEnqueue(int, TValue) will return `false`.

Order

Gets the heap ordering mode configured for this priority queue.

Declaration

public ScyllaPriorityQueueOrder Order { get; }

Property Value

Type	Description
ScyllaPriorityQueueOrder	Min if smaller priority integers are dequeued first; Max if larger priority integers are dequeued first.

SyncRoot

Gets the synchronization root for externally coordinating access to this collection.

Declaration

public object SyncRoot { get; }

Property Value

Type	Description
object	Always `null` for this unsynchronized DOTS collection.

ThreadSafety

Gets the thread-safety guarantees provided by this priority queue.

Declaration

public ScyllaCollectionThreadSafety ThreadSafety { get; }

Property Value

Type	Description
ScyllaCollectionThreadSafety	Always Unsynchronized. This collection is not thread-safe; callers are responsible for external synchronization when needed.

Methods

Clear()

Removes all elements from the priority queue, resetting Count and the internal sequence counter to zero. Does not deallocate the native buffer.

Declaration

public void Clear()

Remarks

Existing ScyllaPriorityQueueDOTS<TValue>.HeapItem data beyond the reset count remains in the buffer but is inaccessible. The native buffer retains its Capacity and can be reused immediately.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the queue has not been created (i.e. IsCreated is `false`).

CopyTo(ScyllaPriorityQueueNode<TValue>[], int)

Copies up to destination.Length - destinationIndex nodes into the destination array in priority-sorted dequeue order (highest priority first), starting at destinationIndex. This method does not mutate the original queue.

Declaration

public int CopyTo(ScyllaPriorityQueueNode<TValue>[] destination, int destinationIndex)

Parameters

Type	Name	Description
ScyllaPriorityQueueNode<TValue>[]	destination	The array to write nodes into. Must not be `null`.
int	destinationIndex	The zero-based starting index in `destination` at which copying begins. Must be in the range `[0, destination.Length]`.

Returns

Type	Description
int	The number of nodes actually written.

Remarks

Like the CopyTo(Span<ScyllaPriorityQueueNode<TValue>>) overload, this method creates a temporary Allocator.Temp copy of the buffer and pops from it to produce a sorted output. Time complexity: O(k log n) where k is the number of items copied.

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`.

CopyTo(Span<ScyllaPriorityQueueNode<TValue>>)

Copies up to destination.Length nodes into destination in priority-sorted dequeue order (highest priority first). This method does not mutate the original queue.

Declaration

public int CopyTo(Span<ScyllaPriorityQueueNode<TValue>> destination)

Parameters

Type	Name	Description
Span<ScyllaPriorityQueueNode<TValue>>	destination	The span to write nodes into. At most `min(Count, destination.Length)` nodes are written.

Returns

Type	Description
int	The number of nodes actually written.

Remarks

The method works by making a temporary Allocator.Temp copy of the internal buffer and repeatedly popping from it via PopRoot(NativeArray<HeapItem>, ref int, ScyllaPriorityQueueOrder). The original queue is left unchanged. This is more expensive than a raw buffer copy because it performs O(k log n) work to produce a sorted snapshot of k = min(Count, destination.Length) items.

Exceptions

Type	Condition
InvalidOperationException	Thrown when IsCreated is `false`.

CreateBuilder()

Creates a new fluent ScyllaPriorityQueueDOTS<TValue>.Builder for configuring and constructing a ScyllaPriorityQueueDOTS<TValue> instance.

Declaration

public static ScyllaPriorityQueueDOTS<TValue>.Builder CreateBuilder()

Returns

Type	Description
ScyllaPriorityQueueDOTS<TValue>.Builder	A fresh ScyllaPriorityQueueDOTS<TValue>.Builder with default settings (capacity 4, Min-heap, uninitialized memory).

Remarks

The builder enforces that WithAllocator(Allocator) is called before Build() to prevent accidentally constructing a queue with Allocator.None.

Dispose()

Disposes the underlying Unity.Collections.NativeArray<T> buffer, releasing native memory back to the allocator. Sets Count and the internal sequence counter to zero.

Declaration

public void Dispose()

Remarks

After calling this method, IsCreated returns false and any further operations on the queue (other than Dispose() again) will throw an InvalidOperationException via Scylla.Core.Structures.ScyllaPriorityQueueDOTS<TValue>.RequireCreated(). Calling Dispose() more than once is safe; subsequent calls are no-ops.

TryAdd(ScyllaPriorityQueueNode<TValue>)

Attempts to add a ScyllaPriorityQueueNode<TValue> to the priority queue. This method is the IScyllaCollection<T> bridge to TryEnqueue(int, TValue) and behaves identically.

Declaration

public bool TryAdd(ScyllaPriorityQueueNode<TValue> item)

Parameters

Type	Name	Description
ScyllaPriorityQueueNode<TValue>	item	The node to enqueue. Its Priority and Value are forwarded to TryEnqueue(int, TValue).

Returns

Type	Description
bool	`true` if the node was enqueued; `false` if the queue is full.

TryDequeue(out int, out TValue)

Attempts to remove and return the highest-priority item, splitting the result into its separate priority and value components. Delegates to TryRemove(out ScyllaPriorityQueueNode<TValue>).

Declaration

public bool TryDequeue(out int priority, out TValue value)

Parameters

Type	Name	Description
int	priority	When this method returns `true`, contains the priority integer of the dequeued item. When this method returns `false`, contains `0`.
TValue	value	When this method returns `true`, contains the payload of the dequeued item. When this method returns `false`, contains `default(TValue)`.

Returns

Type	Description
bool	`true` if an item was dequeued; `false` if the queue is empty.

TryEnqueue(int, TValue)

Attempts to insert a value with the specified integer priority into the heap.

Declaration

public bool TryEnqueue(int priority, TValue value)

Parameters

Type	Name	Description
int	priority	The integer priority of the item. Lower values have higher priority in Min-heap mode; higher values have higher priority in Max-heap mode.
TValue	value	The payload value to store alongside the priority.

Returns

Type	Description
bool	`true` if the item was enqueued; `false` if the queue is full (i.e. Count equals Capacity).

Remarks

The item is appended to the end of the used region of the native buffer and then sifted upward via SiftUp(NativeArray<HeapItem>, int, ScyllaPriorityQueueOrder) to restore the heap invariant. A unique, monotonically increasing sequence number from Scylla.Core.Structures.ScyllaPriorityQueueDOTS<TValue>._sequence is stored alongside the item to enable FIFO tie-breaking for equal priority values. Time complexity: O(log n).

Exceptions

Type	Condition
InvalidOperationException	Thrown when IsCreated is `false`.

TryPeek(out ScyllaPriorityQueueNode<TValue>)

Attempts to read the highest-priority node at the root of the heap without removing it. This method is the IScyllaCollection<T> peek bridge.

Declaration

public bool TryPeek(out ScyllaPriorityQueueNode<TValue> item)

Parameters

Type	Name	Description
ScyllaPriorityQueueNode<TValue>	item	When this method returns `true`, contains a ScyllaPriorityQueueNode<TValue> with the top priority and payload. When this method returns `false`, contains `default(ScyllaPriorityQueueNode<TValue>)`.

Returns

Type	Description
bool	`true` if an item was available; `false` if the queue is empty.

Remarks

This is a non-destructive O(1) operation. The returned node remains in the queue and will be returned again by subsequent calls to this method or TryRemove(out ScyllaPriorityQueueNode<TValue>).

Exceptions

Type	Condition
InvalidOperationException	Thrown when IsCreated is `false`.

TryPeek(out int, out TValue)

Attempts to read the highest-priority item without removing it, splitting the result into separate priority and value components. Delegates to TryPeek(out ScyllaPriorityQueueNode<TValue>).

Declaration

public bool TryPeek(out int priority, out TValue value)

Parameters

Type	Name	Description
int	priority	When this method returns `true`, contains the priority integer of the top item. When this method returns `false`, contains `0`.
TValue	value	When this method returns `true`, contains the payload of the top item. When this method returns `false`, contains `default(TValue)`.

Returns

Type	Description
bool	`true` if an item was available; `false` if the queue is empty.

TryRemove(out ScyllaPriorityQueueNode<TValue>)

Attempts to remove and return the highest-priority element from the queue. This method is the IScyllaCollection<T> bridge and behaves identically to dequeuing via TryDequeue(out int, out TValue).

Declaration

public bool TryRemove(out ScyllaPriorityQueueNode<TValue> item)

Parameters

Type	Name	Description
ScyllaPriorityQueueNode<TValue>	item	When this method returns `true`, contains a ScyllaPriorityQueueNode<TValue> with the dequeued priority and payload. When this method returns `false`, contains `default(ScyllaPriorityQueueNode<TValue>)`.

Returns

Type	Description
bool	`true` if an item was dequeued; `false` if the queue is empty.

Remarks

The root node (index 0) is removed, the last node is moved to the root, and SiftDown(NativeArray<HeapItem>, int, int, ScyllaPriorityQueueOrder) is called to restore the heap invariant. Time complexity: O(log n).

Exceptions

Type	Condition
InvalidOperationException	Thrown when IsCreated is `false`.

Implements

IScyllaCollection<T>

IScyllaCollection

IDisposable