cuda.core.graph.ChildGraphNode#

class cuda.core.graph.ChildGraphNode#

A child graph node.

Properties#

child_graphGraphDefinition

The embedded graph definition (non-owning wrapper).

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

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

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.

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

child_graph#

The embedded graph definition (non-owning wrapper).

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

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