Class ScyllaCSRGraph<TNodeData>

Immutable CSR graph that stores arbitrary user data of type TNodeData alongside each node, while delegating all topology queries to an inner ScyllaCSRGraph.

Inheritance
object
ScyllaCSRGraph<TNodeData>
Implements
Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public sealed class ScyllaCSRGraph<TNodeData> : IScyllaReadOnlyGraph<TNodeData>, IScyllaReadOnlyGraph, IScyllaGraph, IScyllaCollection
Type Parameters
Name Description
TNodeData

The type of user data stored per node. May be any reference or value type. If no per-edge data is needed, prefer this single-type overload over ScyllaCSRGraph<TNodeData, TEdgeData>.
Remarks

All graph topology (nodes, edges, properties, neighbor iteration) is handled by a wrapped ScyllaCSRGraph instance. This class adds a parallel TNodeData[] array and a private ID-to-index map so that typed node data can be retrieved in O(1) without exposing the base graph's internal index mapping.

The internal _nodeIDToIndex map intentionally duplicates the mapping already held inside ScyllaCSRGraph (which keeps its map private). This is an intentional design trade-off: typed data lookups need O(1) ID-to-index translation without delegating through the base graph's public API. The memory overhead is approximately 24 bytes per node (one ScyllaMap<TKey, TValue> entry).

Like ScyllaCSRGraph, this class is fully immutable after construction. Calling Clear() always throws InvalidOperationException.

The only way to create an instance is via CreateFromGraph(IScyllaReadOnlyGraph<TNodeData>), which converts any IScyllaReadOnlyGraph<TNodeData> into this frozen CSR representation.

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 0 when the collection is empty.
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 0 for a graph with no edges.
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

true when Count is 0; false otherwise.
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 0 for an empty graph.
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 lock when ThreadSafety is Synchronized. Returns null for unsynchronized collections, which do not own a lock.
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()

Not supported. ScyllaCSRGraph<TNodeData> is immutable and cannot be cleared.

Declaration
public void Clear()
Exceptions
Type Condition
InvalidOperationException

Always thrown. Use CreateFromGraph(IScyllaReadOnlyGraph<TNodeData>) to create a new graph instead.

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

true if the edge exists; false otherwise.
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

true if a node with nodeID exists in the graph; false otherwise.

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 destination. This equals Min(EdgeCount, destination.Length).
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 destination. This equals Min(NodeCount, destination.Length).
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

CreateFromGraph(IScyllaReadOnlyGraph<TNodeData>)

Creates a new immutable ScyllaCSRGraph<TNodeData> by converting an existing IScyllaReadOnlyGraph<TNodeData> into CSR format, preserving both the graph topology and all per-node user data.

Declaration
public static ScyllaCSRGraph<TNodeData> CreateFromGraph(IScyllaReadOnlyGraph<TNodeData> source)
Parameters
Type Name Description
IScyllaReadOnlyGraph<TNodeData> source

The typed source graph to convert. Must not be null. Any implementation of IScyllaReadOnlyGraph<TNodeData> is accepted.
Returns
Type Description
ScyllaCSRGraph<TNodeData>

A new ScyllaCSRGraph<TNodeData> containing the same nodes, edges, and per-node data as source, stored in CSR format.
Remarks

Internally, this method first delegates to CreateFromGraph(IScyllaReadOnlyGraph) to build the untyped CSR topology, then queries each node's data from source via TryGetNodeData(int, out TNodeData). If a node's data is not found in the source (returns false), the corresponding slot in the data array is left at default(TNodeData).

Nodes are visited in sorted-by-ID order, matching the internal layout of the constructed base graph.

Exceptions
Type Condition
ArgumentNullException

Thrown when source is null.

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 -1 if no node with nodeID exists in the graph.
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>)

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 destination, which is at most Min(neighborCount, destination.Length); or -1 if no node with nodeID exists in the graph.
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

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 true, contains a ScyllaGraphEdge descriptor with the source ID, target ID, and weight for the requested edge. When the method returns false, the value is default(ScyllaGraphEdge).
Returns
Type Description
bool

true if the edge was found; false if the edge does not exist or either endpoint node is absent from the graph.
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

TryGetNodeData(int, out TNodeData)

Attempts to retrieve the user data 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 should be retrieved.
TNodeData data

When this method returns true, contains the TNodeData value stored for the node. When this method returns false, contains the default value of TNodeData.
Returns
Type Description
bool

true if the node was found and its data was written to data; false if no node with nodeID exists in the graph.

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 true, contains the ScyllaGraphNodeFlags value for the specified node, including the walkability bit and any user-defined tag bits. When the method returns false, the value is ScyllaGraphNodeFlags.None.
Returns
Type Description
bool

true if the node exists in the graph; false otherwise.
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

Implements

Extension Methods

See Also

ScyllaCSRGraph<TNodeData, TEdgeData>