@@ -101,25 +101,20 @@ return as_py(h_stream) # cuda.bindings.driver.CUstream
101101```
102102cuda/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
113112The ` _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 {
186175The C++ code retrieves this capsule once (via `load_driver_api()`) and caches the
187176function 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:
276258from 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
288268cdef StreamHandle h_stream = create_stream_handle(h_ctx, flags, priority)
289269if not h_stream:
@@ -302,10 +282,10 @@ The resource handle design:
302282
3032831 . ** Separates resource management** into its own layer, independent of Python objects.
3042842 . ** 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
311291This architecture ensures CUDA resources are managed correctly regardless of Python
0 commit comments