cuda::experimental::graph_builder_ref

Defined in include/cuda/experimental/__graph/graph_builder_ref.cuh

struct graph_builder_ref

An owning wrapper type for a cudaGraph_t handle.

The graph_builder class provides a high-level interface for creating, managing, and manipulating CUDA graphs. It ensures proper resource management and simplifies the process of working with CUDA graph APIs.

Features:

Supports construction, destruction, and copying of CUDA graphs.
Provides methods for adding nodes and dependencies to the graph.
Allows instantiation of the graph into an executable form.
Ensures proper cleanup of CUDA resources.

Usage:

Create an instance of graph_builder to represent a CUDA graph.
Use the add methods to add nodes and dependencies to the graph.
Instantiate the graph using the instantiate method to obtain an executable graph.
Use the reset method to release resources when the graph is no longer needed.

Thread Safety:

This class is not thread-safe. Concurrent access to the same graph_builer object must be synchronized externally.

Exception Safety:

Methods that interact with CUDA APIs may throw cuda::std::cuda_error if the underlying CUDA operation fails.
Move operations leave the source object in a valid but unspecified state.

Subclassed by cuda::experimental::graph_builder

Public Functions

inline constexpr graph_builder_ref(cudaGraph_t __graph, device_ref __dev) noexcept

Constructs a new, empty CUDA graph.

Parameters: __dev – The device on which graph nodes will execute.
Throws: cuda::std::cuda_error – if cudaGraphCreate fails.

inline explicit constexpr operator bool() const noexcept

Checks if the graph handle is valid.

This operator allows the graph builder to be used in a boolean context to determine if it is valid. A valid graph builder is one where the internal node pointer is not nullptr.

Returns: true if the internal node pointer is not nullptr, otherwise false.

inline constexpr auto operator!() const noexcept -> bool

Checks if the graph is not null.

Returns: true if the internal graph handle is null, otherwise false.

inline constexpr void swap(graph_builder_ref &__other) noexcept

Swaps the contents of this graph_builder with another.

Parameters: __other – The graph_builder object to swap with.
Throws: None –

inline constexpr auto get() const noexcept -> cudaGraph_t

Retrieves the underlying CUDA graph object.

Throws: None –
Returns: The cudaGraph_t handle.

inline constexpr auto get_device() const noexcept -> device_ref

Retrieves the device on which the graph is built.

Returns: The device on which the graph is built.

template<class _Node> inline constexpr auto add(_Node __node) -> graph_node_ref 

Adds a new root node to the graph.

Template Parameters: _Node – The type of the node to add.
Parameters: __node – The descriptor of the node to add to the graph.
Throws: cuda::std::cuda_error – if adding the node fails.
Returns: A graph_node_ref representing the added node. The graph object owns the new node.

template<class _Node, size_t _Np> inline constexpr auto add(_Node __node, cuda::std::array<cudaGraphNode_t, _Np> __deps) -> graph_node_ref 

Adds a new node to the graph with specified dependencies.

This function creates a new node in the graph and establishes dependencies between the newly created node and the provided dependency nodes.

The function first creates a new node in the graph using the provided _Node object.
It initializes an array of “dependant” nodes, where all dependant nodes correspond to the newly created node.
The function then uses the CUDA API cudaGraphAddDependencies to establish the dependencies between the newly created node and the nodes provided in the __deps span.
If the number of dependencies is small, a stack-allocated buffer is used; otherwise, a dynamically allocated array is used to store the dependant nodes.

Template Parameters

_Node – The type of the node to be added.
_Extent – The extent of the span representing the dependencies.

Parameters

__node – The descriptor of the node to be added to the graph.
__deps – An array of cudaGraphNode_t handles representing the dependencies of the new node. Each node in this span will become a dependency of the newly created node.

Throws

cuda::std::cuda_error – If the CUDA API call cudaGraphAddDependencies fails.

Returns

A graph_node_ref object representing the newly created node in the graph. The graph object owns the new node.

template<class _Node, size_t _Extent> inline constexpr auto add(_Node __node, cuda::std::span<cudaGraphNode_t, _Extent> __deps) -> graph_node_ref : This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

inline size_t node_count() const

Retrieves the number of nodes in the graph.

Throws: cuda::std::cuda_error – if cudaGraphGetNodes fails.
Returns: The number of nodes in the graph.

inline auto instantiate() -> graph 

Instantiates the CUDA graph into a graph_exec object.

Throws: cuda::std::cuda_error – if cudaGraphInstantiate fails.
Returns: A graph_exec object representing the instantiated graph.

Friends

inline friend bool operator==(const graph_builder_ref &__lhs, const graph_builder_ref &__rhs) noexcept

Compares two graph_builder objects for equality.

Parameters

__lhs – The left-hand side graph_builder object to compare.
__rhs – The right-hand side graph_builder object to compare.

Returns

true if both graph_builder objects are equal, false otherwise.

inline friend bool operator!=(const graph_builder_ref &__lhs, const graph_builder_ref &__rhs) noexcept

Compares two graph_builder objects for inequality.

Parameters

__lhs – The left-hand side graph_builder object to compare.
__rhs – The right-hand side graph_builder object to compare.

Returns

true if both graph_builder objects are not equal, false otherwise.

inline friend bool operator==(cuda::std::nullptr_t, const graph_builder_ref &__rhs) noexcept

Test whether a graph_builder object is null.

Returns: true if __rhs is null, false otherwise.

inline friend bool operator==(const graph_builder_ref &__lhs, cuda::std::nullptr_t) noexcept

Test whether a graph_builder object is null.

Returns: true if __rhs is null, false otherwise.

inline friend bool operator!=(cuda::std::nullptr_t, const graph_builder_ref &__rhs) noexcept

Test whether a graph_builder object is not null.

Returns: true if __rhs is not null, false otherwise.

inline friend bool operator!=(const graph_builder_ref &__lhs, cuda::std::nullptr_t) noexcept

Test whether a graph_builder object is not null.

Returns: true if __lhs is not null, false otherwise.