# This file was generated by stubgen-pyx v0.2.6 from cuda_core/cuda/core/graph/_subclasses.pyx

"""GraphNode subclasses — EmptyNode through SwitchNode."""
from __future__ import annotations

from cuda.core._event import Event
from cuda.core._launch_config import LaunchConfig
from cuda.core._memory._buffer import Buffer
from cuda.core._module import Kernel
from cuda.core.graph._graph_definition import GraphCondition, GraphDefinition
from cuda.core.graph._graph_node import GraphNode
from cuda.core.typing import GraphConditionalType


class EmptyNode(GraphNode):
    """An empty (synchronization) node."""

    def __repr__(self) -> str:
        ...

class KernelNode(GraphNode):
    """A kernel launch node.

    Properties
    ----------
    grid : tuple of int
        Grid dimensions (gridDimX, gridDimY, gridDimZ).
    block : tuple of int
        Block dimensions (blockDimX, blockDimY, blockDimZ).
    shmem_size : int
        Dynamic shared memory size in bytes.
    kernel : Kernel
        The kernel object for this launch node.
    config : LaunchConfig
        A LaunchConfig reconstructed from this node's parameters.
    """

    def __repr__(self) -> str:
        ...

    def update(self, *, config: LaunchConfig | None=None, kernel: Kernel | None=None, args=None) -> None:
        """Replace selected kernel launch parameters.

        Omitted parameters preserve their current values. Changing ``kernel``
        requires ``args``, including ``args=()`` for a no-argument kernel.
        Clustered and cooperative kernel nodes are not supported.

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

    @property
    def grid(self) -> tuple[int, int, int]:
        """Grid dimensions as a 3-tuple (gridDimX, gridDimY, gridDimZ)."""

    @property
    def block(self) -> tuple[int, int, int]:
        """Block dimensions as a 3-tuple (blockDimX, blockDimY, blockDimZ)."""

    @property
    def shmem_size(self) -> int:
        """Dynamic shared memory size in bytes."""

    @property
    def kernel(self) -> Kernel:
        """The Kernel object for this launch node."""

    @property
    def config(self) -> LaunchConfig:
        """A LaunchConfig reconstructed from this node's grid, block, and shmem_size.

        Note: cluster dimensions and is_cooperative are not preserved
        by the CUDA driver's kernel node params, so they are not included.
        """

class AllocNode(GraphNode):
    """A memory allocation node.

    Properties
    ----------
    dptr : int
        The device pointer for the allocation.
    bytesize : int
        The number of bytes allocated.
    device_id : int
        The device on which the allocation was made.
    memory_type : GraphMemoryType | str
        The type of memory allocated.
    peer_access : tuple of int
        Device IDs that have read-write access to this allocation.
    """

    def __repr__(self) -> str:
        ...

    @property
    def dptr(self) -> int:
        """The device pointer for the allocation."""

    @property
    def bytesize(self) -> int:
        """The number of bytes allocated."""

    @property
    def device_id(self) -> int:
        """The device on which the allocation was made."""

    @property
    def memory_type(self) -> str:
        """The type of memory: ``"device"``, ``"host"``, or ``"managed"``."""

    @property
    def peer_access(self) -> tuple[int, ...]:
        """Device IDs with read-write access to this allocation."""

class FreeNode(GraphNode):
    """A memory deallocation node.

    Properties
    ----------
    dptr : int
        The device pointer being freed.
    """

    def __repr__(self) -> str:
        ...

    @property
    def dptr(self) -> int:
        """The device pointer being freed."""

class MemsetNode(GraphNode):
    """A memset node.

    Properties
    ----------
    dptr : int
        The destination device pointer.
    value : int
        The fill value.
    element_size : int
        Element size in bytes (1, 2, or 4).
    width : int
        Width of the row in elements.
    height : int
        Number of rows.
    pitch : int
        Pitch in bytes (unused if height is 1).
    """

    def __repr__(self) -> str:
        ...

    def update(self, *, dst: Buffer | int | None=None, value=None, width: int | None=None, height: int | None=None, pitch: int | None=None, dst_owner=None) -> None:
        """Replace selected memset parameters.

        Omitted parameters preserve their current values. ``dst_owner`` may
        only accompany a raw-address ``dst``.

        With CUDA 12.2 through 13.1, the node's intended CUDA context must be
        current when this method is called. CUDA driver and ``cuda.bindings``
        versions 13.2 and newer preserve the recorded context automatically.

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

    @property
    def dptr(self) -> int:
        """The destination device pointer."""

    @property
    def value(self) -> int:
        """The fill value."""

    @property
    def element_size(self) -> int:
        """Element size in bytes (1, 2, or 4)."""

    @property
    def width(self) -> int:
        """Width of the row in elements."""

    @property
    def height(self) -> int:
        """Number of rows."""

    @property
    def pitch(self) -> int:
        """Pitch in bytes (unused if height is 1)."""

