Skip to content

Improve documentation for stream argument to __dlpack__ #185

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.

Sign up for GitHub

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 2 commits into from
May 26, 2021
Merged

Improve documentation for stream argument to __dlpack__ #185

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8ab050f
Improve documentation for `stream` argument to `__dlpack__`
rgommers May 24, 2021
818b3b7
Update type specification for stream keyword to `__dlpack__`
rgommers May 25, 2021
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
8 changes: 7 additions & 1 deletion spec/API_specification/array_object.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -434,7 +434,13 @@ Exports the array for consumption by {ref}`function-from_dlpack` as a DLPack cap

- **stream**: _Optional\[ int ]_
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **stream**: _Optional\[ int ]_
- **stream**: _Any_

You could also go for Optional[Union[int, Any]] or Union[int, None, Any], but in the end all these statements are equivalent.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Bas, I missed updating that. From a typing point of view they're indeed all the same. From a "this serves as documentation as well" point of view, I think I prefer Optional[Union[int, Any]].


- a Python integer representing a pointer to a stream. `stream` is provided by the consumer to the producer to instruct the producer to ensure that operations can safely be performed on the array. The pointer must be a positive integer or `-1`. If `stream` is `-1`, the value may be used by the consumer to signal "producer must not perform any synchronization". Device-specific notes:
- for CUDA and ROCm, a Python integer representing a pointer to a stream, on devices that support streams. `stream` is provided by the consumer to the producer to instruct the producer to ensure that operations can safely be performed on the array (e.g., by inserting a dependency between streams via "wait for event"). The pointer must be a positive integer or `-1`. If `stream` is `-1`, the value may be used by the consumer to signal "producer must not perform any synchronization". The ownership of the stream stays with the consumer.

On CPU and other device types without streams, only `None` is accepted.

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.

Device-specific notes:

:::{admonition} CUDA
- `None`: producer must assume the legacy default stream (default).
Expand Down