Regenerate cuda.core stubs after main merge

Author: rwgk

cuda_core/cuda/core/_device.pyi

@@ -1027,4 +1027,5 @@ class Device:
         .. versionadded:: 1.1.0
         """
 _tls = threading.local()
-_lock = threading.Lock()
+_lock = threading.Lock()
+__all__ = ['Device']

cuda_core/cuda/core/_event.pyi

@@ -180,6 +180,7 @@ class IPCEventDescriptor:
 
     def __reduce__(self) -> tuple[object, ...]:
         ...
+__all__ = ['Event', 'EventOptions']
 
 def _reduce_event(event: Event) -> tuple[object, ...]:
     ...

cuda_core/cuda/core/_launch_config.pyi

@@ -18,15 +18,15 @@ class LaunchConfig:
 
     Attributes
     ----------
-    grid : Union[tuple, int]
+    grid : tuple | int
         Collection of threads that will execute a kernel function. When cluster
         is not specified, this represents the number of blocks, otherwise
         this represents the number of clusters.
-    cluster : Union[tuple, int]
+    cluster : tuple | int
         Group of blocks (Thread Block Cluster) that will execute on the same
         GPU Processing Cluster (GPC). Blocks within a cluster have access to
         distributed shared memory and can be explicitly synchronized.
-    block : Union[tuple, int]
+    block : tuple | int
         Group of threads (Thread Block) that will execute on the same
         streaming multiprocessor (SM). Threads within a thread blocks have
         access to shared memory and can be explicitly synchronized.
@@ -35,23 +35,29 @@ class LaunchConfig:
         (Default to size 0)
     is_cooperative : bool, optional
         Whether this config can be used to launch a cooperative kernel.
+    programmatic_stream_serialization : bool, optional
+        Whether to allow programmatic stream serialization (PDL). When True,
+        the kernel may overlap with a previous kernel in the same stream that
+        signals completion via programmatic means.
     """
 
-    def __init__(self, grid: int | tuple[int, ...] | None=None, cluster: int | tuple[int, ...] | None=None, block: int | tuple[int, ...] | None=None, shmem_size: int | None=None, is_cooperative: bool=False) -> None:
+    def __init__(self, grid: int | tuple[int, ...] | None=None, cluster: int | tuple[int, ...] | None=None, block: int | tuple[int, ...] | None=None, shmem_size: int | None=None, is_cooperative: bool=False, programmatic_stream_serialization: bool=False) -> None:
         """Initialize LaunchConfig with validation.
 
         Parameters
         ----------
-        grid : Union[tuple, int], optional
+        grid : tuple | int, optional
             Grid dimensions (number of blocks or clusters if cluster is specified)
-        cluster : Union[tuple, int], optional
+        cluster : tuple | int, optional
             Cluster dimensions (Thread Block Cluster)
-        block : Union[tuple, int], optional
+        block : tuple | int, optional
             Block dimensions (threads per block)
         shmem_size : int, optional
             Dynamic shared memory size in bytes (default: 0)
         is_cooperative : bool, optional
             Whether to launch as cooperative kernel (default: False)
+        programmatic_stream_serialization : bool, optional
+            Whether to allow programmatic stream serialization / PDL (default: False)
         """
 
     def _identity(self) -> tuple[Any, ...]:
@@ -65,7 +71,8 @@ class LaunchConfig:
 
     def __hash__(self) -> int:
         ...
-_LAUNCH_CONFIG_ATTRS = ('grid', 'cluster', 'block', 'shmem_size', 'is_cooperative')
+_LAUNCH_CONFIG_ATTRS = ('grid', 'cluster', 'block', 'shmem_size', 'is_cooperative', 'programmatic_stream_serialization')
+__all__ = ['LaunchConfig']
 
 def _to_native_launch_config(config: LaunchConfig) -> object:
     """Convert LaunchConfig to native driver CUlaunchConfig.

cuda_core/cuda/core/_launcher.pyi

@@ -8,6 +8,7 @@ from cuda.core._stream import Stream
 from cuda.core.graph import GraphBuilder
 from cuda.core.typing import IsStreamType
 
+__all__ = ['launch']
 
 def launch(stream: Stream | GraphBuilder | IsStreamType, config: LaunchConfig, kernel: Kernel, *kernel_args) -> None:
     """Launches a :obj:`~_module.Kernel`

cuda_core/cuda/core/_memory/_buffer.pyi

@@ -39,12 +39,15 @@ class Buffer:
         ...
 
     @classmethod
