cuda.core.graph.IfNode#

class cuda.core.graph.IfNode#

An if-conditional node.

Methods

__init__()#
allocate(
self,
size_t size,
*,
device: Device | int | None = None,
memory_type: GraphMemoryType = GraphMemoryType.DEVICE,
list peer_access: list[Device | int] | None = None,
) → AllocNode#

Add a memory allocation node depending on this node.

Parameters:

  • size (int) – Number of bytes to allocate.

  • device (int or Device, optional) – The device on which to allocate memory. If None (default), uses the current CUDA context’s device.

  • memory_type (GraphMemoryType or str, optional) –

    Type of memory to allocate. One of:

    • GraphMemoryType.DEVICE (default): Pinned device memory, optimal for GPU kernels.

    • GraphMemoryType.HOST: Pinned host memory, accessible from both host and device. Useful for graphs containing host callback nodes. Note: may not be supported on all systems/drivers.

    • GraphMemoryType.MANAGED: Managed/unified memory that automatically migrates between host and device. Useful for mixed host/device access patterns.

  • peer_access (list of int or Device, optional) – List of devices that should have read-write access to the allocated memory. If None (default), only the allocating device has access.

Returns:

A new AllocNode representing the allocation. Access the allocated device pointer via the dptr property.

Return type:

AllocNode

Notes

IPC (inter-process communication) is not supported for graph memory allocation nodes per CUDA documentation.

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

Add a host callback node depending on this node.

The callback runs on the host CPU when the graph reaches this node. 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: The function receives a single void* argument (the user_data), and the caller must keep the ctypes wrapper alive for the lifetime of the graph. Its declared prototype must match the driver’s CUhostFn (void (*)(void*)): ctypes.CFUNCTYPE(None, ctypes.c_void_p), or ctypes.WINFUNCTYPE(None, ctypes.c_void_p) on Windows.

Warning

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

Use caution when a Python callback retains an object that owns a graph. Any reference cycle involving the callback and a graph that retains it cannot be broken by Python’s cyclic garbage collector. Use a weak reference to break such cycles.

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.

Returns:

A new HostCallbackNode representing the callback.

Return type:

HostCallbackNode

Raises:

  • TypeError – If fn is a ctypes function pointer whose declared prototype does not match CUhostFn.

  • ValueError – If user_data is given for a Python callable.

deallocate(self, int dptr: int) → FreeNode#

Add a memory free node depending on this node.

Parameters:

dptr (int) – Device pointer to free (typically from AllocNode.dptr).

Returns:

A new FreeNode representing the free operation.

Return type:

FreeNode

destroy(self) → None#

Destroy this node and remove all its edges from the parent graph.

After this call, is_valid returns False and the node cannot be re-added to any graph. Safe to call on an already-destroyed node (no-op).

embed(
self,
GraphDefinition child: GraphDefinition,
) → ChildGraphNode#

Add a child graph node depending on this node.

Embeds a clone of the given graph definition as a sub-graph node. The child graph must not contain allocation, free, or conditional nodes.

Parameters:

child (GraphDefinition) – The graph definition to embed (will be cloned).

Returns:

A new ChildGraphNode representing the embedded sub-graph.

Return type:

ChildGraphNode

if_else(
self,
GraphCondition condition: GraphCondition,
) → IfElseNode#

Add an if-else conditional node depending on this node.

Two body graphs: the first executes when the condition is non-zero, the second when it is zero.

Parameters:

condition (GraphCondition) – GraphCondition from GraphDefinition.create_condition().

Returns:

A new IfElseNode with branches accessible via .then and .else_.

Return type:

IfElseNode

if_then(
self,
GraphCondition condition: GraphCondition,
) → IfNode#

Add an if-conditional node depending on this node.

The body graph executes only when the condition evaluates to a non-zero value at runtime.

Parameters:

condition (GraphCondition) – GraphCondition from GraphDefinition.create_condition().

Returns:

A new IfNode with one branch accessible via .then.

Return type:

IfNode

join(self, *nodes: GraphNode) → EmptyNode#

Create an empty node that depends on this node and all given nodes.

This is used to synchronize multiple branches of execution.

Parameters:

*nodes (GraphNode) – Additional nodes to depend on.

Returns:

A new EmptyNode that depends on all input nodes.

Return type:

EmptyNode

launch(
self,
LaunchConfig config: LaunchConfig,
Kernel kernel: Kernel,
*args,
) → KernelNode#

Add a kernel launch node depending on this node.

Clustered and cooperative launch configurations are not currently supported for graph kernel nodes.

Warning

Use caution when a retained kernel argument directly or indirectly owns a graph. Any reference cycle involving the argument and a graph that retains it cannot be broken by Python’s cyclic garbage collector. Use a weak reference to break such cycles.

Parameters:

  • config (LaunchConfig) – Launch configuration (grid, block, shared memory, etc.)

  • kernel (Kernel) – The kernel to launch.

  • *args – Kernel arguments.

Returns:

A new KernelNode representing the kernel launch.

Return type:

KernelNode

memcpy(
self,
dst: Buffer | int,
src: Buffer | int,
size_t size,
*,
dst_owner=None,
src_owner=None,
) → MemcpyNode#

Add a memcpy node depending on this node.

