Struct ScyllaMapDOTS<TKey, TValue>

Burst/DOTS-friendly fixed-capacity key/value map backed by a Unity Unity.Collections.NativeHashMap<TKey, TValue>. Designed for use in native job contexts and performance-critical systems where managed allocations and garbage collection must be avoided.

Implements

IScyllaCollection<ScyllaMapEntry<TKey, 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 ScyllaMapDOTS<TKey, TValue> : IScyllaCollection<ScyllaMapEntry<TKey, TValue>>, IScyllaCollection, IDisposable where TKey : unmanaged, IEquatable<TKey> where TValue : unmanaged

Type Parameters

Name	Description
TKey	The key type. Must be unmanaged and implement IEquatable<T>.
TValue	The value type. Must be unmanaged.

Remarks

Separation from managed map. This type is intentionally separate from the managed ScyllaMap<TKey, TValue>. Both share the IScyllaMap<TKey, TValue> interface semantics, but ScyllaMapDOTS<TKey, TValue> requires unmanaged type arguments and an explicit Unity Allocator, and must be disposed via Dispose() to release native memory.

Fixed-capacity semantics. The capacity is fixed at construction time. Inserting a new key when the map is full returns false. However, calling TryAdd(TKey, TValue) with a key that already exists performs an update and succeeds regardless of capacity.

Update-on-duplicate behaviour. Unlike TryAdd(TKey, TValue), which rejects duplicates, TryAdd(TKey, TValue) on this type updates the value when the key already exists. This mirrors the upsert pattern common in DOTS workflows where re-registering a key should overwrite the previous binding.

Iteration order. Enumeration order is undefined; it follows the internal hash map layout.

Thread safety. Unsynchronized by default, matching Scylla collection conventions. Do not share a single instance across threads without external synchronization.

Lifecycle. Call Dispose() when the map is no longer needed to free the underlying native memory. Accessing a disposed or uncreated map through any method other than IsCreated throws InvalidOperationException.

// Direct construction
var map = new ScyllaMapDOTS<int, float>(capacity: 64, allocator: Allocator.Persistent);
// Using fluent builder for complex configuration
var map = ScyllaMapDOTS<int, float>.CreateBuilder()
.WithCapacity(128)
.WithAllocator(Allocator.Persistent)
.Build();

Constructors

ScyllaMapDOTS(int, Allocator)

Initializes a new fixed-capacity DOTS map backed by a Unity.Collections.NativeHashMap<TKey, TValue> allocated with the specified Unity allocator.

Declaration

public ScyllaMapDOTS(int capacity, Allocator allocator)

Parameters

Type	Name	Description
int	capacity	The maximum number of entries the map may hold. Values less than 1 are clamped to 1. Unlike the managed ScyllaMap<TKey, TValue>, this capacity is a hard upper bound and is not rounded to a power of two internally; the underlying NativeHashMap manages its own bucket sizing.
Allocator	allocator	The Unity memory allocator to use for the internal native hash map. Must not be Unity.Collections.Allocator.None. Common choices: Allocator.Persistent - long-lived map (e.g. game-session lifetime). Allocator.TempJob - single-frame map passed to a job. Allocator.Temp - very short-lived map within the same frame.

Exceptions

Type	Condition
ArgumentException	Thrown when allocator is Unity.Collections.Allocator.None.

Properties

Capabilities

Gets the capability flags describing optional operations supported by this map instance. Includes HasCapacity, SupportsPeek, SupportsCopyTo, SupportsKeyLookup, and SupportsContains.

Declaration

public ScyllaCollectionCapabilities Capabilities { get; }

Property Value

Type	Description
ScyllaCollectionCapabilities

Capacity

Gets the fixed capacity specified at construction time - the maximum number of entries the map may hold simultaneously. Returns 0 when IsCreated is false.

Declaration

public int Capacity { get; }

Property Value

Type	Description
int

Count

Gets the number of live key/value pairs currently stored in the map. Returns 0 when IsCreated is false.

Declaration

public int Count { get; }

Property Value

Type	Description
int

FreeCount

Gets the number of additional new-key insertions that are permitted before the map reaches its fixed capacity. Returns 0 when IsCreated is false or when the map is already full.

