Class SwiftQueue<T>

Namespace

SwiftCollections

Assembly

SwiftCollections.dll

SwiftQueue<T> is a high-performance, circular buffer-based queue designed for ultra-low-latency enqueue and dequeue operations.

It leverages power-of-two capacities and bitwise arithmetic to eliminate expensive modulo operations, enhancing performance. By managing memory efficiently with a wrap-around technique and custom capacity growth strategies, SwiftQueue minimizes allocations and resizing. Aggressive inlining and optimized exception handling further reduce overhead, making SwiftQueue outperform traditional queues, especially in scenarios with high-frequency additions and removals.

[JsonConverter(typeof(StateJsonConverterFactory))]
[MemoryPackable(GenerateType.Object)]
public sealed class SwiftQueue<T> : IStateBacked<SwiftArrayState<T>>, ISwiftCloneable<T>, ICollection<T>, IEnumerable<T>, ICollection, IEnumerable, IMemoryPackable<SwiftQueue<T>>, IMemoryPackFormatterRegister

Type Parameters

T

Specifies the type of elements in the queue.

Inheritance

object

SwiftQueue<T>

Implements

IStateBacked<SwiftArrayState<T>>

ISwiftCloneable<T>

ICollection<T>

IEnumerable<T>

ICollection

IEnumerable

IMemoryPackable<SwiftQueue<T>>

IMemoryPackFormatterRegister

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Extension Methods

SwiftExtensions.FromEnd<T>(IEnumerable<T>, int)

SwiftExtensions.IsPopulatedSafe<T>(IEnumerable<T>)

SwiftExtensions.IsPopulated<T>(IEnumerable<T>)

SwiftExtensions.PopLast<T>(IEnumerable<T>)

SwiftExtensions.SecondToLast<T>(IEnumerable<T>)

SwiftExtensions.Shuffle<T>(IEnumerable<T>, Random)

SwiftExtensions.SkipFromEnd<T>(IEnumerable<T>, int)

Remarks

MemoryPack GenerateType: Object

SwiftCollections.SwiftArrayState<T> State

Constructors

SwiftQueue()

Initializes a new, empty instance of SwiftQueue.

public SwiftQueue()

SwiftQueue(SwiftArrayState<T>)

Initializes a new instance of the SwiftQueue<T> class with the specified SwiftArrayState<T>.

[MemoryPackConstructor]
public SwiftQueue(SwiftArrayState<T> state)

Parameters

state SwiftArrayState<T>

The state containing the internal array, count, offset, and version for initialization.

SwiftQueue(IEnumerable<T>)

Initializes a new instance of SwiftQueue that contains elements copied from the provided items.

public SwiftQueue(IEnumerable<T> items)

Parameters

items IEnumerable<T>

SwiftQueue(int)

Initializes a new, empty instance of SwiftQueue with the specified initial capacity.

public SwiftQueue(int capacity)

Parameters

capacity int

Fields

DefaultCapacity

The default initial capacity of the SwiftQueue if none is specified. Used to allocate a reasonable starting size to minimize resizing operations.

public const int DefaultCapacity = 8

Field Value

int

Properties

Capacity

Gets the total number of elements the SwiftQueue can hold without resizing. Reflects the current allocated size of the internal array.

[JsonIgnore]
[MemoryPackIgnore]
public int Capacity { get; }

Property Value

int

Count

[JsonIgnore]
[MemoryPackIgnore]
public int Count { get; }

Property Value

int

InnerArray

[JsonIgnore]
[MemoryPackIgnore]
public T[] InnerArray { get; }

Property Value

T[]

IsReadOnly

[JsonIgnore]
[MemoryPackIgnore]
public bool IsReadOnly { get; }

Property Value

bool

IsSynchronized

[JsonIgnore]
[MemoryPackIgnore]
public bool IsSynchronized { get; }

Property Value

bool

this[int]

Gets the element at the specified arrayIndex.

[JsonIgnore]
[MemoryPackIgnore]
public T this[int index] { get; set; }

Parameters

index int

Property Value

T

State

Gets or sets the current state of the collection, including its items and order.

[JsonInclude]
[MemoryPackInclude]
public SwiftArrayState<T> State { get; }

Property Value

SwiftArrayState<T>

Remarks

Setting this property replaces the entire contents of the collection with the items from the specified state. Getting this property returns a snapshot of the collection's current items and their order. This property is intended for serialization and deserialization scenarios.

SyncRoot

[JsonIgnore]
[MemoryPackIgnore]
public object SyncRoot { get; }

Property Value

object

Methods

Clear()

Removes all elements from the SwiftQueue, resetting its count to zero.

public void Clear()

CloneTo(ICollection<T>)

