Skip to content

Commit e3927fd

Browse files
authored
Improve documentation for stream argument to __dlpack__ (#185)
Closes gh-183 (SYCL related, don't require an integer for `stream`) The need to document the ownership of `stream` came up in pytorch/pytorch#57781.
1 parent 2472846 commit e3927fd

File tree

1 file changed

+8
-2
lines changed

1 file changed

+8
-2
lines changed

spec/API_specification/array_object.md

+8-2
Original file line numberDiff line numberDiff line change
@@ -432,9 +432,15 @@ Exports the array for consumption by {ref}`function-from_dlpack` as a DLPack cap
432432

433433
- array instance.
434434

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

437-
- 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:
437+
- 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.
438+
439+
On CPU and other device types without streams, only `None` is accepted.
440+
441+
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.
442+
443+
Device-specific notes:
438444

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

0 commit comments

Comments
 (0)