Declaration

public int FreeCount { get; }

Property Value

Type	Description
int

IsCreated

Gets whether the underlying Unity.Collections.NativeHashMap<TKey, TValue> has been created and not yet disposed. When false, the map was either never constructed through the public constructor or has already been disposed via Dispose().

Declaration

public bool IsCreated { get; }

Property Value

Type	Description
bool

IsEmpty

Gets whether the map contains no entries. Equivalent to Count == 0.

Declaration

public bool IsEmpty { get; }

Property Value

Type	Description
bool

IsFull

Gets whether the map has reached its fixed capacity, meaning no additional new keys can be inserted until at least one entry is removed. Existing keys can still be updated.

Declaration

public bool IsFull { get; }

Property Value

Type	Description
bool

SyncRoot

Returns null because this map is unsynchronized and does not own a lock object. Callers that need thread safety must provide their own external synchronization mechanism.

Declaration

public object SyncRoot { get; }

Property Value

Type	Description
object

ThreadSafety

Gets Unsynchronized, indicating that this map provides no internal locking. Concurrent access requires external synchronization.

Declaration

public ScyllaCollectionThreadSafety ThreadSafety { get; }

Property Value

Type	Description
ScyllaCollectionThreadSafety

Methods

Clear()

Removes all entries from the map without deallocating the underlying native memory. After this call Count is zero and IsCreated remains true.

Declaration

public void Clear()

Exceptions

Type	Condition
InvalidOperationException	Thrown if this instance has not been created or has already been disposed.

ContainsKey(TKey)

Determines whether the map contains an entry for the specified key.

Declaration

public bool ContainsKey(TKey key)

Parameters

Type	Name	Description
TKey	key	The key to locate.

Returns

Type	Description
bool	true if an entry for key exists; false otherwise.

Exceptions

Type	Condition
InvalidOperationException	Thrown if this instance has not been created or has already been disposed.

CopyTo(ScyllaMapEntry<TKey, TValue>[], int)

Copies up to destination.Length - destinationIndex entries into the provided managed array starting at destinationIndex and returns the number of entries actually copied.

Declaration

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

Parameters

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

Returns

Type	Description
int	The number of entries written into destination. At most Min(Count, destination.Length - destinationIndex).

Remarks

Copy order follows internal hash map enumeration order and is undefined. If the available space in the array is shorter than Count, only the available number of entries is copied; the rest are silently skipped.

Exceptions

Type	Condition
ArgumentNullException	Thrown when destination is null.
ArgumentOutOfRangeException	Thrown when destinationIndex is negative or greater than destination.Length.
InvalidOperationException	Thrown if this instance has not been created or has already been disposed.

CopyTo(Span<ScyllaMapEntry<TKey, TValue>>)

Copies up to destination.Length entries into the provided Span<T> buffer and returns the number of entries actually copied.

Declaration

public int CopyTo(Span<ScyllaMapEntry<TKey, TValue>> destination)

Parameters

Type	Name	Description
Span<ScyllaMapEntry<TKey, TValue>>	destination	The destination span to write entries into. Entries are written starting at index 0. If the span length is 0, the method returns 0 immediately.

Returns

Type	Description
int	The number of entries written into destination. At most Min(Count, destination.Length).

Remarks

Copy order follows internal hash map enumeration order and is undefined. If the destination span is shorter than Count, only destination.Length entries are copied; the rest are silently skipped.

Exceptions

Type	Condition
InvalidOperationException	Thrown if this instance has not been created or has already been disposed.

CreateBuilder()

Creates a new builder instance for configuring a ScyllaMapDOTS<TKey, TValue>.

Declaration

public static ScyllaMapDOTS<TKey, TValue>.Builder CreateBuilder()

Returns

Type	Description
ScyllaMapDOTS<TKey, TValue>.Builder	A new builder instance

Dispose()

Releases the native memory owned by the underlying Unity.Collections.NativeHashMap<TKey, TValue>. After disposal, IsCreated returns false and any further operation on this instance (other than reading IsCreated) throws InvalidOperationException.

Declaration

public void Dispose()

