Skip to content

Commit 20b6c22

Browse files
committed
[DOCS] Update the exchange api spec
1 parent 5eeaaae commit 20b6c22

1 file changed

Lines changed: 34 additions & 0 deletions

File tree

docs/source/python_spec.rst

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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+
182215
Reference 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

Comments
 (0)