cuda.core.experimental.GraphBuilder¶

class cuda.core.experimental.GraphBuilder¶

Represents a graph under construction.

A graph groups a set of CUDA kernels and other CUDA operations together and executes them with a specified dependency tree. It speeds up the workflow by combining the driver activities associated with CUDA kernel launches and CUDA API calls.

Directly creating a GraphBuilder is not supported due to ambiguity. New graph builders should instead be created through a Device, or a stream object.

Methods

__init__()¶

add_child(child_graph: GraphBuilder)¶

Adds the child GraphBuilder builder into self.

The child graph builder will be added as a child node to the parent graph builder.

Parameters:: child_graph (GraphBuilder) – The child graph builder. Must have finished building.

begin_building(mode='relaxed') → GraphBuilder¶

Begins the building process.

Build mode for controlling interaction with other API calls must be one of the following:

global : Prohibit potentially unsafe operations across all streams in the process.
thread_local : Prohibit potentially unsafe operations in streams created by the current thread.
relaxed : The local thread is not prohibited from potentially unsafe operations.

Parameters:: mode (str, optional) – Build mode to control the interaction with other API calls that are porentially unsafe. Default set to use relaxed.

close()¶

Destroy the graph builder.

Closes the associated stream if we own it. Borrowed stream object will instead have their references released.

complete(options: GraphCompleteOptions | None = None) → Graph¶

Completes the graph builder and returns the built Graph object.

Parameters:: options (GraphCompleteOptions, optional) – Customizable dataclass for the graph builder completion options.
Returns:: graph – The newly built graph.
Return type:: Graph

create_conditional_handle(default_value=None) → CUgraphConditionalHandle¶

Creates a conditional handle for the graph builder.

Parameters:: default_value (int, optional) – The default value to assign to the conditional handle.
Returns:: handle – The newly created conditional handle.
Return type:: driver.CUgraphConditionalHandle

debug_dot_print(path, options: GraphDebugPrintOptions | None = None)¶

Generates a DOT debug file for the graph builder.

Parameters:

path (str) – File path to use for writting debug DOT output
options (GraphDebugPrintOptions, optional) – Customizable dataclass for the debug print options.

end_building() → GraphBuilder¶: Ends the building process.

if_cond(handle: CUgraphConditionalHandle) → GraphBuilder¶

Adds an if condition branch and returns a new graph builder for it.

The resulting if graph will only execute the branch if the conditional handle evaluates to true at runtime.

The new builder inherits work dependencies from the original builder.

Parameters:: handle (driver.CUgraphConditionalHandle) – The handle to use for the if conditional.
Returns:: graph_builder – The newly created conditional graph builder.
Return type:: GraphBuilder

if_else(handle: CUgraphConditionalHandle) → tuple[GraphBuilder, GraphBuilder]¶

Adds an if-else condition branch and returns new graph builders for both branches.

The resulting if graph will execute the branch if the conditional handle evaluates to true at runtime, otherwise the else branch will execute.

The new builders inherit work dependencies from the original builder.

Parameters:: handle (driver.CUgraphConditionalHandle) – The handle to use for the if-else conditional.
Returns:: graph_builders – A tuple of two new graph builders, one for the if branch and one for the else branch.
Return type:: tuple[GraphBuilder, GraphBuilder]

static join(*graph_builders) → GraphBuilder¶

Joins multiple graph builders into a single graph builder.

The returned builder inherits work dependencies from the provided builders.

Parameters:: *graph_builders (GraphBuilder) – The graph builders to join.
Returns:: graph_builder – The newly joined graph builder.
Return type:: GraphBuilder

split(count: int) → tuple[GraphBuilder, ...]¶

Splits the original graph builder into multiple graph builders.

The new builders inherit work dependencies from the original builder. The original builder is reused for the split and is returned first in the tuple.

Parameters:: count (int) – The number of graph builders to split the graph builder into.
Returns:: graph_builders – A tuple of split graph builders. The first graph builder in the tuple is always the original graph builder.
Return type:: tuple[GraphBuilder, …]

switch(handle: CUgraphConditionalHandle, count: int) → tuple[GraphBuilder, ...]¶

Adds a switch condition branch and returns new graph builders for all cases.

The resulting switch graph will execute the branch that matches the case index of the conditional handle at runtime. If no match is found, no branch will be executed.

The new builders inherit work dependencies from the original builder.

Parameters:

handle (driver.CUgraphConditionalHandle) – The handle to use for the switch conditional.
count (int) – The number of cases to add to the switch conditional.

Returns:

graph_builders – A tuple of new graph builders, one for each branch.

Return type:

tuple[GraphBuilder, …]

while_loop(handle: CUgraphConditionalHandle) → GraphBuilder¶

Adds a while loop and returns a new graph builder for it.

The resulting while loop graph will execute the branch repeatedly at runtime until the conditional handle evaluates to false.

The new builder inherits work dependencies from the original builder.

Parameters:: handle (driver.CUgraphConditionalHandle) – The handle to use for the while loop.
Returns:: graph_builder – The newly created while loop graph builder.
Return type:: GraphBuilder

Attributes

property is_building: bool¶: Returns True if the graph builder is currently building.

property is_join_required: bool¶: Returns True if this graph builder must be joined before building is ended.

property stream: Stream¶: Returns the stream associated with the graph builder.