raise if call with MemcpySrcAccessOrder.DURING_API_CALL requires fallback

Author: juenglin

cuda_core/cuda/core/_memory/_buffer.pyi

@@ -191,15 +191,22 @@ class Buffer:
             Not accepted with ``LEGACY_DEFAULT_STREAM`` or a capturing stream
             (matches :func:`utils.copy_batch`); use ``PER_THREAD_DEFAULT_STREAM``
             or :meth:`graph.GraphNode.memcpy` instead. On cuda.bindings/driver
-            older than CUDA 13.2, the copy falls back to ``cuMemcpyAsync`` with
-            ``options`` silently ignored.
+            older than CUDA 13.2, ``src_access_order`` values of ``STREAM``
+            and ``ANY`` fall back to ``cuMemcpyAsync`` silently; ``DURING_API_CALL``
+            raises instead of silently downgrading its guarantee.
 
         Raises
         ------
         TypeError
             If ``options`` is not a :class:`~utils.CopyOptions` instance, or
             if ``options`` is given together with ``LEGACY_DEFAULT_STREAM``
             or a stream currently in graph capture mode.
+        RuntimeError
+            If ``options.src_access_order`` is ``DURING_API_CALL`` and
+            cuda.bindings/driver older than CUDA 13.2 makes the native
+            ``cuMemcpyWithAttributesAsync`` path unavailable: the
+            ``cuMemcpyAsync`` fallback reads the source in stream order
+            only, which cannot honor that guarantee.
 
         """
 
@@ -218,15 +225,22 @@ class Buffer:
             Not accepted with ``LEGACY_DEFAULT_STREAM`` or a capturing stream
             (matches :func:`utils.copy_batch`); use ``PER_THREAD_DEFAULT_STREAM``
             or :meth:`graph.GraphNode.memcpy` instead. On cuda.bindings/driver
-            older than CUDA 13.2, the copy falls back to ``cuMemcpyAsync`` with
-            ``options`` silently ignored.
+            older than CUDA 13.2, ``src_access_order`` values of ``STREAM``
+            and ``ANY`` fall back to ``cuMemcpyAsync`` silently; ``DURING_API_CALL``
+            raises instead of silently downgrading its guarantee.
 
         Raises
         ------
         TypeError
             If ``options`` is not a :class:`~utils.CopyOptions` instance, or
             if ``options`` is given together with ``LEGACY_DEFAULT_STREAM``
             or a stream currently in graph capture mode.
+        RuntimeError
+            If ``options.src_access_order`` is ``DURING_API_CALL`` and
+            cuda.bindings/driver older than CUDA 13.2 makes the native
+            ``cuMemcpyWithAttributesAsync`` path unavailable: the
+            ``cuMemcpyAsync`` fallback reads the source in stream order
+            only, which cannot honor that guarantee.
         """
 
     def fill(self, value: int | BufferProtocol, *, stream: Stream | GraphBuilder) -> None:

cuda_core/cuda/core/_memory/_buffer.pyx

@@ -40,7 +40,7 @@ import sys
 from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
-from cuda.core._memory._copy_enums import CopyOptions
+from cuda.core._memory._copy_enums import CopyOptions, _reject_unsupported_during_api_call
 from cuda.core._utils.pycompat import BufferProtocol
 from cuda.core._dlpack import classify_dl_device, make_py_capsule
 from cuda.core._device import Device
