cuda::experimental::graph_builder

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

struct graph_builder : public cuda::experimental::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.

Public Functions

inline explicit graph_builder(device_ref __dev)

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

Constructs a new, empty CUDA graph.

The nodes in the graph will execute on the default device 0.

Throws: cuda::std::cuda_error – if cudaGraphCreate fails.

graph_builder(int) = delete: Disallow construction from an int, e.g., 0.

graph_builder(cuda::std::nullptr_t) = delete: Disallow construction from nullptr.

inline explicit constexpr graph_builder(no_init_t, device_ref __dev = device_ref{0}) noexcept

Constructs an uninitialized CUDA graph.

Parameters: __dev – The device on which graph nodes will execute, default to device 0.
Throws: None –

inline constexpr graph_builder(graph_builder &&__other) noexcept

Move constructor for graph_builder.

Note

After the move, the source object is left in the empty state.

Parameters: __other – The graph_builder object to move from.
Throws: None –
Post: __other.get() == nullptr

inline constexpr graph_builder(graph_builder_ref __other)

Copy constructor for graph_builder.

Parameters: __other – The graph_builder object to copy from.
Throws: cuda::std::cuda_error – if cudaGraphClone fails.
Post: get() == __other.get()

inline constexpr ~graph_builder()

Destructor for graph_builder.

Ensures proper cleanup of the CUDA graph object.

Throws: None –

inline constexpr auto operator=(graph_builder &&__other) noexcept -> graph_builder&

Move assignment operator for graph_builder.

Note

After the move, the source object is left in the empty state.

Parameters: __other – The graph_builder object to move from.
Throws: None –
Returns: A reference to the current object.
Post: __other.get() == nullptr

inline constexpr auto operator=(graph_builder_ref __other) -> graph_builder&

Copy assignment operator for graph_builder.

Parameters: __other – The graph_builder object to copy from.
Throws: cuda::std::cuda_error – if cudaGraphClone fails.
Returns: A reference to the current object.
Post: get() == __other.get()

inline constexpr auto release() noexcept -> cudaGraph_t

Releases ownership of the CUDA graph object.

Throws: None –
Returns: The cudaGraph_t handle, leaving this object in a null state.
Post: get() == nullptr

inline constexpr void reset() noexcept

Resets the graph_builder object, destroying the underlying CUDA graph object.

Throws: cuda::std::cuda_error – if cudaGraphDestroy fails.
Post: get() == nullptr

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.

Public Static Functions

static inline constexpr auto from_native_handle(cudaGraph_t __graph, device_ref __dev) noexcept -> graph_builder 

Constructs a graph_builder object from a native CUDA graph handle.

Parameters

__graph – The native CUDA graph handle to construct the graph_builder object from.
__dev – The device on which graph nodes will execute, default to device 0.

Throws

None –

Post

get() == __graph