Skip to content

Address a few device related issues #259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Nov 1, 2021
Merged
Show file tree
Hide file tree
Changes from 9 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions spec/API_specification/array_object.md
Original file line number Diff line number Diff line change
Expand Up @@ -458,6 +458,9 @@ 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
Expand Down Expand Up @@ -1213,9 +1216,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

Expand All @@ -1227,8 +1230,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.
```
19 changes: 14 additions & 5 deletions spec/design_topics/device_support.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
```


Expand Down