Class ScyllaMap<TKey, TValue>

High-performance key/value map (dictionary-like) implemented with open addressing and linear probing over power-of-two-sized parallel arrays for keys, values, and slot state bytes.

Inheritance
object
ScyllaMap<TKey, TValue>
Implements
IScyllaMap<TKey, TValue>
Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public sealed class ScyllaMap<TKey, TValue> : IScyllaMap<TKey, TValue>, IScyllaCollection
Type Parameters
Name Description
TKey

The type of keys stored in the map. Reference-type keys must not be null; passing null throws ArgumentNullException. Value-type keys have no restrictions.
TValue

The type of values associated with each key. null is a valid value for reference types.
Remarks

Algorithm. Each slot carries one of three states - empty, occupied, or deleted (tombstone). Insertions probe forward from the hash-derived home slot and write into the first empty or deleted slot encountered, preferring the earliest deleted slot to recycle capacity without disrupting probe chains. Lookups and removals stop at the first empty slot, so tombstones are essential for correctness after removals. Tombstones are compacted back to empty during a rehash.

Capacity. The internal table length is always a power of two so that the modulo reduction can be computed with a cheap bitwise AND. By default the table grows (doubles) when the combined count of live entries plus tombstones reaches 72 % of capacity, or when tombstones exceed 25 % of capacity. Pass fixedCapacity: true to disable growth; in that mode only tombstone compaction is performed and insertions fail gracefully instead of throwing.

Performance. Average-case lookups, insertions, and removals are O(1). Rehashing is O(n) and amortized over subsequent insertions for growable maps. No LINQ, no boxing, no interface dispatch on hot paths. Enumeration is allocation-free when using the concrete GetEnumerator() method (value-type enumerator pattern).

Thread safety. This class is unsynchronized by default. Use AsSynchronized(object) or the builder's Synchronized() method to obtain a ScyllaMap<TKey, TValue>.SynchronizedScyllaMap wrapper that serializes all operations with a lock.

For DOTS/Burst-compatible workloads that require unmanaged key and value types, use ScyllaMapDOTS<TKey, TValue> instead. For type-keyed storage without boxing, use ScyllaTypeMap. 

// Direct construction
var map = new ScyllaMap<string, int>(capacity: 64, fixedCapacity: true, comparer: StringComparer.OrdinalIgnoreCase);
// Using fluent builder for complex configuration
var map = ScyllaMap<string, User>.CreateBuilder()
.WithCapacity(128)
.WithComparer(StringComparer.OrdinalIgnoreCase)
.Synchronized()
.Build();

Constructors

ScyllaMap(int, bool, IEqualityComparer<TKey>)

Creates a new map.

Declaration
public ScyllaMap(int capacity = 4, bool fixedCapacity = false, IEqualityComparer<TKey> comparer = null)
Parameters
Type Name Description
int capacity

Initial capacity (rounded up to at least 1)
bool fixedCapacity

If true, insertions that require growth will fail (no rehash to larger capacity). If false, the map grows automatically when needed.
IEqualityComparer<TKey> comparer

Optional key comparer. If null, uses Default.

Properties

Capabilities

Feature/capability flags supported by this map instance.

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

Capacity

Current capacity (number of internal slots). Note: capacity is maintained as a power of two for fast masking.

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

Count

Current number of key/value pairs stored in the map.

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

IsEmpty

True if the map contains no entries.

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

IsFixedCapacity

True if this map does not grow beyond its initial capacity.

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

SyncRoot

Synchronization root for externally coordinating operations. This map is unsynchronized by default.

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

ThreadSafety

Thread-safety guarantees provided by this map instance.

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

Methods

AsSynchronized(object)

Creates and returns a thread-safe synchronized wrapper around this map.

Declaration
public ScyllaMap<TKey, TValue>.SynchronizedScyllaMap AsSynchronized(object syncRoot = null)
Parameters
Type Name Description
object syncRoot

Optional external lock object to use for synchronization. If null, the wrapper creates and owns a private lock.
Returns
Type Description
ScyllaMap<TKey, TValue>.SynchronizedScyllaMap

A thread-safe wrapper that synchronizes all operations

Clear()

Removes all entries from the map, resetting it to an empty state. For reference types, clears references to prevent memory leaks.

Declaration
public void Clear()

ContainsKey(TKey)

Returns true if the map currently contains the specified key.

Declaration
public bool ContainsKey(TKey key)
Parameters
Type Name Description
TKey key

Key to locate
Returns
Type Description
bool

True if the key exists, false otherwise

CreateBuilder()

Creates a new fluent builder for configuring and constructing a ScyllaMap instance. The builder provides a discoverable API for setting capacity, fixed-capacity mode, key comparer, and synchronized wrappers.

Declaration
public static ScyllaMap<TKey, TValue>.Builder CreateBuilder()
Returns
Type Description
ScyllaMap<TKey, TValue>.Builder

A new builder instance for configuring ScyllaMap construction
Remarks
var map = ScyllaMap<string, int>.CreateBuilder()
.WithCapacity(64)
.WithComparer(StringComparer.OrdinalIgnoreCase)
.Build();

EnsureCapacity(int)

Ensures the map can hold at least the specified number of entries without resizing.

Declaration
public void EnsureCapacity(int minCapacity)
Parameters
Type Name Description
int minCapacity

Minimum capacity to ensure
Exceptions
Type Condition
InvalidOperationException

Thrown when called on a fixed-capacity map that cannot grow

GetEnumerator()

Returns an enumerator that iterates through the map over occupied entries. The enumerator is a value type, enabling allocation-free enumeration when using the concrete type.

Declaration
public ScyllaMap<TKey, TValue>.Enumerator GetEnumerator()
Returns
Type Description
ScyllaMap<TKey, TValue>.Enumerator

TryAdd(TKey, TValue)

Attempts to add a key/value pair. Returns false if the key already exists or insertion fails.

Declaration
public bool TryAdd(TKey key, TValue value)
Parameters
Type Name Description
TKey key

Key to add
TValue value

Value to associate with the key
Returns
Type Description
bool

True if added, false if key already exists or capacity constraints prevent insertion

TryGetValue(TKey, out TValue)

Attempts to get the value for the specified key.

Declaration
public bool TryGetValue(TKey key, out TValue value)
Parameters
Type Name Description
TKey key

Key to lookup
TValue value

When this method returns, contains the value if found, or default if not found
Returns
Type Description
bool

True if the key exists, false otherwise

TryRemove(TKey)

Attempts to remove a key. Returns false if the key does not exist.

Declaration
public bool TryRemove(TKey key)
Parameters
Type Name Description
TKey key

Key to remove
Returns
Type Description
bool

True if removed, false if the key was not found

TryRemove(TKey, out TValue)

Attempts to remove a key and retrieve its value. Returns false if the key does not exist.

Declaration
public bool TryRemove(TKey key, out TValue value)
Parameters
Type Name Description
TKey key

Key to remove
TValue value

When this method returns, contains the removed value if successful, or default if not found
Returns
Type Description
bool

True if removed, false if the key was not found

TrySet(TKey, TValue)

Attempts to set the value for an existing key. Returns false if the key does not exist.

Declaration
public bool TrySet(TKey key, TValue value)
Parameters
Type Name Description
TKey key

Key to update
TValue value

New value
Returns
Type Description
bool

True if updated, false if the key was not found

Implements

Extension Methods