jorisvandenbossche commented on code in PR #40708: URL: https://github.com/apache/arrow/pull/40708#discussion_r1539568653
########## 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 +should raise an error when trying to export non-CPU data). Review Comment: On the other hand, for a CPU-only consumer that only checks the `__arrow_c_array__` version, it would be good this that this consumer can be ensured the pointers it is going to interpret are valid for CPU memory? How can this consumer otherwise avoid segfaults if getting passed a non-CPU object? -- 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]
