Class CudaGraph

Namespace

DotCompute.Backends.CUDA.Execution.Graph

Assembly

DotCompute.Backends.CUDA.dll

Represents a CUDA computational graph that can be compiled, optimized, and executed. Provides high-performance execution through kernel fusion and optimization for RTX 2000 Ada architecture.

public sealed class CudaGraph : IDisposable

Inheritance

object

CudaGraph

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

BufferExtensions.IsSafeToDispose(IDisposable)

BufferExtensions.SafeDispose(IDisposable)

Remarks

CUDA graphs enable efficient execution of repetitive kernel sequences by reducing CPU-GPU synchronization overhead and enabling advanced optimizations like kernel fusion.

Constructors

CudaGraph()

Initializes a new instance of the CudaGraph class.

public CudaGraph()

Remarks

Creates an empty graph with default configuration. The graph must be properly configured and built before it can be instantiated for execution.

CudaGraph(string)

Initializes a new instance of the CudaGraph class with a specified name.

public CudaGraph(string name)

Parameters

name string

The human-readable name for this graph.

Exceptions

ArgumentException

Thrown when name is null or whitespace.

Properties

CreatedAt

Gets or sets the timestamp when this graph was created.

public DateTimeOffset CreatedAt { get; set; }

Property Value

DateTimeOffset

A DateTimeOffset indicating when the graph was instantiated.

Handle

Gets or sets the native CUDA graph handle.

public nint Handle { get; set; }

Property Value

nint

An nint representing the native CUDA graph handle.

Id

Gets or sets the unique identifier for this CUDA graph.

public string Id { get; set; }

Property Value

string

A string that uniquely identifies this graph instance.

Remarks

This property is automatically set to a unique GUID when the graph is created. It should not be modified after creation unless absolutely necessary.

IsBuilt

Gets or sets a value indicating whether the graph has been built and is ready for instantiation.

public bool IsBuilt { get; set; }

Property Value

bool

true if the graph has been successfully built; otherwise, false.

IsCaptured

Gets or sets a value indicating whether this graph was created through stream capture.

public bool IsCaptured { get; set; }

Property Value

bool

true if the graph was captured from a CUDA stream; otherwise, false.

IsEmpty

Gets a value indicating whether the graph is empty (contains no nodes).

public bool IsEmpty { get; }

Property Value

bool

true if the graph contains no nodes; otherwise, false.

IsOptimized

Gets or sets a value indicating whether the graph has been optimized for execution.

public bool IsOptimized { get; set; }

Property Value

bool

true if optimization passes have been applied; otherwise, false.

Name

Gets or sets the human-readable name for this CUDA graph.

public string Name { get; set; }

Property Value

string

A string representing the graph's name for identification and debugging purposes.

Remarks

This property provides a more meaningful identifier than the GUID-based Id property. It is used in logging, debugging, and error messages to help identify specific graphs. The name should be unique within a given context but is not enforced by this class.

NodeCount

Gets the current count of nodes in the graph.

public int NodeCount { get; }

Property Value

int

The number of nodes currently in the graph.

Remarks

This property provides an efficient way to get the node count without enumerating the entire collection. It is thread-safe and reflects the current state.

Nodes

Gets the thread-safe collection of graph nodes that comprise this CUDA graph.

public IList<CudaGraphNode> Nodes { get; }

Property Value

IList<CudaGraphNode>

A thread-safe list of CudaGraphNode instances representing the graph structure.

Remarks

This property provides a thread-safe view of all nodes in the graph. The underlying collection uses a concurrent data structure to ensure safe access from multiple threads. Use the AddNode(CudaGraphNode) and RemoveNode(string) methods to modify the collection safely.

Operations

Gets or sets the list of kernel operations that comprise this graph.

public IList<CudaKernelOperation> Operations { get; init; }

Property Value

IList<CudaKernelOperation>

A list of CudaKernelOperation instances representing the computational sequence.

Remarks

This property maintains backward compatibility with existing code that expects kernel operations. New code should prefer using the Nodes property for graph structure manipulation.

Options

Gets or sets the optimization options for this graph.

public CudaGraphOptimizationOptions Options { get; set; }

Property Value

CudaGraphOptimizationOptions

A CudaGraphOptimizationOptions instance specifying optimization behavior.

Methods

AddNode(CudaGraphNode)

Adds a node to the graph in a thread-safe manner.

public void AddNode(CudaGraphNode node)

Parameters

node CudaGraphNode

The node to add to the graph.

Remarks

This method ensures thread-safe addition of nodes to the graph. It validates that the node ID is unique within the graph before adding.

Exceptions

ArgumentNullException

Thrown when node is null.

ObjectDisposedException

Thrown when the graph has been disposed.

InvalidOperationException

Thrown when a node with the same ID already exists.

Clear()

Clears all nodes from the graph.

public void Clear()

Remarks

This method removes all nodes from the graph in a thread-safe manner. It also cleans up any resources associated with the nodes.

Exceptions

ObjectDisposedException

Thrown when the graph has been disposed.

Dispose()

Releases the native CUDA graph resources.

public void Dispose()

Remarks

This method is called automatically when the graph is disposed. It safely destroys the native CUDA graph handle and prevents further use of this graph instance. The disposal is thread-safe and will clean up all nodes and their associated resources.

~CudaGraph()

Finalizer for the CudaGraph class.

protected ~CudaGraph()

Remarks

This finalizer ensures that native resources are released even if Dispose is not called. However, it is recommended to explicitly call Dispose or use a using statement.

FindNode(string)

Finds a node in the graph by its ID.

public CudaGraphNode? FindNode(string nodeId)

Parameters

nodeId string

The ID of the node to find.

Returns

CudaGraphNode

The node with the specified ID, or null if not found.

Exceptions

ArgumentException

Thrown when nodeId is null or whitespace.

ObjectDisposedException

Thrown when the graph has been disposed.

RemoveNode(string)

Removes a node from the graph by its ID.

public bool RemoveNode(string nodeId)

Parameters

nodeId string

The ID of the node to remove.

Returns

bool

true if the node was found and removed; otherwise, false.

Remarks

This method removes the node and also cleans up any dependency relationships that reference the removed node.

Exceptions

ArgumentException

Thrown when nodeId is null or whitespace.

ObjectDisposedException

Thrown when the graph has been disposed.