-    def _init(cls, ptr: DevicePointerType, size: int, mr: MemoryResource | None=None, ipc_descriptor: IPCBufferDescriptor | None=None, owner: object | None=None) -> Buffer:
+    def _init(cls, ptr: DevicePointerType, size: int, mr: MemoryResource | None=None, ipc_descriptor: IPCBufferDescriptor | None=None, owner: object | None=None, *, stream: Stream | GraphBuilder | None=None) -> Buffer:
         """Create a Buffer from a raw pointer.
 
         When ``mr`` is provided, the buffer takes ownership: ``mr.deallocate()``
         is called when the buffer is closed or garbage collected.  When ``owner``
         is provided, the owner is kept alive but no deallocation is performed.
+        When ``mr`` is provided, a deallocation stream is recorded at creation
+        (``stream`` if given, otherwise ``default_stream()``). Recording a
+        default-stream token requires a CUDA context to be current.
         """
 
     @staticmethod
@@ -55,7 +58,7 @@ class Buffer:
         ...
 
     @staticmethod
-    def from_handle(ptr: DevicePointerType, size: int, mr: MemoryResource | None=None, owner: object | None=None) -> Buffer:
+    def from_handle(ptr: DevicePointerType, size: int, mr: MemoryResource | None=None, owner: object | None=None, *, stream: Stream | GraphBuilder | None=None) -> Buffer:
         """Create a new :class:`Buffer` object from a pointer.
 
         Parameters
@@ -72,6 +75,13 @@ class Buffer:
             An object holding external allocation that the ``ptr`` points to.
             The reference is kept as long as the buffer is alive.
             The ``owner`` and ``mr`` cannot be specified together.
+        stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder`, optional
+            Keyword-only. The stream used to order the buffer's deallocation
+            when ``mr`` owns the pointer. Defaults to ``default_stream()``.
+            Recording a default-stream token requires a CUDA context to be
+            current. If the buffer may be freed from a different host thread,
+            pass a stream other than the per-thread default stream, which
+            refers to a different stream on each thread.
 
         Note
         ----
@@ -264,7 +274,12 @@ class MemoryResource:
         stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder`
             Keyword-only. The stream on which to perform the allocation
             asynchronously. Must be passed explicitly; pass
-            ``device.default_stream`` to use the default stream.
+            ``device.default_stream`` to use the default stream. For subclasses
+            that support stream-ordered deallocation, this stream also orders
+            the buffer's eventual deallocation, so if the buffer may be freed
+            from a different host thread, prefer a stream other than the
+            per-thread default stream, which refers to a different stream on
+            each thread.
 
         Returns
         -------

cuda_core/cuda/core/_memory/_copy_attributes.pyi

@@ -0,0 +1,3 @@
+# This file was generated by stubgen-pyx v0.2.6 from cuda_core/cuda/core/_memory/_copy_attributes.pyx
+
+from __future__ import annotations

cuda_core/cuda/core/_memory/_copy_ops.pyi

@@ -0,0 +1,85 @@
+# This file was generated by stubgen-pyx v0.2.6 from cuda_core/cuda/core/_memory/_copy_ops.pyx
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from cuda.core._memory._buffer import Buffer
+from cuda.core._memory._copy_enums import CopyOptions
+from cuda.core._stream import Stream
+
+_SINGLE_COPY_HINT = 'Buffer.copy_to / Buffer.copy_from'
+
+def _normalize_copy_options(options: CopyOptions | Sequence[CopyOptions] | None, n: int) -> tuple[CopyOptions, ...]:
+    """Expand ``options`` to exactly one :class:`CopyOptions` per copy.
+
+    ``None`` and a scalar broadcast; a sequence pairs by index and must
+    already have length ``n``.
+
+    Internal, but deliberately importable: options are hints that change
+    how the driver stages a transfer and never the bytes it produces, so
+    this expansion (and the run encoding applied to it) is the only
+    observable evidence that a scalar reached every copy.
+    """
+
+def copy_batch(stream: Stream, srcs: Sequence[Buffer], dsts: Sequence[Buffer], *, options: CopyOptions | Sequence[CopyOptions] | None=None) -> None:
+    """Copy a batch of buffers asynchronously.
+
+    Source buffer and destination buffer sizes must match. For a single
+    buffer, use :meth:`Buffer.copy_to` or :meth:`Buffer.copy_from`.
+
+    The driver provides no graph-node form of ``cuMemcpyBatchAsync``, so
+    this cannot be captured into a graph. Both passing a
+    :class:`~graph.GraphBuilder` and passing its underlying
+    :attr:`~graph.GraphBuilder.stream` while capture is active are
+    rejected. Build graph copies with
+    :meth:`graph.GraphNode.memcpy` or per-buffer :meth:`Buffer.copy_to`.
+
+    Parameters
+    ----------
+    stream : :class:`~_stream.Stream`
+        Stream for the asynchronous copy. First positional and required
+        (mirrors :func:`launch`). Does not accept a capturing stream
+        (including a :class:`~graph.GraphBuilder`'s underlying stream); use
+        :meth:`graph.GraphNode.memcpy` or per-buffer
+        :meth:`Buffer.copy_to` to build copies into a graph.
+    srcs : Sequence[:class:`Buffer`]
+        Source buffers. Must be a sequence, not a single Buffer.
+    dsts : Sequence[:class:`Buffer`]
+        Destination buffers. Must match ``len(srcs)``.
+    options : :class:`CopyOptions` | Sequence[:class:`CopyOptions`] | None
+        Per-copy options. A single value applies to every copy; a
+        sequence pairs by index and must match ``len(srcs)``. ``None``
+        uses stream-ordered defaults.
+
+    Raises
+    ------
+    ValueError
+        If lengths or sizes mismatch.
+    TypeError
+        If a single Buffer is passed instead of a sequence, if a
+        default-stream token (``LEGACY_DEFAULT_STREAM`` /
+        ``PER_THREAD_DEFAULT_STREAM``) is passed, or if the stream is
+        currently in graph capture mode.
+
+    Notes
+    -----
+    Batching through ``cuMemcpyBatchAsync`` requires all three of:
+    ``cuda.core`` built against CUDA 13 headers, ``cuda.bindings`` 13.0 or
+    newer, and a driver reporting CUDA 13.0 or newer
+    (``cuDriverGetVersion() >= 13000``). ``cuda.bindings`` binds only the
+    CUDA 13.0 revision of the entry point, so a driver that predates it is
+    refused even where it implements the earlier CUDA 12.8 signature.
+
+    The driver may execute batch items concurrently and in any order.
+    A batch must therefore not contain copies where the source range of
+    one copy overlaps the destination range of another; such aliasing
+    produces undefined results. Detecting overlaps at runtime is
+    impractical; callers are responsible for ensuring no aliasing exists.
+
+    On pre-CUDA 13 installs the copies fall back to a Python-level loop
+    over ``cuMemcpyAsync``, so the potential performance benefit of
+    asynchronous batched copies is not realized. :class:`CopyOptions` are
+    silently ignored on the fallback path.
+
+    """

cuda_core/cuda/core/_memory/_ipc.pyi

@@ -84,7 +84,7 @@ class IPCAllocationHandle:
     @property
     def uuid(self) -> uuid.UUID:
         ...
-__all__ = ['IPCBufferDescriptor', 'IPCAllocationHandle']
+__all__ = []
 
 def _reduce_allocation_handle(alloc_handle: IPCAllocationHandle) -> tuple[object, ...]:
     ...

cuda_core/cuda/core/_memory/_managed_memory_ops.pyi

@@ -11,6 +11,7 @@ from cuda.core._memory._buffer import Buffer
 from cuda.core._stream import Stream
 from cuda.core._utils.cuda_utils import driver
 
+_SINGLE_MANAGED_HINT = 'the ManagedBuffer instance method'
 
 def discard_batch(stream: Stream | GraphBuilder, buffers: Sequence[Buffer]) -> None:
     """Discard a batch of managed-memory ranges.

cuda_core/cuda/core/_memory/_pinned_memory_resource.pyi

@@ -5,8 +5,11 @@ from __future__ import annotations
 import uuid
 from dataclasses import dataclass
 
+from cuda.core._memory._buffer import Buffer
 from cuda.core._memory._ipc import IPCAllocationHandle
 from cuda.core._memory._memory_pool import _MemPool
+from cuda.core._stream import Stream
+from cuda.core.graph import GraphBuilder
 
 
 @dataclass
@@ -63,6 +66,14 @@ class PinnedMemoryResource(_MemPool):
 
     Notes
     -----
+    The device associated with ``stream`` must support host memory pools. If
+    ``numa_id`` is set or derived for IPC, it must support host NUMA memory pools.
+    You can query these capabilities through
+    ``Device.properties.host_memory_pools_supported`` and
+    ``Device.properties.host_numa_memory_pools_supported``. If the required pool
+    is unsupported and stream-ordered allocation is not needed, use
+    :class:`LegacyPinnedMemoryResource`.
+
     To create an IPC-Enabled memory resource (MR) that is capable of sharing
     allocations between processes, specify ``ipc_enabled=True`` in the initializer
     option. When IPC is enabled and ``numa_id`` is not specified, the NUMA node
@@ -76,6 +87,9 @@ class PinnedMemoryResource(_MemPool):
     def __init__(self, options: PinnedMemoryResourceOptions | dict[str, object] | None=None) -> None:
         ...
 
+    def allocate(self, size: int, *, stream: Stream | GraphBuilder) -> Buffer:
+        """Allocate a host-pinned buffer asynchronously on the supplied stream."""
+
     def __reduce__(self) -> tuple[object, ...]:
         ...