class MemcpyNode(GraphNode):
    """A memcpy node.

    Properties
    ----------
    dst : int
        The destination pointer.
    src : int
        The source pointer.
    size : int
        The number of bytes copied.
    """

    def __repr__(self) -> str:
        ...

    def update(self, *, dst: Buffer | int | None=None, src: Buffer | int | None=None, size: int | None=None, dst_owner=None, src_owner=None) -> None:
        """Replace selected memcpy parameters.

        Omitted parameters preserve their current values. ``dst_owner`` and
        ``src_owner`` may only accompany their corresponding raw addresses.
        Multidimensional, pitched, offset, and array-backed memcpy nodes are
        not supported.

        With CUDA 12.2 through 13.1, the node's intended CUDA context must be
        current when this method is called. CUDA driver and ``cuda.bindings``
        versions 13.2 and newer preserve the recorded context automatically.

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

    @property
    def dst(self) -> int:
        """The destination pointer."""

    @property
    def src(self) -> int:
        """The source pointer."""

    @property
    def size(self) -> int:
        """The number of bytes copied."""

class ChildGraphNode(GraphNode):
    """A child graph node.

    Properties
    ----------
    child_graph : GraphDefinition
        The embedded graph definition (non-owning wrapper).
    """

    def __repr__(self) -> str:
        ...

    def update(self, child: GraphDefinition) -> None:
        """Replace the embedded graph with a clone of ``child``.

        ``child`` must belong to an independent graph hierarchy.
        """

    @property
    def child_graph(self) -> GraphDefinition:
        """The embedded graph definition (non-owning wrapper)."""

class EventRecordNode(GraphNode):
    """An event record node.

    Properties
    ----------
    event : Event
        The event being recorded.
    """

    def __repr__(self) -> str:
        ...

    def update(self, event: Event) -> None:
        """Replace the event recorded by this node."""

    @property
    def event(self) -> Event:
        """The event being recorded."""

class EventWaitNode(GraphNode):
    """An event wait node.

    Properties
    ----------
    event : Event
        The event being waited on.
    """

    def __repr__(self) -> str:
        ...

    def update(self, event: Event) -> None:
        """Replace the event waited on by this node."""

    @property
    def event(self) -> Event:
        """The event being waited on."""

class HostCallbackNode(GraphNode):
    """A host callback node.

    Properties
    ----------
    callback : callable or None
        The Python callable (None for ctypes function pointer callbacks).
    """

    def __repr__(self) -> str:
        ...

    def update(self, fn, *, user_data=None) -> None:
        """Replace the callback and user-data binding for this node.

        ``fn`` accepts the same forms as :meth:`~graph.GraphNode.callback`: a
        Python callable, or a ctypes function pointer whose declared prototype
        matches ``CUhostFn`` (``void (*)(void*)``). A mismatched ctypes
        prototype raises ``TypeError``.

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

    @property
    def callback(self):
        """The Python callable, or None for ctypes function pointer callbacks."""

class ConditionalNode(GraphNode):
    """Base class for conditional nodes.

    When created via builder methods (if_then, if_else, while_loop, switch),
    a specific subclass (IfNode, IfElseNode, WhileNode, SwitchNode) is
    returned. When reconstructed from the driver on CUDA 13.2+, the
    correct subclass is determined via cuGraphNodeGetParams. On older
    drivers, this base class is used as a fallback.

    Properties
    ----------
    condition : GraphCondition or None
        The condition variable controlling execution (None pre-13.2).
    cond_type : str or None
        The conditional type ("if", "while", or "switch"; None pre-13.2).
    branches : tuple of GraphDefinition
        The body graphs for each branch (empty pre-13.2).
    """

    def __repr__(self) -> str:
        ...

    @property
    def condition(self) -> GraphCondition | None:
        """The condition variable controlling execution."""

    @property
    def cond_type(self) -> 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.
        """

    @property
    def branches(self) -> 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.
        """

