cuda::experimental::path_builder#

struct path_builder#

A builder for a path in a CUDA graph.

This class allows for the creation of a path in a CUDA graph, which is a sequence of nodes that are executed in order. The path builder can be used to add nodes to the path, and to set the dependencies between nodes. Thanks to the sequential nature of the path builder, it is possible to write single code path that uses either a stream or a path builder to result in either eager stream execution or construction of a lazy graph.

Public Functions

inline explicit path_builder(graph_builder_ref __builder)#

Construct a path builder that will insert nodes into a graph builder.

Parameters:

__builder – The graph builder to create the path builder for.

inline path_builder(device_ref __dev, cudaGraph_t __graph)#

Construct a path builder that will insert nodes into a graph.

Parameters:

  • __dev – The device on which nodes inserted into the graph will execute.

  • __graph – The graph to create the path builder for.

template<typename _Fn>
inline void legacy_stream_capture(
stream_ref __stream,
_Fn &&__capture_fn
)#

Capture the nodes into the path builder from a legacy stream capture.

Parameters:

  • __stream – The stream to use for the capture.

  • __capture_fn – A function that will be called with the stream to capture the nodes to.

inline auto get_dependencies(
) const noexcept -> ::cuda::std::span<const cudaGraphNode_t>#

Get the dependencies of the path builder.

Returns:

A span of the dependencies of the path builder.

inline void wait(const path_builder &__other)#

Add the dependencies of another path builder to this path builder.

Parameters:

__other – The path builder to add dependencies from. Named wait to match the stream/stream_ref wait function

inline graph_node_ref wait(::cuda::event_ref __ev)#

Adds an event-wait node and makes it the next dependency.

The new node waits for __ev to be recorded before any successor of this node executes. This mirrors stream_ref::wait(event_ref).

Parameters:

__ev – Event that graph execution should wait on.

Throws:

cuda::std::cuda_error – if cudaGraphAddEventWaitNode fails.

Returns:

A graph_node_ref for the newly added event-wait node.

inline graph_node_ref record_event(::cuda::event_ref __ev)#

Adds an event-record node and makes it the next dependency.

The new node records __ev when it executes, signalling any downstream waiters. This mirrors stream_ref::record_event(event_flags) but takes an existing event because graph construction happens before execution.

Parameters:

__ev – Event to record.

Throws:

cuda::std::cuda_error – if cudaGraphAddEventRecordNode fails.

Returns:

A graph_node_ref for the newly added event-record node.

template<typename ...Nodes, ::cuda::std::enable_if_t<__all_dependencies<Nodes...>, int> = 0>
inline void depends_on(
Nodes&&... __nodes
)#

Add the dependencies of another path builder or single nodes to this path builder.

Parameters:

__nodes – The nodes or path builders to add to the path builder as dependencies.

inline constexpr auto get_graph() const noexcept -> graph_builder_ref#

Get the graph that the path builder is building.

Returns:

The graph that the path builder is building.

inline constexpr auto get_native_graph_handle(
) const noexcept -> cudaGraph_t#
inline constexpr auto get_device() const noexcept -> device_ref#

Retrieves the device on which graph nodes inserted by the path builder will execute.

Returns:

The device on which graph nodes inserted by the path builder will execute.