[libcu++] Add debugger pretty-printers for cuda event types

[owevertonguedes]

Description

closes #10094

Adds GDB and LLDB pretty-printers for cuda::event_ref, cuda::event and cuda::timed_event, following the pattern established by the cuda::std::array, cuda::std::complex and cuda::std::tuple printers.

Today a cuda::timed_event prints as its raw layout, with the ABI inline namespace and the nested base subobjects:

$1 = {
  <cuda::__4::event> = {
    <cuda::__4::event_ref> = {
      __event_ = 0x3456
    }, <No data fields>}, <No data fields>}

With this change:

$1 = cuda::timed_event = {
  handle = 0x3456
}

• libcudacxx/share/libcudacxx/gdb/event.py — recognizes exactly the three public class names after stripping typedefs and top-level qualifiers, reusing the existing helper that removes the ABI inline namespace. The handle is stored in the private event_ref base, so the printer walks recognized base subobjects to find __event_. That is what makes timed_event work, since it reaches the handle through two levels of inheritance.
• libcudacxx/share/libcudacxx/lldb/event.py — synthetic-children provider exposing the same single handle child, with a strict canonical-type recognizer.
• libcudacxx/test/debugging/event/ — harness test with 10 cases: a non-null event_ref, an owning event, a timed_event, a typedef alias, a null reference, no_init event and timed_event, event references nested in a cuda::std::array (printer composition), and a reference printed before and after reassignment.

The printers only read stored state and make no CUDA runtime or driver calls. I kept the output to the handle to match the scope of the issue and the other printers in this series. If you would like more fields, such as the device, the flags, or completion status, I am happy to add them.

The scenario needs no GPU and no CUDA driver. It uses opaque fake handles, and the two owning objects release their handle before destruction so no destructor ever passes a fake handle to the driver. I checked that rather than assuming it: the test binary runs to completion with exit status 0 in an environment where libcuda.so.1 is not present at all.

Testing notes: validated locally with gdb 15.1 (embedded Python 3.12.3), lldb 21.1.8, nvcc 12.9.86 and g++ 13.3.0:

libcudacxx.test.debugging.event.lldb ... Passed
libcudacxx.test.debugging.event.gdb .... Passed

Both goldens match the harness output on a clean run. I also checked that the tests fail for the right reasons: dropping the module from the registration tuple fails every case for that debugger, and restricting the GDB base traversal to a single level fails exactly the two timed_event cases and nothing else. One limitation worth naming: the before/after reassignment case proves the printers report the updated value rather than a stale one, but it does not isolate the LLDB update() refresh, since the case still passes with that refresh moved into the constructor.

Checklist

• New or existing tests cover these changes.
• The documentation is up to date with these changes.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 4696a444-5d4b-4f98-9865-5999695e7c92

📥 Commits

Reviewing files that changed from the base of the PR and between 5e1fc16 and cd1561e.

📒 Files selected for processing (9)

• libcudacxx/share/libcudacxx/gdb/__init__.py
• libcudacxx/share/libcudacxx/gdb/event.py
• libcudacxx/share/libcudacxx/lldb/__init__.py
• libcudacxx/share/libcudacxx/lldb/event.py
• libcudacxx/test/debugging/CMakeLists.txt
• libcudacxx/test/debugging/event/CMakeLists.txt
• libcudacxx/test/debugging/event/gdb.expected
• libcudacxx/test/debugging/event/lldb.expected
• libcudacxx/test/debugging/event/source.cu

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added debugger pretty-printing for CUDA event types in GDB and LLDB.
  • Event values now display their native handle for easier inspection.
  • Supports event references, owning events, timed events, aliases, null and uninitialized values, nested events, and updated handles.

• Tests

  • Added comprehensive debugging coverage for CUDA event inspection in both supported debuggers.

Walkthrough

Changes

CUDA event debugger printers

Layer / File(s)	Summary
GDB event printer libcudacxx/share/libcudacxx/gdb/event.py, libcudacxx/share/libcudacxx/gdb/__init__.py	GDB now recognizes cuda::event, cuda::event_ref, and cuda::timed_event, exposes the native handle as handle, and registers the printer.
LLDB event formatter libcudacxx/share/libcudacxx/lldb/event.py, libcudacxx/share/libcudacxx/lldb/__init__.py	LLDB now recognizes the same event types, exposes a synthetic handle child, and registers the formatter.
Debugger test coverage libcudacxx/test/debugging/CMakeLists.txt, libcudacxx/test/debugging/event/*	The test suite covers event references, owning and timed events, aliases, null and uninitialized values, nesting, and updates for GDB and LLDB.

Assessment against linked issues

Objective	Addressed	Explanation
Add GDB and LLDB pretty printers for cuda::event, cuda::event_ref, and cuda::timed_event [#10094]	✅
Add exhaustive debugger tests under libcudacxx/test/debugging/event [#10094]	✅

Possibly related PRs

• NVIDIA/cccl#10563: Adds parallel GDB and LLDB pretty-printer modules and debugger tests for different CUDA types.

Suggested reviewers: robertmaynard, miscco, jacobfaib

---

_{Comment @coderabbitai help to get the list of available commands.}