Skip to content

Commit 6ec8330

Browse files
committed
Eliminate _CXX_API capsule for resource handle functions
Replace the PyCapsule-based function pointer table with direct Cython cimport. Consumer modules now call resource handle functions directly through _resource_handles.so, simplifying the architecture while correctly sharing static/thread-local state. Changes: - Remove _CXX_API capsule infrastructure (resource_handles_cxx_api.hpp, _resource_handles_cxx_api.pxd, get_resource_handles_cxx_api_v1()) - Remove _init_handles_table() calls from all consumer modules - Rename create_event_handle(flags) to create_event_handle_noctx(flags) to avoid C++ overload ambiguity for Cython binding - Update DESIGN.md to reflect the simplified architecture - Add clarifying comment in build_hooks.py for cpp file discovery Closes #1452
1 parent 67b18e2 commit 6ec8330

16 files changed

Lines changed: 179 additions & 512 deletions

‎cuda_core/build_hooks.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,7 @@ def get_sources(mod_name):
105105
sources = [f"cuda/core/{mod_name}.pyx"]
106106

107107
# Add module-specific .cpp file from _cpp/ directory if it exists
108+
# Example: _resource_handles.pyx finds _cpp/resource_handles.cpp.
108109
cpp_file = f"cuda/core/_cpp/{mod_name.lstrip('_')}.cpp"
109110
if os.path.exists(cpp_file):
110111
sources.append(cpp_file)

‎cuda_core/cuda/core/_cpp/DESIGN.md‎

Lines changed: 30 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -101,25 +101,20 @@ return as_py(h_stream) # cuda.bindings.driver.CUstream
101101
```
102102
cuda/core/
103103
├── _resource_handles.pyx # Cython module (compiles resource_handles.cpp)
104-
├── _resource_handles.pxd # Cython declarations and dispatch wrappers
104+
├── _resource_handles.pxd # Cython declarations for consumer modules
105105
└── _cpp/
106106
├── resource_handles.hpp # C++ API declarations
107-
├── resource_handles.cpp # C++ implementation
108-
└── resource_handles_cxx_api.hpp # Capsule struct definition
107+
└── resource_handles.cpp # C++ implementation
109108
```
110109

111110
### Build Implications
112111

113112
The `_cpp/` subdirectory contains C++ source files that are compiled into the
114113
`_resource_handles` extension module. Other Cython modules in cuda.core do **not**
115-
link against this code directly—they access it through a capsule mechanism
116-
(explained below).
114+
link against this code directly—they `cimport` functions from
115+
`_resource_handles.pxd`, and calls go through `_resource_handles.so` at runtime.
117116

118-
## Capsule Architecture
119-
120-
The implementation uses **two separate capsule mechanisms** for different purposes:
121-
122-
### Capsule 1: C++ API Table (`_CXX_API`)
117+
## Cross-Module Function Sharing
123118

124119
**Problem**: Cython extension modules compile independently. If multiple modules
125120
(`_memory.pyx`, `_ipc.pyx`, etc.) each linked `resource_handles.cpp`, they would
@@ -129,38 +124,32 @@ each have their own copies of:
129124
- Thread-local error state
130125
- Other static data, including global caches
131126

