Class ScyllaAdjacencyListGraph<TNodeData, TEdgeData>
Generic mutable adjacency list graph that associates an arbitrary user-data value of
type TNodeData with every node and an arbitrary value of type
TEdgeData with every edge. Structural operations are delegated
to an internal ScyllaAdjacencyListGraph; per-node and per-edge payloads
are maintained in parallel ScyllaMap<TKey, TValue> stores.
Implements
Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public sealed class ScyllaAdjacencyListGraph<TNodeData, TEdgeData> : IScyllaMutableGraph<TNodeData, TEdgeData>, IScyllaReadOnlyGraph<TNodeData, TEdgeData>, IScyllaMutableGraph<TNodeData>, IScyllaReadOnlyGraph<TNodeData>, IScyllaMutableGraph, IScyllaReadOnlyGraph, IScyllaGraph, IScyllaCollection
Type Parameters
| Name | Description |
|---|---|
| TNodeData | The type of user data stored per node. May be any reference or value type.
When nodes are added without explicit data, |
| TEdgeData | The type of user data stored per edge. May be any reference or value type.
When edges are added via the untyped overload, |
Remarks
Edge data storage: edge data entries are stored in per-node
List<TEdgeData> lists keyed by
the source node ID, maintaining a 1-to-1 positional correspondence with the
underlying structural edge list of the inner graph. Adding a new edge appends a
data entry at the matching position; removing an edge identifies the edge's
list index before removal and removes the corresponding data entry at the same index.
This positional coupling means that the order of edge insertions matters for correct
edge-data alignment.
Parallel edge caveat: when parallel edges are enabled, only the first matching entry in the edge list is removed by TryRemoveEdge(int, int) (the behaviour mirrors the structural graph). The corresponding data entry at that index is removed as well. Subsequent parallel edges and their data remain intact.
Node removal: TryRemoveNode(int) removes the node from the structural graph, the node-data map, and the edge-data map atomically. The edge-data lists of neighbours are not modified because the structural graph already cleans up the corresponding structural edge entries; the neighbour's edge lists stay in sync with the structural adjacency list.
All other behavioural characteristics are inherited from ScyllaAdjacencyListGraph. See that class for performance notes, thread-safety guidance, and directed/undirected semantics.
Constructors
ScyllaAdjacencyListGraph(bool, bool, int, bool, bool)
Creates a new typed adjacency list graph with per-node and per-edge user data. The configuration parameters mirror those of ScyllaAdjacencyListGraph; refer to that class for a detailed description of each parameter.
Declaration
public ScyllaAdjacencyListGraph(bool isDirected = true, bool isWeighted = false, int capacity = 16, bool allowsSelfLoops = false, bool allowsParallelEdges = false)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | isDirected |
|
| bool | isWeighted |
|
| int | capacity | Initial node capacity for the structural graph, the node-data map, and the
edge-data map. Values below 1 are clamped to 1 by the underlying graph.
Defaults to |
| bool | allowsSelfLoops |
|
| bool | allowsParallelEdges |
|
Properties
Capabilities
Gets the feature and capability flags supported by this collection instance.
Declaration
public ScyllaCollectionCapabilities Capabilities { get; }
Property Value
| Type | Description |
|---|---|
| ScyllaCollectionCapabilities | A bitfield of ScyllaCollectionCapabilities flags describing which optional operations the concrete instance supports. The value None indicates that only the base contract (Count, IsEmpty, Clear()) is available. |
Remarks
Use Capabilities for feature detection in place of type-casting. For example:
if ((collection.Capabilities & ScyllaCollectionCapabilities.SupportsPeek) != 0)
{
// safe to call TryPeek through IScyllaCollection<T>
}
Synchronized wrappers cache the capability flags of their inner collection at construction time, so the value returned is stable and does not require synchronization.
See Also
Count
Gets the number of items currently contained in the collection.
Declaration
public int Count { get; }
Property Value
| Type | Description |
|---|---|
| int | A non-negative integer representing the current element count.
Returns |
Remarks
On unsynchronized collections, Count is not thread-safe and may return a stale
value when accessed concurrently. On synchronized wrappers, reading Count is
protected by the internal lock.
EdgeCount
Gets the number of edges currently contained in the graph.
Declaration
public int EdgeCount { get; }
Property Value
| Type | Description |
|---|---|
| int | A non-negative integer representing the total edge count.
Returns |
Remarks
For undirected graphs, each conceptual edge is counted exactly once, even though the underlying storage may maintain adjacency entries in both directions. For directed graphs, each directed edge is counted independently, so a pair of reciprocal edges (A→B and B→A) contributes 2 to the count.
IsEmpty
Gets a value indicating whether the collection contains no items.
Declaration
public bool IsEmpty { get; }
Property Value
| Type | Description |
|---|---|
| bool |
|
Remarks
This is a convenience property equivalent to Count == 0. Prefer it over comparing
Count directly when the actual count is not needed, as some implementations may
compute it more efficiently.
NodeCount
Gets the number of nodes currently contained in the graph.
Declaration
public int NodeCount { get; }
Property Value
| Type | Description |
|---|---|
| int | A non-negative integer representing the total node count.
Returns |
Remarks
This property is the canonical source of the node count and is also surfaced through
the inherited Count property. For clarity, prefer
NodeCount over Count in graph-specific code so the intent is explicit.
Properties
Gets the structural property flags that describe this graph instance.
Declaration
public ScyllaGraphProperties Properties { get; }
Property Value
| Type | Description |
|---|---|
| ScyllaGraphProperties | A bitfield of ScyllaGraphProperties flags set at construction time. The value is stable for the lifetime of the graph and does not change as nodes or edges are added or removed. |
Remarks
Use this property for feature detection rather than type-casting. For example,
check Directed before interpreting the
directionality of edges returned by GetNeighborsNonAlloc(int, Span<ScyllaGraphEdge>), or check
Weighted before relying on edge weight values.
Pathfinding and traversal algorithms in ScyllaGraphAlgorithms inspect this
property to select the appropriate implementation branch.
See Also
SyncRoot
Gets the synchronization root object used to externally coordinate multi-step operations with this collection.
Declaration
public object SyncRoot { get; }
Property Value
| Type | Description |
|---|---|
| object | A non-null object suitable for use with |
Remarks
When this collection is a synchronized wrapper, SyncRoot must be non-null and
stable for the entire lifetime of the wrapper. All internal operations on the wrapper
must lock on this same object. This allows callers to perform atomic multi-step
sequences:
lock (collection.SyncRoot)
{
if (!collection.IsEmpty)
typedCollection.TryRemove(out var item);
}
For unsynchronized collections (SyncRoot == null), callers are responsible for
supplying and consistently applying their own external synchronization mechanism.
A null SyncRoot does not mean the collection is thread-safe;
consult ThreadSafety for the authoritative guarantee.
See Also
ThreadSafety
Gets the thread-safety guarantees provided by this collection instance.
Declaration
public ScyllaCollectionThreadSafety ThreadSafety { get; }
Property Value
| Type | Description |
|---|---|
| ScyllaCollectionThreadSafety | A ScyllaCollectionThreadSafety value indicating whether the collection is unsynchronized, synchronized via a lock, or safe for lock-free concurrent access. Most core implementations return Unsynchronized. Synchronized wrappers return Synchronized. |
Remarks
Always check this property (or SyncRoot) before assuming a collection is
safe for concurrent use. Do not rely solely on the absence of a non-null SyncRoot
to infer thread safety; use this property as the authoritative source.
See Also
Methods
Clear()
Removes all nodes and edges from the graph and clears both the node-data map and the edge-data map. The pre-allocated internal storage capacity is retained.
Declaration
public void Clear()
ContainsEdge(int, int)
Determines whether the graph contains an edge between the specified nodes.
Declaration
public bool ContainsEdge(int fromID, int toID)
Parameters
| Type | Name | Description |
|---|---|---|
| int | fromID | The ID of the source (or first) node. |
| int | toID | The ID of the target (or second) node. |
Returns
| Type | Description |
|---|---|
| bool |
|
Remarks
For undirected graphs, the argument order does not matter: calling
ContainsEdge(A, B) and ContainsEdge(B, A) always return the same
result. For directed graphs, only the edge in the specified direction is checked;
the reverse direction is independent.
If either fromID or toID does not
correspond to an existing node, the method returns false.
ContainsNode(int)
Determines whether the graph contains a node with the specified ID.
Declaration
public bool ContainsNode(int nodeID)
Parameters
| Type | Name | Description |
|---|---|---|
| int | nodeID | The integer ID of the node to look up. |
Returns
| Type | Description |
|---|---|
| bool |
|
CopyAllEdges(Span<ScyllaGraphEdge>)
Copies all edge descriptors from the graph into the provided span without allocating any managed memory.
Declaration
public int CopyAllEdges(Span<ScyllaGraphEdge> destination)
Parameters
| Type | Name | Description |
|---|---|---|
| Span<ScyllaGraphEdge> | destination | The caller-supplied span into which ScyllaGraphEdge descriptors will be written. The span should be at least EdgeCount elements long to receive all edges; if it is smaller, only as many edges as fit are copied. |
Returns
| Type | Description |
|---|---|
| int | The number of ScyllaGraphEdge descriptors written to
|
Remarks
For undirected graphs, each conceptual edge is copied exactly once. The FromID and ToID fields reflect the canonical storage direction and may not match the order in which the edge was originally added.
For directed graphs, each directed edge appears as a separate descriptor; reciprocal edges (A→B and B→A) produce two distinct entries.
The order of edges within destination is
implementation-defined and should not be relied upon. For typed edge graphs,
retrieve per-edge user data via
TryGetEdgeData(int, int, out TEdgeData)
after copying the base descriptors.
See Also
CopyAllNodes(Span<ScyllaGraphNode>)
Copies all node descriptors from the graph into the provided span without allocating any managed memory.
Declaration
public int CopyAllNodes(Span<ScyllaGraphNode> destination)
Parameters
| Type | Name | Description |
|---|---|---|
| Span<ScyllaGraphNode> | destination | The caller-supplied span into which ScyllaGraphNode descriptors will be written. The span should be at least NodeCount elements long to receive all nodes; if it is smaller, only as many nodes as fit are copied. |
Returns
| Type | Description |
|---|---|
| int | The number of ScyllaGraphNode descriptors written to
|
Remarks
The order in which nodes are written into destination is
implementation-defined. Callers must not assume any particular ordering.
For typed graphs, this method copies only the base descriptor (ID and flags). To retrieve per-node user data alongside the descriptor, call TryGetNodeData(int, out TNodeData) for each node after copying. See the remarks on that interface for guidance on performing typed bulk operations.
See Also
EnsureCapacity(int)
Ensures the internal structural graph, node-data map, and edge-data map can all
accommodate at least minNodeCapacity nodes without reallocation.
Declaration
public void EnsureCapacity(int minNodeCapacity)
Parameters
| Type | Name | Description |
|---|---|---|
| int | minNodeCapacity | The minimum number of nodes to pre-allocate for. |
GetNeighborCount(int)
Returns the number of outgoing neighbors (adjacent nodes) for the specified node.
Declaration
public int GetNeighborCount(int nodeID)
Parameters
| Type | Name | Description |
|---|---|---|
| int | nodeID | The ID of the node to query. |
Returns
| Type | Description |
|---|---|
| int | The number of outgoing edges from the specified node, or |
Remarks
The sentinel value -1 is used instead of a separate bool-returning
overload to keep the API lightweight for high-frequency graph traversal loops.
Callers that need to distinguish "zero neighbors" from "node not found" should
check the return value against -1 explicitly.
For undirected graphs, every stored edge is counted in both directions, so the neighbor count equals the degree of the node. For directed graphs, only outgoing edges are counted (the out-degree).
GetNeighborsNonAlloc(int, Span<ScyllaGraphEdge<TEdgeData>>)
Copies the outgoing typed edges of the specified node into the provided span,
combining each structural ScyllaGraphEdge with its corresponding
TEdgeData payload into a ScyllaGraphEdge<TEdgeData>.
If the destination span is smaller than the node's edge count, only as many entries
as fit are copied.
Declaration
public int GetNeighborsNonAlloc(int nodeID, Span<ScyllaGraphEdge<TEdgeData>> destination)
Parameters
| Type | Name | Description |
|---|---|---|
| int | nodeID | The ID of the node whose typed neighbours to copy. |
| Span<ScyllaGraphEdge<TEdgeData>> | destination | Caller-provided span that receives the ScyllaGraphEdge<TEdgeData> descriptors. |
Returns
| Type | Description |
|---|---|
| int | The number of entries copied into |
Remarks
Internally, the structural edges are retrieved into a temporary buffer. A
stack-allocated buffer is used when the destination length is 128 or fewer to
avoid heap pressure. For each structural edge at index i, the corresponding
edge-data entry at the same index in the per-node list is paired in. If the
edge-data list is shorter than the copied structural edge count (e.g. due to an
inconsistency), default(TEdgeData) is used as the fallback.
GetNeighborsNonAlloc(int, Span<ScyllaGraphEdge>)
Copies the outgoing edges of the specified node into the provided span without allocating any managed memory.
Declaration
public int GetNeighborsNonAlloc(int nodeID, Span<ScyllaGraphEdge> destination)
Parameters
| Type | Name | Description |
|---|---|---|
| int | nodeID | The ID of the node whose neighbors to retrieve. |
| Span<ScyllaGraphEdge> | destination | The caller-supplied span into which ScyllaGraphEdge descriptors will be written. The span must be allocated by the caller and may reside on the stack or in a rented array to avoid heap allocations in hot paths. |
Returns
| Type | Description |
|---|---|
| int | The number of edge descriptors written to |
Remarks
This method follows the same sentinel convention as GetNeighborCount(int):
a return value of -1 means "node not found", while 0 means "node
exists but has no outgoing edges".
If destination is smaller than the node's actual neighbor
count, only the first destination.Length edges are written. Callers
should use GetNeighborCount(int) to pre-size the span when all edges
must be retrieved. To avoid the extra call in tight loops, allocate a span large
enough for the maximum expected degree.
The order of edges written into destination is
implementation-defined and should not be relied upon across calls.
For graphs that also carry per-edge user data, prefer the typed overload GetNeighborsNonAlloc(int, Span<ScyllaGraphEdge<TEdgeData>>) which fills ScyllaGraphEdge<TEdgeData> descriptors instead. The untyped overload defined here remains available through the base interface for callers that do not need edge data.
See Also
TryAddEdge(int, int, float)
Attempts to add a structural edge between the two specified nodes and appends
default(TEdgeData) to the source node's edge-data list. Use the typed
overload TryAddEdge(int, int, float, TEdgeData) to provide an explicit
data value at insertion time.
Declaration
public bool TryAddEdge(int fromID, int toID, float weight = 1)
Parameters
| Type | Name | Description |
|---|---|---|
| int | fromID | Source node ID. |
| int | toID | Target node ID. |
| float | weight | Edge weight. Ignored for unweighted graphs. Defaults to |
Returns
| Type | Description |
|---|---|
| bool |
|
TryAddEdge(int, int, float, TEdgeData)
Attempts to add an edge with an explicit TEdgeData payload
between the two specified nodes. The data is appended to the source node's
edge-data list at the position that corresponds to the newly added structural edge.
Declaration
public bool TryAddEdge(int fromID, int toID, float weight, TEdgeData data)
Parameters
| Type | Name | Description |
|---|---|---|
| int | fromID | Source node ID. Must already exist in the graph. |
| int | toID | Target node ID. Must already exist in the graph. |
| float | weight | Edge weight. Ignored for unweighted graphs (stored as |
| TEdgeData | data | User data to associate with the new edge. |
Returns
| Type | Description |
|---|---|
| bool |
|
Remarks
For undirected graphs, only the forward (from→to) edge-data list is updated. The symmetric reverse entry in the structural graph does not have a corresponding edge-data entry; querying edge data in the reverse direction should be done via the canonical forward direction.
TryAddNode(int, ScyllaGraphNodeFlags)
Attempts to add a node with the specified ID and flags, but without associated user data.
An empty TEdgeData list is initialised for the node in the
edge-data map so that subsequent TryAddEdge(int, int, float) calls can store edge data
immediately. No entry is created in the node-data map; call
TrySetNodeData(int, TNodeData) or use the data-bearing
TryAddNode(int, TNodeData, ScyllaGraphNodeFlags) overload to supply node data.
Declaration
public bool TryAddNode(int nodeID, ScyllaGraphNodeFlags flags = ScyllaGraphNodeFlags.Walkable)
Parameters
| Type | Name | Description |
|---|---|---|
| int | nodeID | Unique integer ID for the new node. |
| ScyllaGraphNodeFlags | flags | Initial property flags. Defaults to Walkable. |
Returns
| Type | Description |
|---|---|
| bool |
|
TryAddNode(int, TNodeData, ScyllaGraphNodeFlags)
Attempts to add a node with the specified ID, user data, and flags in a single operation. If the structural insertion succeeds, the data is stored in the node-data map and an empty edge-data list is initialised for the node immediately.
Declaration
public bool TryAddNode(int nodeID, TNodeData data, ScyllaGraphNodeFlags flags = ScyllaGraphNodeFlags.Walkable)
Parameters
| Type | Name | Description |
|---|---|---|
| int | nodeID | Unique integer ID for the new node. |
| TNodeData | data | User data to associate with the new node. |
| ScyllaGraphNodeFlags | flags | Initial property flags. Defaults to Walkable. |
Returns
| Type | Description |
|---|---|
| bool |
|
TryGetEdge(int, int, out ScyllaGraphEdge)
Attempts to retrieve the edge descriptor for the edge between two nodes.
Declaration
public bool TryGetEdge(int fromID, int toID, out ScyllaGraphEdge edge)
Parameters
| Type | Name | Description |
|---|---|---|
| int | fromID | The ID of the source node. For undirected graphs, argument order is irrelevant. |
| int | toID | The ID of the target node. For undirected graphs, argument order is irrelevant. |
| ScyllaGraphEdge | edge | When this method returns |
Returns
| Type | Description |
|---|---|
| bool |
|
Remarks
For undirected graphs, the fromID and toID
arguments are interchangeable. The returned FromID
and ToID will match the canonical storage direction
used internally, which may differ from the argument order supplied.
For directed graphs, only the edge in the direction
(fromID → toID) is looked up.
The reverse direction is independent; call this method again with swapped
arguments to check the reverse edge separately.
To check existence without retrieving the descriptor, prefer ContainsEdge(int, int) which may be implemented more efficiently in some graph representations.
See Also
TryGetEdgeData(int, int, out TEdgeData)
Attempts to retrieve the TEdgeData payload associated
with the edge from fromID to toID.
Declaration
public bool TryGetEdgeData(int fromID, int toID, out TEdgeData data)
Parameters
| Type | Name | Description |
|---|---|---|
| int | fromID | Source node ID of the edge to look up. |
| int | toID | Target node ID of the edge to look up. |
| TEdgeData | data | When this method returns |
Returns
| Type | Description |
|---|---|
| bool |
|
Remarks
The lookup works by scanning the structural adjacency list of the source node to find the positional index of the target edge, then reading the corresponding entry from the per-node edge-data list. A stack-allocated buffer is used for source nodes with 128 or fewer outgoing edges.
TryGetNodeData(int, out TNodeData)
Attempts to retrieve the TNodeData payload associated
with the specified node.
Declaration
public bool TryGetNodeData(int nodeID, out TNodeData data)
Parameters
| Type | Name | Description |
|---|---|---|
| int | nodeID | The ID of the node whose data to retrieve. |
| TNodeData | data | When this method returns |
Returns
| Type | Description |
|---|---|
| bool |
|
TryGetNodeFlags(int, out ScyllaGraphNodeFlags)
Attempts to retrieve the flags associated with the specified node.
Declaration
public bool TryGetNodeFlags(int nodeID, out ScyllaGraphNodeFlags flags)
Parameters
| Type | Name | Description |
|---|---|---|
| int | nodeID | The ID of the node to query. |
| ScyllaGraphNodeFlags | flags | When this method returns |
Returns
| Type | Description |
|---|---|
| bool |
|
Remarks
Node flags are bitpacked into a uint. Bit 0 is the
Walkable flag; bits 1-31 are user-defined
tags (Tag0 through
Tag30) that callers may use for domain-specific
categorization such as terrain type, cost multiplier tier, or zone membership.
Flags can be mutated on mutable graphs via TrySetNodeFlags(int, ScyllaGraphNodeFlags).
See Also
TryRemoveEdge(int, int)
Attempts to remove the edge from fromID to
toID and removes the corresponding entry from the source
node's edge-data list at the same positional index.
Declaration
public bool TryRemoveEdge(int fromID, int toID)
Parameters
| Type | Name | Description |
|---|---|---|
| int | fromID | Source node ID of the edge to remove. |
| int | toID | Target node ID of the edge to remove. |
Returns
| Type | Description |
|---|---|
| bool |
|
Remarks
The method first snapshots the source node's current neighbour list to determine the index of the target edge. A stack-allocated buffer is used when the neighbour count is 128 or fewer to avoid heap allocation. For larger degrees, a heap array is allocated.
Only the first matching edge index is located. When parallel edges are enabled, only the first matching structural edge and its corresponding data entry are removed; subsequent parallel edges remain.
If the source node does not exist or has no outgoing edges, the call falls
through to the structural graph's TryRemoveEdge directly (which will
also return false).
TryRemoveNode(int)
Attempts to remove the node with the specified ID and all its incident edges, and simultaneously removes the corresponding entries from both the node-data map and the edge-data map.
Declaration
public bool TryRemoveNode(int nodeID)
Parameters
| Type | Name | Description |
|---|---|---|
| int | nodeID | The ID of the node to remove. |
Returns
| Type | Description |
|---|---|
| bool |
|
Remarks
The removals from Scylla.Core.Structures.ScyllaAdjacencyListGraph<TNodeData, TEdgeData>._nodeData and Scylla.Core.Structures.ScyllaAdjacencyListGraph<TNodeData, TEdgeData>._edgeData are
best-effort via TryRemove. If either map does not contain an entry for the
node (e.g. the node was added via a path that skipped data initialisation), the
structural removal still succeeds.
TrySetEdgeData(int, int, TEdgeData)
Attempts to replace the TEdgeData payload for an existing
edge from fromID to toID.
Declaration
public bool TrySetEdgeData(int fromID, int toID, TEdgeData data)
Parameters
| Type | Name | Description |
|---|---|---|
| int | fromID | Source node ID of the edge to update. |
| int | toID | Target node ID of the edge to update. |
| TEdgeData | data | The new data value to store for the edge. |
Returns
| Type | Description |
|---|---|
| bool |
|
Remarks
The method scans the source node's structural adjacency list to locate the
positional index of the target edge, then updates the entry at the same index in
the per-node edge-data list. A stack-allocated buffer is used for nodes with 128
or fewer outgoing edges. If the edge exists structurally but its positional index
exceeds the current length of the edge-data list, the method returns false
rather than extending the list.
TrySetNodeData(int, TNodeData)
Attempts to set or replace the TNodeData payload for an
existing node. If the node exists but has no current data entry, the data is
inserted. If the node does not exist, false is returned and no data
is modified.
Declaration
public bool TrySetNodeData(int nodeID, TNodeData data)
Parameters
| Type | Name | Description |
|---|---|---|
| int | nodeID | The ID of the node whose data to update. |
| TNodeData | data | The new data value to store. |
Returns
| Type | Description |
|---|---|
| bool |
|
Remarks
Internally, the method attempts TrySet first (a single-lookup update),
falling back to TryAdd only when no existing data entry is present. This
keeps the common update path to a single map lookup.
TrySetNodeFlags(int, ScyllaGraphNodeFlags)
Attempts to update the flags on an existing node.
Declaration
public bool TrySetNodeFlags(int nodeID, ScyllaGraphNodeFlags flags)
Parameters
| Type | Name | Description |
|---|---|---|
| int | nodeID | The ID of the node to update. |
| ScyllaGraphNodeFlags | flags | The new ScyllaGraphNodeFlags value to assign to the node. Replaces the entire flags value; this is an assignment, not a bitwise OR. To add a flag while preserving existing flags, first retrieve the current value with TryGetNodeFlags(int, out ScyllaGraphNodeFlags), combine it with the new flag, then call this method with the combined value. |
Returns
| Type | Description |
|---|---|
| bool |
|