René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"cuda.core: reject stream=None — require explicit stream everywhere","articleBody":"## Summary\n\nSeveral `cuda.core` APIs accept `stream=None` and silently fall back to `default_stream()` (or NULL). This makes the stream choice implicit and environment-dependent (`CUDA_PYTHON_CUDA_PER_THREAD_DEFAULT_STREAM`), which is error-prone. Users should always pass a stream explicitly — including `device.default_stream` when they want the default.\n\n## Design rule\n\n`stream` should be a **keyword-only argument with no default value** (`*, stream: Stream`), so callers must always pass a stream explicitly.\n\nAPIs that already follow this convention:\n- `Buffer.copy_to(dst=None, *, stream: Stream | GraphBuilder)`\n- `Buffer.copy_from(src, *, stream: Stream | GraphBuilder)`\n- `Buffer.fill(value, *, stream: Stream | GraphBuilder)`\n\n## APIs that need to change\n\n### `stream=None` → `default_stream()` (implicit fallback, remove it)\n\n- `MemoryPool.allocate()` / `deallocate()`\n- `GraphMemoryResource.allocate()` / `deallocate()`\n- `GraphicsResource.map()`\n- `LegacyPinnedMemoryResource.allocate()`\n- `_SynchronousMemoryResource.allocate()`\n- `Device.allocate()` (delegates to the above)\n\n### `stream=None` → NULL / legacy default (same issue)\n\n- `Kernel.max_potential_cluster_size(config, stream=None)`\n- `Kernel.max_active_clusters(config, stream=None)`\n\n### `stream` should become keyword-only\n\n- `GraphBuilder.launch(self, stream: Stream)` — currently positional, should be `(self, *, stream: Stream)`\n\n## APIs that are fine (no change needed)\n\n- `launch(stream, config, kernel, *args)` — stream is the 1st positional arg by design\n- `Buffer.close(stream=None)` — None means \"reuse the original stream\", by design\n- `GraphicsResource.unmap(stream=None)` / `close(stream=None)` — same, reuses the mapping stream\n\n## Proposed implementation\n\n1. Have `Stream_accept()` raise `TypeError` when `stream is None`, so the check is centralized and cannot be forgotten.\n2. Remove the `= None` default from every affected API signature.\n3. Make `stream` keyword-only where it isn't already (except `launch()` where it's intentionally positional).\n\n## Prior art: CCCL's cccl-runtime\n\nCCCL's modern CUDA runtime (libcudacxx, `cuda::` namespace) follows the same explicit-stream principle:\n\n> The CUDA default (NULL) stream is not exposed as a first-class runtime object because it is tied to implicit per-device state and encourages hidden dependencies.\n>\n> — `docs/libcudacxx/runtime/cudart_interactions.rst`\n\nConcretely:\n- `cuda::launch(stream, config, kernel, args...)` requires an explicit `stream_ref` as the first parameter, with no default.\n- The `cuda::mr::resource` concept requires `allocate(cuda::stream_ref, ...)` / `deallocate(cuda::stream_ref, ...)` — no fallback to a default stream.\n- `cuda::stream_ref` deletes constructors from `int` and `nullptr`, and deprecates the parameterless (default stream) constructor.\n","author":{"url":"https://github.com/leofang","@type":"Person","name":"leofang"},"datePublished":"2026-05-01T01:11:53Z","url":"https://github.com/NVIDIA/cuda-python/issues/2001"}