DLPackExchangeAPI Struct Reference

Framework-specific function pointers table for DLPack exchange. More...

#include <DLPack.h>

Data Fields
DLPackExchangeAPIHeader	header
	The header that remains stable across versions. More...
DLPackManagedTensorAllocator	managed_tensor_allocator
	Producer function pointer for DLPackManagedTensorAllocator This function must not be NULL. More...
DLPackManagedTensorFromPyObjectNoSync	managed_tensor_from_py_object_no_sync
	Producer function pointer for DLPackManagedTensorFromPyObject This function must be not NULL. More...
DLPackManagedTensorToPyObjectNoSync	managed_tensor_to_py_object_no_sync
	Producer function pointer for DLPackManagedTensorToPyObject This function must be not NULL. More...
DLPackDLTensorFromPyObjectNoSync	dltensor_from_py_object_no_sync
	Producer function pointer for DLPackDLTensorFromPyObject This function can be NULL when the producer does not support this function. More...
DLPackCurrentWorkStream	current_work_stream
	Producer function pointer for DLPackCurrentWorkStream This function must be not NULL. More...

Detailed Description

Framework-specific function pointers table for DLPack exchange.

Additionally to __dlpack__() we define a C function table sharable by Python implementations via __c_dlpack_exchange_api__. This attribute must be set on the type as a Python integer compatible with PyLong_FromVoidPtr/PyLong_AsVoidPtr.

A consumer library may use a pattern such as:

PyObject *api_obj = type(tensor_obj).__c_dlpack_exchange_api__;  // as C-code
MyDLPackExchangeAPI *api = PyLong_AsVoidPtr(api_obj);
if (api == NULL && PyErr_Occurred()) { goto handle_error; }

Note that this must be defined on the type. The consumer should look up the attribute on the type and may cache the result for each unique type.

The precise API table is given by:

struct MyDLPackExchangeAPI : public DLPackExchangeAPI {
  MyDLPackExchangeAPI() {
    header.version.major = DLPACK_MAJOR_VERSION;
    header.version.minor = DLPACK_MINOR_VERSION;
    header.prev_version_api = nullptr;
 
    managed_tensor_allocator = MyDLPackManagedTensorAllocator;
    managed_tensor_from_py_object_no_sync =
MyDLPackManagedTensorFromPyObjectNoSync; managed_tensor_to_py_object_no_sync
= MyDLPackManagedTensorToPyObjectNoSync; dltensor_from_py_object_no_sync =
MyDLPackDLTensorFromPyObjectNoSync; current_work_stream =
MyDLPackCurrentWorkStream;
 }
 
 static const DLPackExchangeAPI* Global() {
    static MyDLPackExchangeAPI inst;
    return &inst;
 }
};

Guidelines for leveraging DLPackExchangeAPI:

There are generally two kinds of consumer needs for DLPack exchange:

• N0: library support, where consumer.kernel(x, y, z) would like to run a kernel with the data from x, y, z. The consumer is also expected to run the kernel with the same stream context as the producer. For example, when x, y, z is torch.Tensor, consumer should query exchange_api->current_work_stream to get the current stream and launch the kernel with the same stream. This setup is necessary for no synchronization in kernel launch and maximum compatibility with CUDA graph capture in the producer. This is the desirable behavior for library extension support for frameworks like PyTorch.
• N1: data ingestion and retention

Note that obj.__dlpack__() API should provide useful ways for N1. The primary focus of the current DLPackExchangeAPI is to enable faster exchange N0 with the support of the function pointer current_work_stream.

Array/Tensor libraries should statically create and initialize this structure then return a pointer to DLPackExchangeAPI as an int value in Tensor/Array. The DLPackExchangeAPI* must stay alive throughout the lifetime of the process.

One simple way to do so is to create a static instance of DLPackExchangeAPI within the framework and return a pointer to it. The following code shows an example to do so in C++. It should also be reasonably easy to do so in other languages.

Field Documentation

current_work_stream

DLPackCurrentWorkStream DLPackExchangeAPI::current_work_stream

Producer function pointer for DLPackCurrentWorkStream This function must be not NULL.

See also

DLPackCurrentWorkStream

dltensor_from_py_object_no_sync

DLPackDLTensorFromPyObjectNoSync DLPackExchangeAPI::dltensor_from_py_object_no_sync

Producer function pointer for DLPackDLTensorFromPyObject This function can be NULL when the producer does not support this function.

See also

DLPackDLTensorFromPyObjectNoSync

header

DLPackExchangeAPIHeader DLPackExchangeAPI::header

The header that remains stable across versions.

managed_tensor_allocator

DLPackManagedTensorAllocator DLPackExchangeAPI::managed_tensor_allocator

Producer function pointer for DLPackManagedTensorAllocator This function must not be NULL.

See also

DLPackManagedTensorAllocator

managed_tensor_from_py_object_no_sync

DLPackManagedTensorFromPyObjectNoSync DLPackExchangeAPI::managed_tensor_from_py_object_no_sync

Producer function pointer for DLPackManagedTensorFromPyObject This function must be not NULL.

See also

DLPackManagedTensorFromPyObject

managed_tensor_to_py_object_no_sync

DLPackManagedTensorToPyObjectNoSync DLPackExchangeAPI::managed_tensor_to_py_object_no_sync

Producer function pointer for DLPackManagedTensorToPyObject This function must be not NULL.

See also

DLPackManagedTensorToPyObject

---

The documentation for this struct was generated from the following file:

• /root/Open3D/cpp/open3d/core/DLPack.h