Address device related issues (#259)

* add to_device

* clarify device object

* clarify library-specific stream can be used

* move -> copy

* apply review comments

* Apply suggestions from code review

Co-authored-by: Athan <[email protected]>

* Update copy

* Add linebreak.

Co-authored-by: Athan <[email protected]>

Author: leofang

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.
+```

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.
 ```