Struct DLPackExchangeAPI 

#[repr(C)]
pub struct DLPackExchangeAPI {
    pub header: DLPackExchangeAPIHeader,
    pub managed_tensor_allocator: DLPackManagedTensorAllocator,
    pub managed_tensor_from_py_object_no_sync: DLPackManagedTensorFromPyObjectNoSync,
    pub managed_tensor_to_py_object_no_sync: DLPackManagedTensorToPyObjectNoSync,
    pub dltensor_from_py_object_no_sync: DLPackDLTensorFromPyObjectNoSync,
    pub current_work_stream: DLPackCurrentWorkStream,
}

\brief 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:

\code

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; }

\endcode

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: \code 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; } }; \endcode

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.

Fields

header: DLPackExchangeAPIHeader

\brief The header that remains stable across versions.

managed_tensor_allocator: DLPackManagedTensorAllocator

\brief Producer function pointer for DLPackManagedTensorAllocator This function must not be NULL. \sa DLPackManagedTensorAllocator

managed_tensor_from_py_object_no_sync: DLPackManagedTensorFromPyObjectNoSync

\brief Producer function pointer for DLPackManagedTensorFromPyObject This function must be not NULL. \sa DLPackManagedTensorFromPyObject

managed_tensor_to_py_object_no_sync: DLPackManagedTensorToPyObjectNoSync

\brief Producer function pointer for DLPackManagedTensorToPyObject This function must be not NULL. \sa DLPackManagedTensorToPyObject

dltensor_from_py_object_no_sync: DLPackDLTensorFromPyObjectNoSync

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

current_work_stream: DLPackCurrentWorkStream

\brief Producer function pointer for DLPackCurrentWorkStream This function must be not NULL. \sa DLPackCurrentWorkStream

Trait Implementations

impl Clone for DLPackExchangeAPI

fn clone(&self) -> DLPackExchangeAPI

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for DLPackExchangeAPI

impl Debug for DLPackExchangeAPI

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.