@@ -179,6 +179,39 @@ refer to `github.com/dmlc/dlpack <https://github.com/dmlc/dlpack>`_.
179179 guaranteed to be in a certain order or not.
180180
181181
182+ DLPack C Exchange API
183+ ~~~~~~~~~~~~~~~~~~~~~
184+
185+ Starting with DLPack 1.3, a new C Exchange API is introduced to enable faster
186+ data exchange than the Python ``__dlpack__ `` API at the C extension level.
187+ The producer array framework will need to provide a ``__dlpack_c_exchange_api__ ``
188+ attribute on the array type.
189+ The type of the attribute should be ``PyCapsule `` with name ``"dlpack_exchange_api" ``.
190+ The consumer can query whether this attribute exists and make use of it at the C-extension level.
191+
192+ .. code-block :: C
193+
194+ PyObject *api_obj = type(tensor_obj).__dlpack_c_exchange_api__; // as C code.
195+ MyDLPackExchangeAPI *api = PyCapsule_GetPointer(api_obj, "dlpack_exchange_api");
196+ if (api == NULL && PyErr_Occurred()) { goto handle_error; }
197+
198+
199+ .. note :: Implementation of the C Exchange API
200+
201+ Producer framework should implement the C Exchange API in a static way either
202+ through Cython, Python C extensions, or Python binding mechanism. Importantly,
203+ because the DLPack C exchange API operates at the C extension level, we need
204+ direct interaction between the array framework PyObject* and DLPack,
205+ as a result it is harder to implement the C Exchange API through ctypes (because
206+ ctypes releases GIL by default and sometimes in non-free-threading environment,
207+ GIL is needed to interact with the Python C API).
208+
209+ A reference implementations of the C Exchange API in frameworks:
210+
211+ * PyTorch: `C++ <https://github.com/pytorch/pytorch/blob/main/torch/csrc/Module.cpp#L692 >`__
212+ * Paddle: `C++ <https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/pybind/pybind.cc#L856 >`__
213+
214+
182215Reference Implementations
183216~~~~~~~~~~~~~~~~~~~~~~~~~
184217
@@ -198,3 +231,4 @@ ctypes, cffi, etc:
198231* mpi4py: `Cython <https://github.com/mpi4py/mpi4py/blob/master/src/mpi4py/MPI.src/asdlpack.pxi >`_
199232* Paddle: `C++ <https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/framework/tensor_util.cc#L901-L951 >`__, `Python wrapper using Python C API <https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/pybind/pybind.cc#L1263-L1280 >`__
200233* Hidet: `ctypes <https://github.com/hidet-org/hidet/blob/main/python/hidet/graph/impl/dlpack.py >`__
234+
0 commit comments