Skip to content

Commit 1f18a9e

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

File tree

1 file changed

+37
-0
lines changed

1 file changed

+37
-0
lines changed

docs/source/python_spec.rst

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

Comments
 (0)