@@ -179,6 +179,42 @@ 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+ Producer array frameworks must provide a ``__dlpack_c_exchange_api__ ``
188+ attribute on the array type.
189+ The attribute should be a ``PyCapsule `` with name ``"dlpack_exchange_api" ``.
190+ The consumer can query whether this attribute exists and use it at the C extension level.
191+ Notably, consumer frameworks can always start implementing by only using the Python ``__dlpack__ `` API,
192+ and then upgrade to the C Exchange API later when faster data exchange is needed.
193+
194+ .. code-block :: C
195+
196+ PyObject *api_obj = type(tensor_obj).__dlpack_c_exchange_api__; // as C code.
197+ MyDLPackExchangeAPI *api = PyCapsule_GetPointer(api_obj, "dlpack_exchange_api");
198+ if (api == NULL && PyErr_Occurred()) { goto handle_error; }
199+
200+
201+ .. note :: Implementation of the C Exchange API
202+
203+ Producer framework should implement the C Exchange API in a static way either
204+ through Cython, Python C extensions, or Python binding mechanism. Importantly,
205+ because the DLPack C exchange API operates at the C extension level, we need
206+ direct interaction between the array framework PyObject* and DLPack,
207+ as a result it is harder to implement the C Exchange API through ctypes (because
208+ ctypes releases GIL by default and sometimes in non-free-threading environment,
209+ GIL is needed to interact with the Python C API).
210+
211+ A reference implementations of the C Exchange API in frameworks:
212+
213+
214+ * PyTorch: `C++ <https://github.com/pytorch/pytorch/blob/main/torch/csrc/Module.cpp#L692 >`__
215+ * Paddle: `C++ <https://github.com/PaddlePaddle/Paddle/blob/develop/paddle/fluid/pybind/pybind.cc#L856 >`__
216+
217+
182218Reference Implementations
183219~~~~~~~~~~~~~~~~~~~~~~~~~
184220
@@ -198,3 +234,4 @@ ctypes, cffi, etc:
198234* mpi4py: `Cython <https://github.com/mpi4py/mpi4py/blob/master/src/mpi4py/MPI.src/asdlpack.pxi >`_
199235* 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 >`__
200236* Hidet: `ctypes <https://github.com/hidet-org/hidet/blob/main/python/hidet/graph/impl/dlpack.py >`__
237+
0 commit comments