__dlpack__

array.__dlpack__(*, stream: int | Any | None = None) → PyCapsule

Exports the array for consumption by from_dlpack() as a DLPack capsule.

Parameters:

  • self (array) – array instance.

  • 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. 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.

Note

Support for a stream value other than None is optional and implementation-dependent.

Device-specific notes:

CUDA

  • None: producer must assume the legacy default stream (default).

  • 1: the legacy default stream.

  • 2: the per-thread default stream.

  • > 2: stream number represented as a Python integer.

  • 0 is disallowed due to its ambiguity: 0 could mean either None, 1, or 2.

ROCm

  • None: producer must assume the legacy default stream (default).

  • 0: the default stream.

  • > 2: stream number represented as a Python integer.

  • Using 1 and 2 is not supported.

Tip

It is recommended that implementers explicitly handle streams. If they use the legacy default stream, specifying 1 (CUDA) or 0 (ROCm) is preferred. None is a safe default for developers who do not want to think about stream handling at all, potentially at the cost of more synchronization than necessary.

Returns:

capsule (PyCapsule) – a DLPack capsule for the array. See Data interchange mechanisms for details.

Raises:

BufferError – Implementations should raise BufferError when the data cannot be exported as DLPack (e.g., incompatible dtype or strides). Other errors are raised when export fails for other reasons (e.g., incorrect arguments passed or out of memory).

Notes

Changed in version 2022.12: Added BufferError.