Class ScyllaTypeMap

High-performance type dictionary (type map) that stores values grouped by a CLR Type and a uint numeric ID. Each distinct generic type argument T maps to a dedicated per-type bucket internally backed by a ScyllaMap<TKey, TValue>, providing O(1) average-case lookup, insertion, and removal without boxing.

Inheritance
object
ScyllaTypeMap
Implements
Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public sealed class ScyllaTypeMap : IScyllaCollection
Remarks

Two-level structure. The type map maintains a top-level ScyllaMap<Type, IBucket> that associates each CLR Type with a Bucket<T> instance. Each bucket is a ScyllaMap<uint, T> that maps numeric IDs to values of the exact type. Buckets are created lazily on first insertion and removed automatically when they become empty (via TryRemove<T>(uint, out T)), keeping the top-level table compact.

Key semantics. The composite key is (typeof(T), uint ID). Values are stored under the exact generic type parameter - no inheritance or interface dispatch is performed when resolving the bucket. null is a valid value for reference-type buckets; use Contains<T>(uint) rather than inspecting the output of TryGet<T>(uint, out T) to distinguish a stored null from a missing entry.

Capacity. Two capacity parameters govern growth: typeCapacity controls the initial size of the top-level type table; bucketCapacity controls the initial size of each per-type bucket. Both grow automatically unless fixedCapacity: true is specified, in which case operations that would require growth return false instead.

Thread safety. This class is unsynchronized by default. Use AsSynchronized(object) or the builder's Synchronized() method to obtain a ScyllaTypeMap.SynchronizedScyllaTypeMap wrapper that serializes all operations with a lock.

For plain key/value storage with arbitrary key types, use ScyllaMap<TKey, TValue>. For DOTS/Burst workloads with unmanaged types, use ScyllaMapDOTS<TKey, TValue>. 

// Direct construction
var typeMap = new ScyllaTypeMap(typeCapacity: 64, bucketCapacity: 16, fixedCapacity: true);
// Using fluent builder for complex configuration
var typeMap = ScyllaTypeMap.CreateBuilder()
.WithTypeCapacity(128)
.WithBucketCapacity(32)
.FixedCapacity()
.Synchronized()
.Build();

Constructors

ScyllaTypeMap(int, int, bool, IEqualityComparer<Type>)

Creates a new type map.

Declaration
public ScyllaTypeMap(int typeCapacity = 4, int bucketCapacity = 4, bool fixedCapacity = false, IEqualityComparer<Type> typeComparer = null)
Parameters
Type Name Description
int typeCapacity

Initial capacity for the number of distinct types (rounded up to at least 1)
int bucketCapacity

Initial capacity for each type bucket (rounded up to at least 1)
bool fixedCapacity

If true, operations that would require growth can fail (e.g., adding a new type when the type table is full, or adding a new ID when the bucket is full). If false, the type table and buckets grow automatically when needed.
IEqualityComparer<Type> typeComparer

Optional comparer for Type keys. If null, uses Default.

Properties

BucketDefaultCapacity

Default initial capacity used for new type buckets.

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

Capabilities

Feature/capability flags supported by this type map instance.

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

Count

Total number of mapped (type, id) entries stored across all type buckets.

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

IsEmpty

True if this type map currently contains no entries.

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

IsFixedCapacity

True if this type map does not grow beyond its initial capacities.

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

SyncRoot

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

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

ThreadSafety

Thread-safety guarantees provided by this type map instance.

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

TypeCapacity

Capacity of the internal type table (number of slots).

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

TypeCount

Number of distinct type buckets currently present.

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

Methods

AsSynchronized(object)

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

Declaration
public ScyllaTypeMap.SynchronizedScyllaTypeMap 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
ScyllaTypeMap.SynchronizedScyllaTypeMap

A thread-safe wrapper that synchronizes all operations

Clear()

Removes all entries from the type map, clearing all buckets.

Declaration
public void Clear()

ClearType<T>()

