cuda::experimental::graph_builder

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

struct graph_builder

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

Constructs a new, empty CUDA graph.

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 constexpr graph_builder(no_init_t) noexcept

Constructs an uninitialized CUDA graph.

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(const graph_builder &__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=(const graph_builder &__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 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 &__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 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

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

Throws

None –

Post

get() == __graph

Friends

inline friend bool operator==(const graph_builder &__lhs, const graph_builder &__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 &__lhs, const graph_builder &__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 &__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 &__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 &__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 &__lhs, cuda::std::nullptr_t) noexcept

Test whether a graph_builder object is not null.

Returns

true if __lhs is not null, false otherwise.