cuda::experimental::graph_builder_ref#

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:
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:
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.