reduce the applicability of __cuda_stream__

Author: leofang

cuda_core/cuda/core/experimental/_stream.py

@@ -47,8 +47,8 @@ class StreamOptions:
 class IsStreamT(Protocol):
     def __cuda_stream__(self) -> Tuple[int, int]:
         """
-        For any Python objects that are meant to be interpreted as a CUDA stream, they
-        can do so by implementing this protocol that returns a 2-tuple: The protocol
+        For any Python object that is meant to be interpreted as a CUDA stream, the intent
+        can be communicated by implementing this protocol that returns a 2-tuple: The protocol
         version number (currently ``0``) and the address of ``cudaStream_t``. Both values
         should be Python `int`.
         """

cuda_core/docs/source/interoperability.rst

@@ -34,10 +34,10 @@ in Python. While we encourage new Python projects to start using streams (and ot
 CUDA types) from ``cuda.core``, we understand that there are already several projects
 exposing their own stream types.
 
-To address this issue, we propose the :attr:`~_stream.IsStreamT.__cuda_stream__` protocol (currently version
-0) as follows: For any Python objects that are meant to be interpreted as a stream, they
-should add a ``__cuda_stream__`` method that returns a 2-tuple: The version number
-(``0``) and the address of ``cudaStream_t`` (both as Python `int`):
+To address this issue, we propose the :attr:`~_stream.IsStreamT.__cuda_stream__` protocol
+(currently version 0) as follows: For any Python objects that are meant to be interpreted
+as a stream, they should add a ``__cuda_stream__`` *method* that returns a 2-tuple: The
+version number (``0``) and the address of ``cudaStream_t`` (both as Python `int`):
 
 .. code-block:: python
 
@@ -48,12 +48,11 @@ should add a ``__cuda_stream__`` method that returns a 2-tuple: The version numb
 
        ...
 
-Then such objects can be understood by ``cuda.core`` anywhere a stream-like object
-is needed.
+Then such objects can be understood and wrapped by :meth:`Device.create_stream`.
 
-We suggest all existing Python projects that expose a stream class to also support this
-protocol wherever a function takes a stream. For new Python projects that need to access
-CUDA streams, we encourage you to use :class:`~_stream.Stream` directly.
+We suggest all existing Python projects that already expose a stream class to also support
+this protocol. For new Python projects that need to access CUDA streams, we encourage you
+to use :class:`~_stream.Stream` from ``cuda.core`` directly.
 
 
 Memory view utilities for CPU/GPU buffers

cuda_core/examples/pytorch_example.py

@@ -40,7 +40,7 @@ def __cuda_stream__(self):
         return (0, stream_id)  # Return format required by CUDA Python
 
 
-s = PyTorchStreamWrapper(pt_stream)
+s = dev.create_stream(PyTorchStreamWrapper(pt_stream))
 
 # prepare program
 arch = "".join(f"{i}" for i in dev.compute_capability)

cuda_core/examples/simple_multi_gpu_example.py

@@ -87,7 +87,7 @@ def __cuda_stream__(self):
 a = cp.random.random(size, dtype=dtype)
 b = cp.random.random(size, dtype=dtype)
 c = cp.empty_like(a)
-cp_stream0 = StreamAdaptor(cp.cuda.get_current_stream())
+cp_stream0 = dev0.create_stream(StreamAdaptor(cp.cuda.get_current_stream()))
 
 # Establish a stream order to ensure that memory has been initialized before
 # accessed by the kernel.
@@ -102,7 +102,7 @@ def __cuda_stream__(self):
 x = cp.random.random(size, dtype=dtype)
 y = cp.random.random(size, dtype=dtype)
 z = cp.empty_like(a)
-cp_stream1 = StreamAdaptor(cp.cuda.get_current_stream())
+cp_stream1 = dev1.create_stream(StreamAdaptor(cp.cuda.get_current_stream()))
 
 # Establish a stream order
 stream1.wait(cp_stream1)