Skip to content

Commit 8ab050f

Browse files
committed
Improve documentation for stream argument to __dlpack__
Closes data-apisgh-183 The need to document the ownership of `stream` came up in pytorch/pytorch#57781.
1 parent 0429693 commit 8ab050f

File tree

1 file changed

+7
-1
lines changed

1 file changed

+7
-1
lines changed

spec/API_specification/array_object.md

+7-1
Original file line numberDiff line numberDiff line change
@@ -434,7 +434,13 @@ Exports the array for consumption by {ref}`function-from_dlpack` as a DLPack cap
434434

435435
- **stream**: _Optional\[ int ]_
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)