cuda.core.graph.GraphBuilder#

class cuda.core.graph.GraphBuilder#

A graph under construction by stream capture.

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__(self)#
begin_building(self, 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.

callback(self, fn, *, user_data=None)#

Add a host callback to the graph during stream capture.

The callback runs on the host CPU when the graph reaches this point in execution. Two modes are supported:

  • Python callable: Pass any callable. The GIL is acquired automatically. The callable must take no arguments; use closures or functools.partial to bind state.

  • ctypes function pointer: Pass a ctypes.CFUNCTYPE instance. The function receives a single void* argument (the user_data). The caller must keep the ctypes wrapper alive for the lifetime of the graph.

Warning

Callbacks must not call CUDA API functions. Doing so may deadlock or corrupt driver state.

Parameters:

  • fn (callable or ctypes function pointer) – The callback function.

  • user_data (int or bytes-like, optional) – Only for ctypes function pointers. If int, passed as a raw pointer (caller manages lifetime). If bytes-like, the data is copied and its lifetime is tied to the graph.

close(self)#

Destroy the graph builder.

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

complete(
self,
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_condition(
self,
default_value=None,
) → GraphCondition#

Create a condition variable for use with conditional nodes.

The returned GraphCondition object is passed to conditional-node builder methods (if_then(), if_else(), while_loop(), switch()). Its value is controlled at runtime by device code via cudaGraphSetConditional.

Parameters:

default_value (int, optional) – The default value to assign to the condition. If None, no default is assigned.

Returns:

A condition variable for controlling conditional execution.

Return type:

GraphCondition

debug_dot_print(
self,
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.

embed(self, child: GraphBuilder)#

Embed a previously-built GraphBuilder as a child node.

Parameters:

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

end_building(self) → GraphBuilder#

Ends the building process.

if_else(
self,
GraphCondition condition: GraphCondition,
) → 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 condition evaluates to true at runtime, otherwise the else branch will execute.

The new builders inherit work dependencies from the original builder.

Parameters:

condition (GraphCondition) – The condition variable from create_condition() controlling which branch executes.

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]

if_then(
self,
GraphCondition condition: GraphCondition,
) → 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 condition evaluates to true at runtime.

The new builder inherits work dependencies from the original builder.

Parameters:

condition (GraphCondition) – The condition variable from create_condition() controlling whether the branch executes.

Returns:

graph_builder – The newly created conditional graph builder.

Return type:

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(self, int 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(
self,
GraphCondition condition: GraphCondition,
int 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 whose case index matches the value of the condition at runtime. If no match is found, no branch will be executed.

The new builders inherit work dependencies from the original builder.

Parameters:

  • condition (GraphCondition) – The condition variable from create_condition() selecting which case executes.

  • 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(
self,
GraphCondition condition: GraphCondition,
) → 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 condition evaluates to false.

The new builder inherits work dependencies from the original builder.

Parameters:

condition (GraphCondition) – The condition variable from create_condition() controlling loop continuation.

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.