Remarks

It is safe to call Dispose() on an already-disposed instance; subsequent calls are no-ops because the check _map.IsCreated guards the disposal.

Remove(TKey)

Removes the entry for the specified key if it is present.

Declaration

public bool Remove(TKey key)

Parameters

Type	Name	Description
TKey	key	The key to remove.

Returns

Type	Description
bool	true if the key was found and its entry was removed; false if the key did not exist in the map.

Exceptions

Type	Condition
InvalidOperationException	Thrown if this instance has not been created or has already been disposed.

TryAdd(ScyllaMapEntry<TKey, TValue>)

Attempts to insert or update the entry represented by the specified ScyllaMapEntry<TKey, TValue>. Delegates to TryAdd(TKey, TValue) using the entry's Key and Value fields.

Declaration

public bool TryAdd(ScyllaMapEntry<TKey, TValue> item)

Parameters

Type	Name	Description
ScyllaMapEntry<TKey, TValue>	item	The entry to add or update.

Returns

Type	Description
bool	true if the entry was successfully added or updated; false if the map is at capacity and the key is new.

Exceptions

Type	Condition
InvalidOperationException	Thrown if this instance has not been created or has already been disposed.

TryAdd(TKey, TValue)

Attempts to insert or update the entry for the specified key.

Declaration

public bool TryAdd(TKey key, TValue value)

Parameters

Type	Name	Description
TKey	key	The key to insert or update.
TValue	value	The value to associate with key.

Returns

Type	Description
bool	true if the entry was successfully added or updated; false if the map is at capacity and the key is new.

Remarks

If key already exists in the map, the existing entry is removed and re-inserted with value, and the method returns true.

If key does not exist and the map has not yet reached its fixed capacity (Capacity), the entry is inserted and the method returns true.

If key does not exist and the map is already at capacity, the method returns false without modifying the map.

This upsert behaviour differs from TryAdd(TKey, TValue), which strictly rejects duplicate keys. It mirrors common DOTS patterns where re-registering a key should overwrite the previous value.

Exceptions

Type	Condition
InvalidOperationException	Thrown if this instance has not been created or has already been disposed.

TryGetValue(TKey, out TValue)

Attempts to retrieve the value associated with the specified key.

Declaration

public bool TryGetValue(TKey key, out TValue value)

Parameters

Type	Name	Description
TKey	key	The key to look up.
TValue	value	When this method returns true, the value stored under key; otherwise the default value for TValue.

Returns

Type	Description
bool	true if the key was found; false otherwise.

Exceptions

Type	Condition
InvalidOperationException	Thrown if this instance has not been created or has already been disposed.

TryPeek(out ScyllaMapEntry<TKey, TValue>)

Returns an arbitrary entry from the map without removing it. The specific entry returned is determined by the internal hash map enumeration order and is not guaranteed to be consistent across calls or map modifications.

Declaration

public bool TryPeek(out ScyllaMapEntry<TKey, TValue> item)

Parameters

Type	Name	Description
ScyllaMapEntry<TKey, TValue>	item	When this method returns true, an entry (key and value) currently present in the map; otherwise the default ScyllaMapEntry<TKey, TValue>.

Returns

Type	Description
bool	true if an entry was found and written to item; false if the map is empty.

Exceptions

Type	Condition
InvalidOperationException	Thrown if this instance has not been created or has already been disposed.

TryRemove(out ScyllaMapEntry<TKey, TValue>)

Removes and returns an arbitrary entry from the map. The specific entry removed is determined by the internal hash map enumeration order and is not guaranteed to be consistent across calls.

Declaration

public bool TryRemove(out ScyllaMapEntry<TKey, TValue> item)

Parameters

Type	Name	Description
ScyllaMapEntry<TKey, TValue>	item	When this method returns true, the entry that was removed (key and value); otherwise the default ScyllaMapEntry<TKey, TValue>.

Returns

Type	Description
bool	true if an entry was removed; false if the map is empty.

Exceptions

Type	Condition
InvalidOperationException	Thrown if this instance has not been created or has already been disposed.

Implements

IScyllaCollection<T>

IScyllaCollection

IDisposable