cuda::experimental::graph_builder#

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