132-
**Solution**: Only `_resource_handles.so` links the C++ code. It exports a capsule
133-
containing function pointers:
134-
135-
```cpp
136-
struct ResourceHandlesCxxApiV1 {
137-
uint32_t abi_version;
138-
uint32_t struct_size;
139-
140-
// Thread-local error handling
141-
CUresult (*get_last_error)() noexcept;
142-
CUresult (*peek_last_error)() noexcept;
143-
void (*clear_last_error)() noexcept;
127+
**Solution**: Only `_resource_handles.so` links the C++ code. The `.pyx` file
128+
uses `cdef extern from` to declare C++ functions with Cython-accessible names:
144129

145-
// Handle creation functions
146-
ContextHandle (*get_primary_context)(int device_id) noexcept;
147-
StreamHandle (*create_stream_handle)(...) noexcept;
148-
// ... etc
149-
};
130+
```cython
131+
# In _resource_handles.pyx
132+
cdef extern from "_cpp/resource_handles.hpp" namespace "cuda_core":
133+
StreamHandle create_stream_handle "cuda_core::create_stream_handle" (
134+
ContextHandle h_ctx, unsigned int flags, int priority) nogil
135+
# ... other functions
150136
```
151137

152-
Other Cython modules import this capsule at runtime and call through the function
153-
pointers. The `.pxd` file provides inline wrappers that hide this indirection:
138+
The `.pxd` file declares these same functions so other modules can `cimport` them:
154139

155140
```cython
156-
cdef inline StreamHandle create_stream_handle(...) except * nogil:
157-
return _handles_table.create_stream_handle(...)
141+
# In _resource_handles.pxd
142+
cdef StreamHandle create_stream_handle(
143+
ContextHandle h_ctx, unsigned int flags, int priority) noexcept nogil
158144
```
159145

160-
Importing modules are expected to call `_init_handles_table()` prior to calling
161-
any wrapper functions.
146+
The `cdef extern from` declaration in the `.pyx` satisfies the `.pxd` declaration
147+
directly—no wrapper functions are needed. When consumer modules `cimport` these
148+
functions, Cython generates calls through `_resource_handles.so` at runtime.
149+
This ensures all static and thread-local state lives in a single shared library,
150+
avoiding the duplicate state problem.
162151

163-
### Capsule 2: CUDA Driver API (`_CUDA_DRIVER_API_V1`)
152+
## CUDA Driver API Capsule (`_CUDA_DRIVER_API_V1`)
164153

165154
**Problem**: cuda.core cannot directly call CUDA driver functions because:
166155

@@ -186,13 +175,6 @@ struct CudaDriverApiV1 {
186175
The C++ code retrieves this capsule once (via `load_driver_api()`) and caches the
187176
function pointers for subsequent use.
188177
189-
### Why Two Capsules?
190-
191-
| Capsule | Direction | Purpose |
192-
|---------|-----------|---------|
193-
| `_CXX_API` | C++ → Cython | Share handle functions across modules |
194-
| `_CUDA_DRIVER_API_V1` | Cython → C++ | Provide resolved driver symbols |
195-
196178
## Key Implementation Details
197179
198180
### Structural Dependencies
@@ -276,14 +258,12 @@ Related functions:
276258
from cuda.core._resource_handles cimport (
277259
StreamHandle,
278260
create_stream_handle,
279-
cu,
280-
intptr,
261+
as_cu,
262+
as_intptr,
263+
as_py,
281264
get_last_error,
282-
_init_handles_table,
283265
)
284266
285-
_init_handles_table() # prerequisite before calling handle API functions
286-
287267
# Create a stream
288268
cdef StreamHandle h_stream = create_stream_handle(h_ctx, flags, priority)
289269
if not h_stream:
@@ -302,10 +282,10 @@ The resource handle design:
302282

303283
1. **Separates resource management** into its own layer, independent of Python objects.
304284
2. **Encodes lifetimes structurally** via embedded handle dependencies.
305-
3. **Uses capsules** to solve two distinct problems:
306-
- Sharing C++ code across Cython modules without duplicate statics.
307-
- Resolving CUDA driver symbols dynamically through cuda-bindings.
308-
4. **Provides overloaded accessors** (`cu`, `intptr`, `py`) since handles cannot
285+
3. **Uses Cython's `cimport` mechanism** to share C++ code across modules without
286+
duplicate static/thread-local state.
287+
4. **Uses a capsule** to resolve CUDA driver symbols dynamically through cuda-bindings.
288+
5. **Provides overloaded accessors** (`as_cu`, `as_intptr`, `as_py`) since handles cannot
309289
have attributes without unnecessary Python object wrappers.
310290

311291
This architecture ensures CUDA resources are managed correctly regardless of Python

‎cuda_core/cuda/core/_cpp/resource_handles.cpp‎

Lines changed: 1 addition & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@
55
#include <Python.h>
66

77
#include "resource_handles.hpp"
8-
#include "resource_handles_cxx_api.hpp"
98
#include <cuda.h>
109
#include <cstdint>
1110
#include <cstring>
@@ -470,7 +469,7 @@ EventHandle create_event_handle(ContextHandle h_ctx, unsigned int flags) {
470469
return EventHandle(box, &box->resource);
471470
}
472471

473-
EventHandle create_event_handle(unsigned int flags) {
472+
EventHandle create_event_handle_noctx(unsigned int flags) {
474473
return create_event_handle(ContextHandle{}, flags);
475474
}
476475

@@ -857,60 +856,4 @@ DevicePtrHandle deviceptr_import_ipc(MemoryPoolHandle h_pool, const void* export
857856
}
858857
}
859858

860-
// ============================================================================
861-
// Capsule C++ API table
862-
// ============================================================================
863-
864-
const ResourceHandlesCxxApiV1* get_resource_handles_cxx_api_v1() noexcept {
865-
static const ResourceHandlesCxxApiV1 table = []() {
866-
ResourceHandlesCxxApiV1 t{};
867-
t.abi_version = RESOURCE_HANDLES_CXX_API_VERSION;
868-
t.struct_size = static_cast<std::uint32_t>(sizeof(ResourceHandlesCxxApiV1));
869-
870-
// Error handling
871-
t.get_last_error = &get_last_error;
872-
t.peek_last_error = &peek_last_error;
873-
t.clear_last_error = &clear_last_error;
874-
875-
// Context
876-
t.create_context_handle_ref = &create_context_handle_ref;
877-
t.get_primary_context = &get_primary_context;
878-
t.get_current_context = &get_current_context;
879-
880-
// Stream
881-
t.create_stream_handle = &create_stream_handle;
882-
t.create_stream_handle_ref = &create_stream_handle_ref;
883-
t.create_stream_handle_with_owner = &create_stream_handle_with_owner;
884-
t.get_legacy_stream = &get_legacy_stream;
885-
t.get_per_thread_stream = &get_per_thread_stream;
886-
887-
// Event (resolve overloads explicitly)
888-
t.create_event_handle =
889-
static_cast<EventHandle (*)(ContextHandle, unsigned int)>(&create_event_handle);
890-
t.create_event_handle_noctx =
891-
static_cast<EventHandle (*)(unsigned int)>(&create_event_handle);
892-
t.create_event_handle_ipc = &create_event_handle_ipc;
893-
894-
// Memory pool
895-
t.create_mempool_handle = &create_mempool_handle;
896-
t.create_mempool_handle_ref = &create_mempool_handle_ref;
897-
t.get_device_mempool = &get_device_mempool;
898-
t.create_mempool_handle_ipc = &create_mempool_handle_ipc;
899-
900-
// Device pointer
901-
t.deviceptr_alloc_from_pool = &deviceptr_alloc_from_pool;
902-
t.deviceptr_alloc_async = &deviceptr_alloc_async;
903-
t.deviceptr_alloc = &deviceptr_alloc;
904-
t.deviceptr_alloc_host = &deviceptr_alloc_host;
905-
t.deviceptr_create_ref = &deviceptr_create_ref;
906-
t.deviceptr_create_with_owner = &deviceptr_create_with_owner;
907-
t.deviceptr_import_ipc = &deviceptr_import_ipc;
908-
t.deallocation_stream = &deallocation_stream;
909-
t.set_deallocation_stream = &set_deallocation_stream;
910-
911-
return t;
912-
}();
913-
return &table;
914-
}
915-
916859
} // namespace cuda_core

‎cuda_core/cuda/core/_cpp/resource_handles.hpp‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ EventHandle create_event_handle(ContextHandle h_ctx, unsigned int flags);
9191
// Use for temporary events that are created and destroyed in the same scope.
9292
// When the last reference is released, cuEventDestroy is called automatically.
9393
// Returns empty handle on error (caller must check).
94-
EventHandle create_event_handle(unsigned int flags);
94+
EventHandle create_event_handle_noctx(unsigned int flags);
9595

9696
// Create an owning event handle from an IPC handle.
9797
// The originating process owns the event and its context.

‎cuda_core/cuda/core/_cpp/resource_handles_cxx_api.hpp‎

Lines changed: 0 additions & 79 deletions
This file was deleted.

‎cuda_core/cuda/core/_device.pyx‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,11 @@ from cuda.core._event cimport Event as cyEvent
1717
from cuda.core._event import Event, EventOptions
1818
from cuda.core._resource_handles cimport (
1919
ContextHandle,
20-
_init_handles_table,
2120
create_context_handle_ref,
2221
get_primary_context,
2322
as_cu,
2423
)
2524

26-
# Prerequisite before calling handle API functions (see _cpp/DESIGN.md)
27-
_init_handles_table()
28-
2925
from cuda.core._graph import GraphBuilder
3026
from cuda.core._stream import IsStreamT, Stream, StreamOptions
3127
from cuda.core._utils.clear_error_support import assert_type

‎cuda_core/cuda/core/_event.pyx‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,17 +11,13 @@ from cuda.core._context cimport Context
1111
from cuda.core._resource_handles cimport (
1212
ContextHandle,
1313
EventHandle,
14-
_init_handles_table,
1514
create_event_handle,
1615
create_event_handle_ipc,
1716
as_intptr,
1817
as_cu,
1918
as_py,
2019
)
2120

22-
# Prerequisite before calling handle API functions (see _cpp/DESIGN.md)
23-
_init_handles_table()
24-
2521
from cuda.core._utils.cuda_utils cimport (
2622
check_or_create_options,
2723
HANDLE_RETURN

‎cuda_core/cuda/core/_memory/_buffer.pyx‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,16 +16,12 @@ from cuda.core._memory cimport _ipc
1616
from cuda.core._resource_handles cimport (
1717
DevicePtrHandle,
1818
StreamHandle,
19-
_init_handles_table,
2019
deviceptr_create_with_owner,
2120
as_intptr,
2221
as_cu,
2322
set_deallocation_stream,
2423
)
2524

26-
# Prerequisite before calling handle API functions (see _cpp/DESIGN.md)
27-
_init_handles_table()
28-
2925
from cuda.core._stream cimport Stream_accept, Stream
3026
from cuda.core._utils.cuda_utils cimport HANDLE_RETURN
3127

‎cuda_core/cuda/core/_memory/_graph_memory_resource.pyx‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,10 @@ from cuda.bindings cimport cydriver
1010
from cuda.core._memory._buffer cimport Buffer, Buffer_from_deviceptr_handle, MemoryResource
1111
from cuda.core._resource_handles cimport (
1212
DevicePtrHandle,
13-
_init_handles_table,
1413
deviceptr_alloc_async,
1514
as_cu,
1615
)
1716

18-
# Prerequisite before calling handle API functions (see _cpp/DESIGN.md)
19-
_init_handles_table()
20-
2117
from cuda.core._stream cimport default_stream, Stream_accept, Stream
2218
from cuda.core._utils.cuda_utils cimport HANDLE_RETURN
2319

‎cuda_core/cuda/core/_memory/_ipc.pyx‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,16 +10,12 @@ from cuda.core._memory._memory_pool cimport _MemPool
1010
from cuda.core._stream cimport Stream
1111
from cuda.core._resource_handles cimport (
1212
DevicePtrHandle,
13-
_init_handles_table,
1413
create_mempool_handle_ipc,
1514
deviceptr_import_ipc,
1615
get_last_error,
1716
as_cu,
1817
)
1918

20-
# Prerequisite before calling handle API functions (see _cpp/DESIGN.md)
21-
_init_handles_table()
22-
2319
from cuda.core._stream cimport default_stream
2420
from cuda.core._utils.cuda_utils cimport HANDLE_RETURN
2521
from cuda.core._utils.cuda_utils import check_multiprocessing_start_method

0 commit comments

Comments
 (0)