class IfNode(ConditionalNode):
    """An if-conditional node."""

    def __repr__(self) -> str:
        ...

    @property
    def then(self) -> GraphDefinition:
        """The 'then' branch graph."""

class IfElseNode(ConditionalNode):
    """An if-else conditional node."""

    def __repr__(self) -> str:
        ...

    @property
    def then(self) -> GraphDefinition:
        """The ``then`` branch graph (executed when condition is non-zero)."""

    @property
    def else_(self) -> GraphDefinition:
        """The ``else`` branch graph (executed when condition is zero)."""

class WhileNode(ConditionalNode):
    """A while-loop conditional node."""

    def __repr__(self) -> str:
        ...

    @property
    def body(self) -> GraphDefinition:
        """The loop body graph."""

class SwitchNode(ConditionalNode):
    """A switch conditional node."""

    def __repr__(self) -> str:
        ...

class ExecutableGraphNode:
    """A lightweight view pairing an executable graph with a source node.

    Create executable-node views with ``graph[node]``. CUDA validates that the
    node identifies a node in the executable graph when an operation is
    performed.
    """

    def __init__(self):
        ...

    def __repr__(self) -> str:
        ...

class ExecutableKernelNode(ExecutableGraphNode):
    """An executable kernel-node view."""

    def update(self, *, config: LaunchConfig, kernel: Kernel, args) -> None:
        """Replace all kernel launch parameters for future launches.

        ``args`` must contain the complete argument sequence; use ``args=()``
        for a no-argument kernel. Clustered and cooperative launch
        configurations are not supported.
        """

    @property
    def is_enabled(self) -> bool:
        """Whether this node is enabled in the executable graph."""

    def enable(self) -> None:
        """Enable this node in the executable graph."""

    def disable(self) -> None:
        """Disable this node in the executable graph."""

class ExecutableMemsetNode(ExecutableGraphNode):
    """An executable memset-node view."""

    def update(self, *, dst: Buffer | int, value, width: int, height: int=1, pitch: int=0) -> None:
        """Replace all memset parameters for future launches."""

    @property
    def is_enabled(self) -> bool:
        """Whether this node is enabled in the executable graph."""

    def enable(self) -> None:
        """Enable this node in the executable graph."""

    def disable(self) -> None:
        """Disable this node in the executable graph."""

class ExecutableMemcpyNode(ExecutableGraphNode):
    """An executable memcpy-node view."""

    def update(self, *, dst: Buffer | int, src: Buffer | int, size: int) -> None:
        """Replace all one-dimensional memcpy parameters for future launches."""

    @property
    def is_enabled(self) -> bool:
        """Whether this node is enabled in the executable graph."""

    def enable(self) -> None:
        """Enable this node in the executable graph."""

    def disable(self) -> None:
        """Disable this node in the executable graph."""

class ExecutableChildGraphNode(ExecutableGraphNode):
    """An executable child-graph-node view."""

    def update(self, child: GraphDefinition) -> None:
        """Replace the embedded graph parameters for future launches."""

class ExecutableEventRecordNode(ExecutableGraphNode):
    """An executable event-record-node view."""

    def update(self, event: Event) -> None:
        """Replace the event recorded by future launches."""

class ExecutableEventWaitNode(ExecutableGraphNode):
    """An executable event-wait-node view."""

    def update(self, event: Event) -> None:
        """Replace the event waited on by future launches."""

class ExecutableHostCallbackNode(ExecutableGraphNode):
    """An executable host-callback-node view."""

    def update(self, fn, *, user_data=None) -> None:
        """Replace the callback and user-data binding for future launches.

        ``fn`` may be a Python callable, or a ctypes function pointer whose
        declared prototype matches ``CUhostFn`` (``void (*)(void*)``); a
        mismatched prototype raises ``TypeError``.

        .. warning::

            Callbacks must not call CUDA API functions. Doing so may deadlock
            or corrupt driver state.
        """
__all__ = ['AllocNode', 'ChildGraphNode', 'ConditionalNode', 'EmptyNode', 'EventRecordNode', 'EventWaitNode', 'ExecutableChildGraphNode', 'ExecutableEventRecordNode', 'ExecutableEventWaitNode', 'ExecutableGraphNode', 'ExecutableHostCallbackNode', 'ExecutableKernelNode', 'ExecutableMemcpyNode', 'ExecutableMemsetNode', 'FreeNode', 'HostCallbackNode', 'IfElseNode', 'IfNode', 'KernelNode', 'MemcpyNode', 'MemsetNode', 'SwitchNode', 'WhileNode']