Copies size bytes from src to dst. Memory types are auto-detected via the driver, so both device and pinned host pointers are supported.

Warning

Use caution when a retained operand owner directly or indirectly owns a graph. Any reference cycle involving the owner and a graph that retains it cannot be broken by Python’s cyclic garbage collector. Use a weak reference to break such cycles.

Parameters:

  • dst (Buffer or int) – Destination (device or pinned host). When a Buffer is given, the underlying allocation is retained for the graph’s lifetime. A raw pointer (int) is used as-is; the caller must keep the underlying memory alive, or supply dst_owner to have the graph retain it.

  • src (Buffer or int) – Source (device or pinned host). Same retention rules as dst; use src_owner for a raw pointer.

  • size (int) – Number of bytes to copy.

  • dst_owner (object, optional) – Object retained for the graph’s lifetime when dst is a raw pointer. A Buffer owner retains its underlying allocation. Must not be passed when dst is a Buffer.

  • src_owner (object, optional) – Object retained for the graph’s lifetime when src is a raw pointer. A Buffer owner retains its underlying allocation. Must not be passed when src is a Buffer.

Returns:

A new MemcpyNode representing the copy operation.

Return type:

MemcpyNode

Raises:

ValueError – If dst_owner or src_owner is given together with a Buffer dst or src respectively.

memset(
self,
dst: Buffer | int,
value,
size_t width,
size_t height=1,
size_t pitch=0,
*,
dst_owner=None,
) → MemsetNode#

Add a memset node depending on this node.

Warning

Use caution when a retained operand owner directly or indirectly owns a graph. Any reference cycle involving the owner and a graph that retains it cannot be broken by Python’s cyclic garbage collector. Use a weak reference to break such cycles.

Parameters:

  • dst (Buffer or int) – Destination. When dst is a Buffer, the underlying allocation is retained for the graph’s lifetime. A raw pointer (int) is used as-is; the caller must keep the underlying memory alive, or supply dst_owner to have the graph retain it.

  • value (int or buffer-protocol object) – Fill value. int for 1-byte fill (range [0, 256)), or buffer-protocol object of 1, 2, or 4 bytes.

  • width (int) – Width of the row in elements.

  • height (int, optional) – Number of rows (default 1).

  • pitch (int, optional) – Pitch of destination in bytes (default 0, unused if height is 1).

  • dst_owner (object, optional) – Object retained for the graph’s lifetime when dst is a raw pointer. A Buffer owner retains its underlying allocation, not the wrapper. Must not be passed when dst is a Buffer.

Returns:

A new MemsetNode representing the memset operation.

Return type:

MemsetNode

Raises:

ValueError – If dst_owner is given together with a Buffer dst.

record(self, Event event: Event) → EventRecordNode#

Add an event record node depending on this node.

Parameters:

event (Event) – The event to record.

Returns:

A new EventRecordNode representing the event record operation.

Return type:

EventRecordNode

switch(
self,
GraphCondition condition: GraphCondition,
unsigned int count,
) → SwitchNode#

Add a switch conditional node depending on this node.

The condition value selects which branch to execute. If the value is out of range, no branch executes.

Parameters:
Returns:

A new SwitchNode with branches accessible via .branches.

Return type:

SwitchNode

wait(self, Event event: Event) → EventWaitNode#

Add an event wait node depending on this node.

Parameters:

event (Event) – The event to wait for.

Returns:

A new EventWaitNode representing the event wait operation.

Return type:

EventWaitNode

while_loop(
self,
GraphCondition condition: GraphCondition,
) → WhileNode#

Add a while-loop conditional node depending on this node.

The body graph executes repeatedly while the condition evaluates to a non-zero value.

Parameters:

condition (GraphCondition) – GraphCondition from GraphDefinition.create_condition().

Returns:

A new WhileNode with body accessible via .body.

Return type:

WhileNode

Attributes

branches#

tuple[GraphDefinition, …]

The body graphs for each branch as a tuple of GraphDefinition.

Returns an empty tuple when reconstructed from the driver pre-CUDA 13.2.

Type:

ConditionalNode.branches

cond_type#

GraphConditionalType | None

The conditional type: GraphConditionalType.IF, .WHILE, or .SWITCH

Returns None when reconstructed from the driver pre-CUDA 13.2, as the conditional type cannot be determined.

Type:

ConditionalNode.cond_type

condition#

GraphCondition | None

The condition variable controlling execution.

Type:

ConditionalNode.condition

graph#

GraphDefinition

Return the GraphDefinition this node belongs to.

Type:

GraphNode.graph

handle#

driver.CUgraphNode

Return the underlying driver CUgraphNode handle.

Returns None for the entry node.

Type:

GraphNode.handle

is_valid#

bool

Whether this node is valid (not destroyed).

Returns False after destroy() has been called.

Type:

GraphNode.is_valid

pred#

AdjacencySetProxy

A mutable set-like view of this node’s predecessors.

Type:

GraphNode.pred

succ#

AdjacencySetProxy

A mutable set-like view of this node’s successors.

Type:

GraphNode.succ

then#

The ‘then’ branch graph.

type#

driver.CUgraphNodeType | None

Return the CUDA graph node type.

Returns:

The node type enum value, or None for the entry node.

Return type:

CUgraphNodeType or None

Type:

GraphNode.type