jorisvandenbossche commented on code in PR #40708: URL: https://github.com/apache/arrow/pull/40708#discussion_r1539576312
########## docs/source/format/CDataInterface/PyCapsuleInterface.rst: ########## @@ -185,6 +230,34 @@ raise an exception. The requested schema mechanism is only meant to negotiate between different representations of the same data and not to allow arbitrary schema transformations. +Device Support +-------------- + +Th PyCapsule interface has cross hardware support through using the +:ref:`C device interface <c-device-data-interface>`. This means it is possible +to exchange data on non-CPU devices (e.g. CUDA GPUs) and to inspect on what +device the exchanged data lives. + +For exchanging the data structures, this interface has two sets of protocol +methods: the standard CPU-only versions (:meth:`__arrow_c_array__` and +:meth:`__arrow_c_stream__`) and the equivalent device-aware versions +(:meth:`__arrow_c_device_array__```, and :meth:`__arrow_c_device_stream__`). + +For CPU-only libraries, it is allowed to either implement only the standard +protocol methods, or either implement both the standard and device-aware +methods. The absence of the device version methods implies CPU-only data. For +CPU-only consumers, it is encouraged to be able to consume both versions of the +protocol. + +For a device-aware library, and for data structures that can only reside in +non-CPU memory, it is recommeded to _only_ implement the device version of the +protocol (e.g. only add ``__arrow_c_device_array__``, and not add ``__arrow_c_array__``). +Libraries that have data structures that can live both on CPU or non-CPU devices +can implement both versions of the protocol (in that case, the standard methods Review Comment: Yes, I did "define" the standard methods as the CPU only ones in the second paragraph listing the two sets of methods, in the idea to not have to constantly repeat CPU-only (eg also the paragraph just above (the third paragraph) uses that terminology). But maybe that's not helping, and I can certainly also just consistently use "CPU-only" and "device-aware" to refer to the different versions of the methods. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
