You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit c3dc370
Browse filesBrowse the repository at this point in the historyBrowse files
cuda.core docs: which reporting channel to use, and what pw_ really does
Review follow-ups on NVIDIA#2759:
- DESIGN.md gains a table that picks the reporting channel by situation
(a path that can raise, an except block whose rollback failed, a deleter,
a Python destructor path, a CUDA callback thread), with the thread-local
mechanisms marked transitional pending NVIDIA#2760, and a section on p_ versus
pw_: a pw_ wrapper acquires the GIL on failure and runs user Python, so it
is never used while a C++ lock is held. Python exceptions raised by that
code never become C++ exceptions; nothing on the report path may allocate
or throw. CUDA callback threads do nothing that needs the GIL;
Py_AddPendingCall is how work leaves them.
- AGENTS.md gets the same two rules in short form. The header comments on the
reporting functions and on WarnOnFailure say what pw_ runs.
- note_or_report_cuda_error is renamed attach_rollback_failure: callers are in
one situation (a rollback failed while an exception is in flight) and should
not have to know the note-or-warning mechanism. The test hook follows.
Co-Authored-By: Claude Fable 5.1 <[email protected]>
Copy file name to clipboardExpand all lines: cuda_core/cuda/core/_cpp/DESIGN.md
+38-1Lines changed: 38 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -334,10 +334,47 @@ terminate the process; see `docs/source/error_handling.rst` and the "Failure han
334
334
section of `AGENTS.md` for the policy.
335
335
336
336
A rollback that fails inside a Cython `except` block is not a non-propagating
337
-
path: `note_or_report_cuda_error()` attaches it as a note to the exception being
337
+
path: `attach_rollback_failure()` attaches it as a note to the exception being
338
338
handled (`PyErr_GetHandledException`, Python 3.11+) and falls back to a report
339
339
only when there is no such exception or notes are unavailable.
340
340
341
+
### Which channel to use
342
+
343
+
Pick the channel by where the failure happens. Every failure goes through
344
+
exactly one of these; none is ever dropped.
345
+
346
+
| Where you are | Use | Result |
347
+
|---|---|---|
348
+
| Cython, on a path that can raise |`HANDLE_RETURN(status)`| Raises `CUDAError`. A restoration detail recorded by the C++ helper becomes a note on the exception. |
349
+
| Cython, after a handle constructor returned an empty handle |`HANDLE_RETURN(get_last_error())`, immediately | Same. Transitional: #2760 makes constructors return the status instead. |
350
+
| C++, a helper that runs an operation in another context | Return the `CUresult`; `exit_context` records the restoration detail | Cython raises it. Transitional: #2760 returns the restoration status as a second out-parameter. |
351
+
| Cython, inside an `except` block whose rollback failed |`attach_rollback_failure(op, status, detail)`| Adds a note to the exception being handled. Reports instead if nothing is being handled or notes do not exist (Python 3.10). |
352
+
| C++, a deleter or deferred cleanup | A `pw_*` wrapper, or `report_cuda_error()` / `report_message()`| Emits `CUDAWarning`. Never raises. |
353
+
| Cython or Python, a `__dealloc__` or destructor-path callback |`warnings.warn(msg, CUDAWarning, stacklevel=2)`| Same. |
354
+
| A CUDA callback thread | Nothing that needs the GIL. Hand the work to the deferred-cleanup queue with `Py_AddPendingCall`| CUDA forbids driver calls there, and acquiring the GIL there can deadlock with a GIL holder blocked in a driver call. GIL-free C API that only schedules work is fine. |
355
+
356
+
### `p_` versus `pw_`
357
+
358
+
A `p_` function pointer calls the driver and nothing else. Its `pw_` twin calls
359
+
the driver and, if the call fails, acquires the GIL and runs Python: the warning
360
+
filters, `showwarning`, or `sys.unraisablehook`. Any of those can be user code,
361
+
and user code can call back into cuda.core. This is the one place where the
362
+
handle layer runs code it does not control, and it is the entry point through
363
+
which a thread holding a C++ lock can deadlock (see "GIL Management").
364
+
365
+
Python exceptions raised by that code never become C++ exceptions: the C API
366
+
reports them as return codes, and `report_message` hands them to
367
+
`sys.unraisablehook`. Nothing on the report path may allocate or throw, since a
368
+
deleter is `noexcept`.
369
+
370
+
So: use `pw_` only in deleters and cleanup paths that hold no C++ lock and have
371
+
finished updating the layer's own state. Where a lock must stay held, call
372
+
`p_`, keep the status, and report after the lock is released, as
373
+
`deviceptr_import_ipc` does. CUDA callback threads need no extra rule for
374
+
`pw_`: the driver call is forbidden there, so the wrapper is too. The general
375
+
rule for those threads is no GIL and no Python objects; GIL-free scheduling
376
+
calls such as `Py_AddPendingCall` are how work leaves them.
0 commit comments