@@ -221,8 +221,14 @@ cdef void _dispatch_buffer_copy(
     if _with_attributes_available():
         _do_copy_with_attributes(dst, src, nbytes, options, as_cu(s._h_stream))
     else:
-        # Matches copy_batch: options are silently ignored on the
-        # pre-CUDA-13.2 driver/bindings fallback path.
+        _reject_unsupported_during_api_call(
+            options.src_access_order,
+            "cuda.bindings and the driver to both report CUDA 13.2 or newer "
+            "(cuMemcpyWithAttributesAsync is unavailable here)",
+        )
+        # STREAM and ANY never require access sooner than stream order, so
+        # cuMemcpyAsync satisfies them; options are otherwise silently
+        # ignored on this pre-CUDA-13.2 fallback path, matching copy_batch.
         with nogil:
             HANDLE_RETURN(cydriver.cuMemcpyAsync(dst, src, nbytes, as_cu(s._h_stream)))
 
@@ -482,15 +488,22 @@ cdef class Buffer:
             Not accepted with ``LEGACY_DEFAULT_STREAM`` or a capturing stream
             (matches :func:`utils.copy_batch`); use ``PER_THREAD_DEFAULT_STREAM``
             or :meth:`graph.GraphNode.memcpy` instead. On cuda.bindings/driver
-            older than CUDA 13.2, the copy falls back to ``cuMemcpyAsync`` with
-            ``options`` silently ignored.
+            older than CUDA 13.2, ``src_access_order`` values of ``STREAM``
+            and ``ANY`` fall back to ``cuMemcpyAsync`` silently; ``DURING_API_CALL``
+            raises instead of silently downgrading its guarantee.
 
         Raises
         ------
         TypeError
             If ``options`` is not a :class:`~utils.CopyOptions` instance, or
             if ``options`` is given together with ``LEGACY_DEFAULT_STREAM``
             or a stream currently in graph capture mode.
+        RuntimeError
+            If ``options.src_access_order`` is ``DURING_API_CALL`` and
+            cuda.bindings/driver older than CUDA 13.2 makes the native
+            ``cuMemcpyWithAttributesAsync`` path unavailable: the
+            ``cuMemcpyAsync`` fallback reads the source in stream order
+            only, which cannot honor that guarantee.
 
         """
         cdef Stream s = Stream_accept(stream)
@@ -527,15 +540,22 @@ cdef class Buffer:
             Not accepted with ``LEGACY_DEFAULT_STREAM`` or a capturing stream
             (matches :func:`utils.copy_batch`); use ``PER_THREAD_DEFAULT_STREAM``
             or :meth:`graph.GraphNode.memcpy` instead. On cuda.bindings/driver
-            older than CUDA 13.2, the copy falls back to ``cuMemcpyAsync`` with
-            ``options`` silently ignored.
+            older than CUDA 13.2, ``src_access_order`` values of ``STREAM``
+            and ``ANY`` fall back to ``cuMemcpyAsync`` silently; ``DURING_API_CALL``
+            raises instead of silently downgrading its guarantee.
 
         Raises
         ------
         TypeError
             If ``options`` is not a :class:`~utils.CopyOptions` instance, or
             if ``options`` is given together with ``LEGACY_DEFAULT_STREAM``
             or a stream currently in graph capture mode.
+        RuntimeError
+            If ``options.src_access_order`` is ``DURING_API_CALL`` and
+            cuda.bindings/driver older than CUDA 13.2 makes the native
+            ``cuMemcpyWithAttributesAsync`` path unavailable: the
+            ``cuMemcpyAsync`` fallback reads the source in stream order
+            only, which cannot honor that guarantee.
         """
         cdef Stream s = Stream_accept(stream)
         cdef size_t dst_size = self._size

cuda_core/cuda/core/_memory/_copy_enums.py

@@ -160,6 +160,40 @@ def _to_driver_flags(self) -> int:
     _OVERLAP_MODE_TO_DRIVER = {}
 
 
+def _reject_unsupported_during_api_call(
+    src_access_order: MemcpySrcAccessOrder, requirement: str, *, index: int | None = None
+) -> None:
+    """Raise if ``src_access_order`` is DURING_API_CALL but the native attributes
+    path (``cuMemcpyWithAttributesAsync`` / ``cuMemcpyBatchAsync``) is unavailable.
+
+    STREAM and ANY never promise access sooner than stream order, so a plain
+    ``cuMemcpyAsync`` fallback satisfies them; DURING_API_CALL specifically
+    promises all source reads complete before the call returns, which
+    ``cuMemcpyAsync`` cannot provide (it reads the source in stream order
+    only). Silently downgrading that guarantee would let a caller reuse or
+    overwrite the source buffer before the real, stream-ordered read
+    happens: a silent data race, not a missed optimization. ``requirement``
+    names what the native path needs and why it is unavailable here;
+    ``index`` identifies the offending copy within a batch.
+
+    Internal, but deliberately importable: shared between the per-buffer and
+    batched fallback paths so both raise identically, and directly testable
+    without needing an actual old driver/bindings install.
+    """
+    if src_access_order != MemcpySrcAccessOrder.DURING_API_CALL:
+        return
+    where = f" at index {index}" if index is not None else ""
+    raise RuntimeError(
+        f"src_access_order=DURING_API_CALL{where} requires {requirement}. A "
+        "plain cuMemcpyAsync fallback reads the source in stream order only, "
+        "which would silently violate the guarantee that all source reads "
+        "complete before the call returns, letting the caller reuse the "
+        "source buffer before the real (stream-ordered) read happens. Use "
+        "src_access_order=STREAM or ANY, or omit options, if that works for "
+        "your use case."
+    )
+
+
 def _attr_run_starts(attrs: Sequence[CopyOptions]) -> list[int]:
     """Return the start index of each maximal run of equal attributes.
 

cuda_core/cuda/core/_memory/_copy_ops.pyi

@@ -63,6 +63,11 @@ def copy_batch(stream: Stream, srcs: Sequence[Buffer], dsts: Sequence[Buffer], *
         If a single Buffer is passed instead of a sequence, if
         ``LEGACY_DEFAULT_STREAM`` is passed, or if the stream is currently
         in graph capture mode.
+    RuntimeError
+        If any copy requests ``src_access_order=DURING_API_CALL`` and the
+        native ``cuMemcpyBatchAsync`` path is unavailable (see Notes): the
+        per-copy ``cuMemcpyAsync`` fallback reads the source in stream
+        order only, which cannot honor that guarantee.
 
     Notes
     -----
@@ -81,7 +86,11 @@ def copy_batch(stream: Stream, srcs: Sequence[Buffer], dsts: Sequence[Buffer], *
 
     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.
+    asynchronous batched copies is not realized. ``src_access_order`` values
+    of ``STREAM`` and ``ANY`` are silently ignored on the fallback path
+    (stream-ordered access already satisfies both); ``DURING_API_CALL``
+    raises ``RuntimeError`` instead, since silently downgrading it to
+    stream-ordered access would let a caller reuse the source buffer before
+    the real read happens.
 
     """

cuda_core/cuda/core/_memory/_copy_ops.pyx

@@ -21,7 +21,11 @@ from cuda.core._utils.cuda_utils cimport HANDLE_RETURN
 # a pragma to be seen as used.
 from cuda.core._utils.version cimport cy_driver_version  # no-cython-lint
 
-from cuda.core._memory._copy_enums import CopyOptions, _attr_run_starts  # no-cython-lint
+from cuda.core._memory._copy_enums import (
+    CopyOptions,
+    _attr_run_starts,  # no-cython-lint
+    _reject_unsupported_during_api_call,
+)
 
 _SINGLE_COPY_HINT = "Buffer.copy_to / Buffer.copy_from"
 
@@ -131,6 +135,11 @@ def copy_batch(
         If a single Buffer is passed instead of a sequence, if
         ``LEGACY_DEFAULT_STREAM`` is passed, or if the stream is currently
         in graph capture mode.
+    RuntimeError
+        If any copy requests ``src_access_order=DURING_API_CALL`` and the
+        native ``cuMemcpyBatchAsync`` path is unavailable (see Notes): the
+        per-copy ``cuMemcpyAsync`` fallback reads the source in stream
+        order only, which cannot honor that guarantee.
 
     Notes
     -----
@@ -149,8 +158,12 @@ def copy_batch(
 
     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.
+    asynchronous batched copies is not realized. ``src_access_order`` values
+    of ``STREAM`` and ``ANY`` are silently ignored on the fallback path
+    (stream-ordered access already satisfies both); ``DURING_API_CALL``
+    raises ``RuntimeError`` instead, since silently downgrading it to
+    stream-ordered access would let a caller reuse the source buffer before
+    the real read happens.
 
     """
     cdef tuple src_bufs = Buffer_coerce_batch(srcs, "copy_batch", _SINGLE_COPY_HINT)
@@ -211,17 +224,36 @@ cdef void _do_copy_batch(tuple src_bufs, tuple dst_bufs, Stream s, tuple attr_tu
         if _batch_entry_point_available():
             _do_copy_batch_native(src_bufs, dst_bufs, s, attr_tuple)
         else:
+            _reject_during_api_call_fallback(attr_tuple)
             _do_copy_batch_loop(src_bufs, dst_bufs, s)
     ELSE:
+        _reject_during_api_call_fallback(attr_tuple)
         _do_copy_batch_loop(src_bufs, dst_bufs, s)
 
 
+cdef void _reject_during_api_call_fallback(tuple attr_tuple):
+    """Raise before the per-copy cuMemcpyAsync loop if any copy needs
+    DURING_API_CALL, which that fallback cannot honor (see
+    _reject_unsupported_during_api_call for why this must raise rather than
+    silently ignore the option, unlike STREAM and ANY).
+    """
+    cdef Py_ssize_t i
+    for i in range(len(attr_tuple)):
+        _reject_unsupported_during_api_call(
+            (<object>attr_tuple[i]).src_access_order,
+            "cuda.core built against CUDA 13 headers and cuda.bindings/driver "
+            "13.0 or newer (cuMemcpyBatchAsync is unavailable here)",
+            index=i,
+        )
+
+
 cdef void _do_copy_batch_loop(tuple src_bufs, tuple dst_bufs, Stream s):
     """Per-copy cuMemcpyAsync fallback where the batch entry point is absent.
 
     Issues copies one at a time, so the performance benefit of batching is
-    not realized. Callers guarantee the options are defaults; copy_batch
-    rejects anything else before reaching here.
+    not realized. STREAM and ANY are silently ignored here (satisfied by
+    stream-ordered cuMemcpyAsync regardless); DURING_API_CALL is rejected by
+    _reject_during_api_call_fallback before this is ever called.
     """
     cdef Py_ssize_t n = len(src_bufs)
     cdef Py_ssize_t i

cuda_core/docs/source/release/1.2.0-notes.rst

@@ -14,7 +14,10 @@ New features
   by the new :class:`utils.CopyOptions` dataclass. Requires ``cuda.core``
   built against CUDA 13, ``cuda.bindings`` 13.0+, and a driver reporting
   CUDA 13.0 or newer; otherwise falls back to a per-copy ``cuMemcpyAsync``
-  loop with options silently ignored. Graph capture and
+  loop. On that fallback, ``src_access_order`` values of ``STREAM`` and
+  ``ANY`` are silently ignored (stream-ordered access already satisfies
+  both), while ``DURING_API_CALL`` raises ``RuntimeError`` instead of
+  silently downgrading its stronger guarantee. Graph capture and
   ``LEGACY_DEFAULT_STREAM`` are rejected (``PER_THREAD_DEFAULT_STREAM`` is
   accepted). Copies within a batch must not alias.
   (`#1333 <https://github.com/NVIDIA/cuda-python/issues/1333>`__)
@@ -32,8 +35,10 @@ New features
   ``cuMemcpyWithAttributesAsync``. Matching :func:`utils.copy_batch`, passing
   ``options`` together with ``LEGACY_DEFAULT_STREAM`` or a capturing stream
   raises ``TypeError`` (``PER_THREAD_DEFAULT_STREAM`` is accepted). On
-  ``cuda.bindings``/driver older than CUDA 13.2, the copy falls back to
-  ``cuMemcpyAsync`` with ``options`` silently ignored.
+  ``cuda.bindings``/driver older than CUDA 13.2, ``src_access_order`` values
+  of ``STREAM`` and ``ANY`` fall back to ``cuMemcpyAsync`` silently, while
+  ``DURING_API_CALL`` raises ``RuntimeError`` instead of silently
+  downgrading its stronger guarantee.
   (`#2365 <https://github.com/NVIDIA/cuda-python/issues/2365>`__)
 
 Fixes and enhancements