diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 823fdc6b2..ff5b1b46b 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -458,6 +458,10 @@ Exports the array for consumption by {ref}`function-from_dlpack` as a DLPack cap For other device types which do have a stream, queue or similar synchronization mechanism, the most appropriate type to use for `stream` is not yet determined. E.g., for SYCL one may want to use an object containing an in-order `cl::sycl::queue`. This is allowed when libraries agree on such a convention, and may be standardized in a future version of this API standard. + ```{note} + Support for a `stream` value other than `None` is optional and implementation-dependent. + ``` + Device-specific notes: :::{admonition} CUDA @@ -1213,9 +1217,9 @@ Element-wise results must equal the results returned by the equivalent element-w ``` (method-to_device)= -### to\_device(self, device, /) +### to\_device(self, device, /, *, stream=None) -Move the array to the given device. +Copy the array from the device on which it currently resides to the specified `device`. #### Parameters @@ -1227,8 +1231,16 @@ Move the array to the given device. - a `device` object (see {ref}`device-support`). +- **stream**: _Optional\[ Union\[ int, Any ]]_ + + - stream object to use during copy. In addition to the types supported in {ref}`method-__dlpack__`, implementations may choose to support any library-specific stream object with the caveat that any code using such an object would not be portable. + #### Returns - **out**: _<array>_ - - an array with the same data and dtype, located on the specified device. + - an array with the same data and data type as `self` and located on the specified `device`. + +```{note} +If `stream` is given, the copy operation should be enqueued on the provided `stream`; otherwise, the copy operation should be enqueued on the default stream/queue. Whether the copy is performed synchronously or asynchronously is implementation-dependent. Accordingly, if synchronization is required to guarantee data safety, this must be clearly explained in a conforming library's documentation. +``` diff --git a/spec/design_topics/device_support.md b/spec/design_topics/device_support.md index 033e0b3a1..454171731 100644 --- a/spec/design_topics/device_support.md +++ b/spec/design_topics/device_support.md @@ -48,13 +48,22 @@ cross-device data transfer: libraries is out of scope). 2. A `device=None` keyword for array creation functions, which takes an instance of a `Device` object. -3. A `.to_device(device)` method on the array object, with `device` again being - a `Device` object, to move an array to a different device. +3. A `.to_device` method on the array object to copy an array to a different device. ```{note} -The only way to obtain a `Device` object is from the `.device` property on -the array object, hence there is no `Device` object in the array API itself -that can be instantiated to point to a specific physical or logical device. +In the current API standard, the only way to obtain a `Device` object is from the +`.device` property on the array object. The standard does **not** include a universal +`Device` object recognized by all compliant libraries. Accordingly, the standard does +not provide a means of instantiating a `Device` object to point to a specific physical or +logical device. + +The choice to not include a standardized `Device` object may be revisited in a future revision of this standard. + +For array libraries which concern themselves with multi-device support, including CPU and GPU, +they are free to expose a library-specific device object (e.g., for creating an +array on a particular device). While a library-specific device object can be used as input to +`to_device`, beware that this will mean non-portability as code will be specific to +that library. ```