Class ScyllaStack<T>.Builder

Fluent builder for constructing ScyllaStack<T> instances with complex or explicit configurations.

Inheritance
object
ScyllaStack<T>.Builder
Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public sealed class ScyllaStack<T>.Builder
Remarks

The builder provides a discoverable, named-parameter-style API as an alternative to positional constructor arguments. This is especially useful when enabling fixed-capacity mode or wrapping the stack in a synchronized wrapper, where positional arguments would be easy to mis-order.

Call Build() to obtain an IScyllaCollection<T> (which may be either the raw stack or a ScyllaStack<T>.SynchronizedScyllaStack depending on whether Synchronized(object) was called). Call BuildConcrete() to obtain the typed ScyllaStack<T> directly - this throws if Synchronized(object) was also called, since the synchronized wrapper is not the concrete stack type. 

// Basic usage with defaults
var stack = ScyllaStack<int>.CreateBuilder().Build();

// Configure capacity and fixed-capacity mode
var stack = ScyllaStack<string>.CreateBuilder()
.WithCapacity(64)
.FixedCapacity()
.Build();


// Create synchronized (thread-safe) wrapper
var stack = ScyllaStack<Task>.CreateBuilder()
.WithCapacity(128)
.Synchronized()
.Build();

Methods

Build()

Builds the configured stack and returns it as IScyllaCollection<T>.

Declaration
public IScyllaCollection<T> Build()
Returns
Type Description
IScyllaCollection<T>

A configured IScyllaCollection<T> that is either an unsynchronized ScyllaStack<T> or a ScyllaStack<T>.SynchronizedScyllaStack wrapper, depending on whether Synchronized(object) was called.
Remarks

If Synchronized(object) was called, the returned value is a ScyllaStack<T>.SynchronizedScyllaStack wrapping the newly created stack. Otherwise, the raw ScyllaStack<T> is returned. In both cases the return type is the IScyllaCollection<T> interface, which is sufficient for polymorphic usage across queue, stack, and ring-buffer types.

BuildConcrete()

Builds the configured stack and returns the concrete ScyllaStack<T> type.

Declaration
public ScyllaStack<T> BuildConcrete()
Returns
Type Description
ScyllaStack<T>

The configured unsynchronized ScyllaStack<T> instance.
Remarks

Use this method instead of Build() when the concrete type is required (for example, to call GetEnumerator() without boxing, or to access EnsureCapacity(int) directly). This method is incompatible with Synchronized(object): a synchronized build produces a ScyllaStack<T>.SynchronizedScyllaStack wrapper, which is not ScyllaStack<T>, so calling this method after Synchronized(object) throws.

Exceptions
Type Condition
InvalidOperationException

Thrown when Synchronized(object) was called before this method. Use Build() instead to obtain the synchronized wrapper as IScyllaCollection<T>.

FixedCapacity(bool)

Enables or disables fixed-capacity mode on the constructed stack.

Declaration
public ScyllaStack<T>.Builder FixedCapacity(bool value = true)
Parameters
Type Name Description
bool value

Pass true (the default) to enable fixed-capacity mode, or false to allow automatic growth (which is also the default when this method is not called).
Returns
Type Description
ScyllaStack<T>.Builder

This builder instance, enabling method chaining.
Remarks

In fixed-capacity mode the backing buffer is allocated once at construction and never resized. Push operations return false when full rather than triggering a new allocation. This is useful for real-time game code that must avoid GC pressure during gameplay.

Synchronized(object)

Configures Build() to return a ScyllaStack<T>.SynchronizedScyllaStack wrapper that serializes all stack operations behind a single lock.

Declaration
public ScyllaStack<T>.Builder Synchronized(object syncRoot = null)
Parameters
Type Name Description
object syncRoot

An optional external lock object shared with other synchronized collections. If null, the wrapper creates and owns a private lock.
Returns
Type Description
ScyllaStack<T>.Builder

This builder instance, enabling method chaining.
Remarks

When this method is called, Build() returns a ScyllaStack<T>.SynchronizedScyllaStack and BuildConcrete() throws an InvalidOperationException. Use Build() and cast to ScyllaStack<T>.SynchronizedScyllaStack if direct access to the wrapper type is needed.

WithCapacity(int)

Sets the initial capacity of the stack's backing buffer.

Declaration
public ScyllaStack<T>.Builder WithCapacity(int capacity)
Parameters
Type Name Description
int capacity

The initial buffer capacity. Must be at least 1; values of 0 or below are rejected with an ArgumentOutOfRangeException. The constructed stack will clamp any value below 1 to 1, but the builder validates eagerly.
Returns
Type Description
ScyllaStack<T>.Builder

This builder instance, enabling method chaining.
Remarks

The capacity determines how many elements the stack can hold before the first resize (variable-capacity mode) or the maximum number of elements (fixed-capacity mode). Choosing a value close to the expected peak element count avoids unnecessary allocations at runtime.

Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when capacity is less than 1.

Extension Methods