Removes all entries for the specified type bucket T and removes the bucket.

Declaration
public int ClearType<T>()
Returns
Type Description
int

The number of entries removed
Type Parameters
Name Description
T

Bucket type

ContainsType<T>()

Returns true if the map currently contains a bucket for the specified type T.

Declaration
public bool ContainsType<T>()
Returns
Type Description
bool
Type Parameters
Name Description
T

Contains<T>(uint)

Returns true if the specified (type, id) entry exists.

Declaration
public bool Contains<T>(uint id)
Parameters
Type Name Description
uint id

ID to locate
Returns
Type Description
bool
Type Parameters
Name Description
T

Bucket type

CountOf<T>()

Returns the number of entries stored under the specified type bucket T.

Declaration
public int CountOf<T>()
Returns
Type Description
int

Number of entries in the bucket; 0 if no bucket exists
Type Parameters
Name Description
T

Bucket type

CreateBuilder()

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

Declaration
public static ScyllaTypeMap.Builder CreateBuilder()
Returns
Type Description
ScyllaTypeMap.Builder

A new builder instance for configuring ScyllaTypeMap construction
Remarks
var typeMap = ScyllaTypeMap.CreateBuilder()
.WithTypeCapacity(64)
.WithBucketCapacity(16)
.FixedCapacity()
.Build();

GetDiagnosticEntries(List<DiagnosticEntry>)

Appends one ScyllaTypeMap.DiagnosticEntry per stored (type, id) entry to the given list and returns the number of entries appended.

Declaration
public int GetDiagnosticEntries(List<ScyllaTypeMap.DiagnosticEntry> results)
Parameters
Type Name Description
List<ScyllaTypeMap.DiagnosticEntry> results

The list to append entries to. Must not be null.
Returns
Type Description
int

The number of entries appended
Remarks

This is a diagnostic API for tooling (inspectors, debug overlays, log dumps). It boxes every stored value and must never be called from hot paths. The caller's list is appended to, not cleared. Enumeration order is unspecified.

This capability is intentionally not reflected in Capabilities; it is not part of the collection contract and exists purely for diagnostics.

Exceptions
Type Condition
ArgumentNullException

Thrown when results is null

TryAdd<T>(uint, T)

Attempts to add a new entry under (type T, id). Returns false if the entry already exists or capacity constraints prevent insertion.

Declaration
public bool TryAdd<T>(uint id, T value)
Parameters
Type Name Description
uint id

ID to add
T value

Value to store (may be null for reference types)
Returns
Type Description
bool

True if added, false otherwise
Type Parameters
Name Description
T

Bucket type

TryGet<T>(uint, out T)

Attempts to get the value stored under (type T, id). Returns true if the key exists (even if the stored value is null for reference types).

Declaration
public bool TryGet<T>(uint id, out T value)
Parameters
Type Name Description
uint id

ID to lookup
T value

When this method returns, contains the value if found; otherwise default
Returns
Type Description
bool

True if the entry exists, false otherwise
Type Parameters
Name Description
T

Bucket type

TryRemove<T>(uint, out T)

Attempts to remove the entry stored under (type T, id). When this method returns, value contains the removed value if successful.

Declaration
public bool TryRemove<T>(uint id, out T value)
Parameters
Type Name Description
uint id

ID to remove
T value

When this method returns, contains the removed value if successful; otherwise default
Returns
Type Description
bool

True if removed, false if not found
Type Parameters
Name Description
T

Bucket type

TrySet<T>(uint, T)

Attempts to set the value for (type T, id). If the entry exists it is updated; otherwise it is added (upsert). Returns false only if a new entry must be added but capacity constraints prevent insertion.

Declaration
public bool TrySet<T>(uint id, T value)
Parameters
Type Name Description
uint id

ID to set
T value

Value to store (may be null for reference types)
Returns
Type Description
bool

True if set/added, false if insertion was required but failed
Type Parameters
Name Description
T

Bucket type

Implements

Extension Methods