cuda.core.utils.copy_batch#

cuda.core.utils.copy_batch(Stream stream: Stream, srcs: Sequence[Buffer], dsts: Sequence[Buffer], *, options: CopyOptions | Sequence[CopyOptions] | None = None) → None#

Copy a batch of buffers asynchronously.

Sizes are taken from the source buffers and each destination must match. For a single buffer, use Buffer.copy_to() or Buffer.copy_from().

The driver provides no graph-node form of cuMemcpyBatchAsync, so this cannot be captured into a graph. Build graph copies with graph.GraphNode.memcpy() or per-buffer Buffer.copy_to().

Parameters:

  • stream (Stream) – Stream for the asynchronous copy. First positional and required (mirrors launch()). Unlike most stream-taking APIs this does not accept a GraphBuilder; one is rejected with TypeError because the copy cannot be captured.

  • srcs (Sequence[Buffer]) – Source buffers. Must be a sequence, not a single Buffer.

  • dsts (Sequence[Buffer]) – Destination buffers. Must match len(srcs).

  • options (CopyOptions | Sequence[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.

  • NotImplementedError – If non-default options are given where cuMemcpyBatchAsync is unavailable (see Notes).

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.

Short of that, the copies fall back to a Python-level loop over cuMemcpyAsync, which is semantically equivalent but does not amortize launch overhead. The fallback has no way to convey CopyOptions to the driver, so non-default options raise NotImplementedError there rather than being silently ignored.

Warns:

UserWarning – If overlap_mode='prefer_overlap_with_compute' is requested on a non-integrated (discrete) GPU.

On this page