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 6 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: 13 additions & 4 deletions spec/API_specification/array_object.md
Original file line number Diff line number Diff line change
Expand Up @@ -1213,9 +1213,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 it currently resides to the specified `device`.

#### Parameters

Expand All @@ -1225,10 +1225,19 @@ Move the array to the given device.

- **device**: _<device>_

- a `device` object (see {ref}`device-support`).
- a `device` object (see {ref}`device-support`)

- **stream**: _Optional\[ Union\[ int, Any ]]_

- stream object to use during copy. In addition to the supported types as discussed in {ref}`method-__dlpack__`, any library-specific stream object is also allowed to be used here.

#### Returns

- **out**: _<array>_

- an array with the same data and dtype, located on the specified device.
- an array with the same data and dtype, located on the specified `device`.

```{note}

If `stream` is given, the copy operation will be enqueued on it; otherwise, it is enqueued on the default stream/queue (the concept of which is out of scope of this standard). Whether the copy is performed synchronously or asynchronously is up to the array library. As a result, if any synchronization (which is also out of scope of this standard) is required to guarantee data safety, the library should explain to its users.
```
17 changes: 12 additions & 5 deletions spec/design_topics/device_support.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,13 +48,20 @@ 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, with `device` again being
a `Device` 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, 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 other words, the standard does *not* include a universal
`Device` object recognized by all compliant libraries.

For array libraries that concern with multi-device support, including CPU and GPU,
it is free to expose a library-specific device object for use (ex: creating an
array on a particular device). For the purpose of this standard, it is considered
an (important) implementation detail.
```


Expand Down