Class ScyllaAdjacencyListGraph.SynchronizedScyllaAdjacencyListGraph

Thread-safe decorator around ScyllaAdjacencyListGraph that serializes all graph operations through a shared lock object.

Inheritance
object
ScyllaAdjacencyListGraph.SynchronizedScyllaAdjacencyListGraph
Implements
Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public sealed class ScyllaAdjacencyListGraph.SynchronizedScyllaAdjacencyListGraph : IScyllaMutableGraph, IScyllaReadOnlyGraph, IScyllaGraph, IScyllaCollection
Remarks

Obtain an instance via AsSynchronized(object) or the Synchronized(object) builder method. Do not construct directly unless you already hold a reference to the inner graph.

Properties and Capabilities are cached at construction time and returned lock-free. All other properties and methods acquire SyncRoot for their duration.

Compound check-then-act sequences (e.g. ContainsNode followed by TryAddEdge) are still subject to TOCTOU races unless the caller explicitly locks SyncRoot across both operations.

Constructors

SynchronizedScyllaAdjacencyListGraph(ScyllaAdjacencyListGraph, object)

Initializes a new synchronized wrapper around the given ScyllaAdjacencyListGraph.

Declaration
public SynchronizedScyllaAdjacencyListGraph(ScyllaAdjacencyListGraph inner, object syncRoot)
Parameters
Type Name Description
ScyllaAdjacencyListGraph inner

The unsynchronized graph to wrap. Must not be null.
object syncRoot

An optional external lock object. When null, a new private object is created and used as the lock.
Exceptions
Type Condition
ArgumentNullException

Thrown when inner is null.

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()

Removes all items from the collection and resets it to an empty state.

Declaration
public void Clear()
Remarks

Implementations that store reference-type elements should null out internal slots after clearing to avoid retaining object references and preventing garbage collection. After Clear returns, Count must be 0 and IsEmpty must be true.

On synchronized wrappers this operation is protected by the collection's internal lock. On unsynchronized collections, callers are responsible for external coordination.

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

EnsureCapacity(int)

Ensures that the internal node storage can accommodate at least the specified number of nodes without triggering a reallocation.

Declaration
public void EnsureCapacity(int minNodeCapacity)
Parameters
Type Name Description
int minNodeCapacity

The minimum number of nodes the graph storage should be able to hold. Values less than or equal to the current internal capacity are ignored without error.
Remarks

This method is an optional performance hint. Call it before a bulk insertion of a known number of nodes to avoid incremental reallocations. It does not change NodeCount and does not add any nodes.

Edge storage grows dynamically on a per-node basis and is not affected by this call. There is no corresponding bulk edge pre-allocation method.

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

TryAddEdge(int, int, float)

Attempts to add an edge between two existing nodes.

Declaration
public bool TryAddEdge(int fromID, int toID, float weight = 1)
Parameters
Type Name Description
int fromID

The ID of the source node.
int toID

The ID of the target node.
float weight

The weight of the edge. Defaults to 1.0f. For graphs whose Properties do not include Weighted, this parameter is ignored and the stored weight is always 1.0f.
Returns
Type Description
bool

true if the edge was successfully added; false if any of the following conditions hold:

  • Either fromID or toID does not exist in the graph.
  • An edge between the two nodes already exists.
  • fromID equals toID and the graph does not have the AllowsSelfLoops flag.
  • A parallel edge would result and the graph does not have the AllowsParallelEdges flag.
Remarks

For undirected graphs, adding edge (A, B) automatically stores the reverse adjacency (B, A) as well. EdgeCount increases by 1 for each successful call regardless of directionality.

For typed edge graphs, edges added through this untyped overload will carry default(TEdgeData). To associate edge data at creation time, use TryAddEdge(int, int, float, TEdgeData).

See Also

TryAddNode(int, ScyllaGraphNodeFlags)

Attempts to add a new node with the specified ID and flags to the graph.

Declaration
public bool TryAddNode(int nodeID, ScyllaGraphNodeFlags flags = ScyllaGraphNodeFlags.Walkable)
Parameters
Type Name Description
int nodeID

A caller-supplied integer ID that must be unique within this graph. No ordering or contiguity is required; any int value is valid as an ID.
ScyllaGraphNodeFlags flags

Initial ScyllaGraphNodeFlags for the node. Defaults to Walkable if not specified. Flags can be changed later via TrySetNodeFlags(int, ScyllaGraphNodeFlags).
Returns
Type Description
bool

true if the node was successfully added; false if a node with nodeID already exists in the graph.
Remarks

For typed graphs, nodes added through this untyped overload will have default(TNodeData) as their data value. To associate data at creation time, use TryAddNode(int, TNodeData, ScyllaGraphNodeFlags) instead.

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

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

TryRemoveEdge(int, int)

Attempts to remove the edge between two nodes.

Declaration
public bool TryRemoveEdge(int fromID, int toID)
Parameters
Type Name Description
int fromID

The ID of the source node.
int toID

The ID of the target node.
Returns
Type Description
bool

true if the edge was found and removed; false if the edge does not exist or either endpoint is absent from the graph.
Remarks

For undirected graphs, removing edge (A, B) also removes the reverse adjacency (B, A). EdgeCount decreases by 1 for each successful call. For directed graphs, only the directed edge in the specified direction is removed; the reverse edge (if any) is unaffected.

See Also

TryRemoveNode(int)

Attempts to remove a node and all of its incident edges from the graph.

Declaration
public bool TryRemoveNode(int nodeID)
Parameters
Type Name Description
int nodeID

The ID of the node to remove.
Returns
Type Description
bool

true if the node was found and removed; false if no node with nodeID exists in the graph.
Remarks

Removing a node also removes all edges that have it as an endpoint (both outgoing and incoming edges for directed graphs, or all incident edges for undirected graphs). After a successful removal, NodeCount decreases by 1 and EdgeCount decreases by the number of edges removed.

See Also

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

true if the node was found and its flags updated; false if no node with nodeID exists in the graph.
See Also

Implements

Extension Methods