Clones the entire ISwiftCloneable<T> into a new target ICollection<T>, ensuring that the target list is an exact copy. Clears the target list first to match the structure and state of the source list exactly.

public void CloneTo(ICollection<T> output)

Parameters

output ICollection<T>

Contains(T)

public bool Contains(T item)

Parameters

item T

Returns

bool

CopyTo(Array, int)

public void CopyTo(Array array, int arrayIndex)

Parameters

array Array

arrayIndex int

CopyTo(Span<T>)

Copies the elements of the SwiftQueue into the specified destination span.

public void CopyTo(Span<T> destination)

Parameters

destination Span<T>

The destination span.

CopyTo(T[], int)

public void CopyTo(T[] array, int arrayIndex)

Parameters

array T[]

arrayIndex int

Dequeue()

Removes and returns the item at the front of the queue. Throws an InvalidOperationException if the queue is empty.

public T Dequeue()

Returns

T

The item at the front of the queue.

Enqueue(T)

Adds an item to the end of the queue. Automatically resizes the queue if the capacity is exceeded.

public void Enqueue(T item)

Parameters

item T

The item to add to the queue.

EnqueueRange(IEnumerable<T>)

Adds the elements of the specified collection to the end of the queue.

public void EnqueueRange(IEnumerable<T> items)

Parameters

items IEnumerable<T>

The collection of elements to add to the queue. Cannot be null.

Remarks

Known-count sources reserve capacity before enumeration to avoid repeated growth.

EnqueueRange(ReadOnlySpan<T>)

Adds the elements of the specified span to the end of the queue in queue order.

public void EnqueueRange(ReadOnlySpan<T> items)

Parameters

items ReadOnlySpan<T>

The span whose elements should be enqueued.

EnqueueRange(T[])

Adds the elements of the specified array to the end of the queue in queue order.

public void EnqueueRange(T[] items)

Parameters

items T[]

The array whose elements should be enqueued.

EnsureCapacity(int)

Ensures that the internal storage has at least the specified capacity, resizing if necessary.

public void EnsureCapacity(int capacity)

Parameters

capacity int

The minimum number of elements that the internal storage should be able to hold. Must be a non-negative integer.

Remarks

If the specified capacity is not a power of two, it is rounded up to the next power of two to optimize internal operations.

Exists(Predicate<T>)

Determines whether the SwiftQueue<T> contains an element that matches the conditions defined by the specified predicate.

public bool Exists(Predicate<T> match)

Parameters

match Predicate<T>

The predicate that defines the conditions of the element to search for.

Returns

bool

true if the SwiftQueue<T> contains one or more elements that match the specified predicate; otherwise, false.

FastClear()

Clears the SwiftQueue without releasing the reference to the stored elements. Use FastClear() when you want to quickly reset the list without reallocating memory.

public void FastClear()

Find(Predicate<T>)

Searches for an element that matches the conditions defined by the specified predicate, and returns the first matching element in queue order.

public T Find(Predicate<T> match)

Parameters

match Predicate<T>

The predicate that defines the conditions of the element to search for.

Returns

T

The first element that matches the conditions defined by the specified predicate, if found; otherwise, the default value for type T.

GetEnumerator()

Returns an enumerator that iterates through the SwiftList.

public SwiftQueue<T>.SwiftQueueEnumerator GetEnumerator()

Returns

SwiftQueue<T>.SwiftQueueEnumerator

GetSegments(out ReadOnlySpan<T>, out ReadOnlySpan<T>)

Returns the current queue contents as up to two read-only spans.

public void GetSegments(out ReadOnlySpan<T> first, out ReadOnlySpan<T> second)

Parameters

first ReadOnlySpan<T>

The first contiguous queue segment.

second ReadOnlySpan<T>

The wrapped tail segment, if any.

Peek()

Returns the item at the front of the queue without removing it. Throws an InvalidOperationException if the queue is empty.

public T Peek()

Returns

T

The item at the front of the queue.

PeekTail()

Returns the item at the end of the queue without removing it. Throws an InvalidOperationException if the queue is empty.

public T PeekTail()

Returns

T

The item at the end of the queue.

ToArray()

Copies the elements of the SwiftQueue to a new array.

public T[] ToArray()

Returns

T[]

TrimExcessCapacity()

Reduces the capacity of the SwiftQueue if the element count is significantly less than the current capacity. This method resizes the internal array to the next power of two greater than or equal to the current count, optimizing memory usage.

public void TrimExcessCapacity()

TryDequeue(out T)

Tries to remove and return the item at the front of the queue.

public bool TryDequeue(out T item)

Parameters

item T

Returns

bool

TryPeek(out T)

Tries to return the item at the front of the queue without removing it.

public bool TryPeek(out T item)

Parameters

item T

Returns

bool