Interface IScyllaGraph

Base interface for all Scylla graph types. Defines the minimal structural query contract - node and edge counts, property flags, containment tests, and allocation-free neighbor access - without implying mutability, enumeration, or typed node/edge payloads.

The inherited Count property returns NodeCount (the number of nodes), consistent with the primary collection element being nodes. Callers who need both counts should prefer the dedicated NodeCount and EdgeCount properties for clarity.

This interface sits at the root of a two-branch hierarchy. The read-only branch (IScyllaReadOnlyGraph) adds full inspection capabilities such as edge retrieval and bulk copy methods. The mutable branch (IScyllaMutableGraph) further extends the read-only branch with node and edge modification operations. Generic typed variants (IScyllaReadOnlyGraph<TNodeData>, IScyllaMutableGraph<TNodeData>) attach per-node and optionally per-edge user data to those branches.

The Properties flags describe fixed structural characteristics such as directionality and weightedness that are established at construction time and do not change during the lifetime of the graph.

Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public interface IScyllaGraph : IScyllaCollection
Remarks

Directed vs. undirected edges. When Properties includes Directed, an edge from node A to node B does not imply an edge from B to A. In undirected graphs the reverse direction is implied and stored accordingly. The ContainsEdge(int, int) and GetNeighborsNonAlloc(int, Span<ScyllaGraphEdge>) methods account for this distinction - see their individual documentation for exact semantics.

Integer node IDs. Nodes are identified by caller-supplied int IDs. The framework imposes no ordering constraints on IDs; they need not be contiguous or start at zero. Callers are responsible for ID uniqueness within a graph instance.

Sentinel return values. Several methods on this interface use -1 as a sentinel to indicate "node not found" in order to keep the API lightweight for high-frequency traversal code. See GetNeighborCount(int) and GetNeighborsNonAlloc(int, Span<ScyllaGraphEdge>) for details.

Properties

EdgeCount

Gets the number of edges currently contained in the graph.

Declaration
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.

NodeCount

Gets the number of nodes currently contained in the graph.

Declaration
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
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

Methods

ContainsEdge(int, int)

Determines whether the graph contains an edge between the specified nodes.

Declaration
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
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.

GetNeighborCount(int)

Returns the number of outgoing neighbors (adjacent nodes) for the specified node.

Declaration
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
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

Extension Methods

See Also