From 8ab050f5763ba80f33d46df7e01371e91d545e71 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Mon, 24 May 2021 19:47:55 +0200 Subject: [PATCH 1/2] Improve documentation for `stream` argument to `__dlpack__` Closes gh-183 The need to document the ownership of `stream` came up in https://github.com/pytorch/pytorch/pull/57781. --- spec/API_specification/array_object.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index b44ad2dbb..4f96cc25d 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -434,7 +434,13 @@ Exports the array for consumption by {ref}`function-from_dlpack` as a DLPack cap - **stream**: _Optional\[ int ]_ - - 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). From 818b3b71c719c4ea6e7e9dfa600338ef278bc3a6 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Tue, 25 May 2021 13:45:58 +0200 Subject: [PATCH 2/2] Update type specification for stream keyword to `__dlpack__` --- spec/API_specification/array_object.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 4f96cc25d..0f2c3deca 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -432,7 +432,7 @@ Exports the array for consumption by {ref}`function-from_dlpack` as a DLPack cap - array instance. -- **stream**: _Optional\[ int ]_ +- **stream**: _Optional\[ Union\[ int, Any ]]_ - 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.