Stream Management¶

hipStreamCreate¶

hipError_t hipStreamCreate(hipStream_t *stream)¶

Create an asynchronous stream.

Create a new asynchronous stream.

stream returns an opaque handle that can be used to reference the newly created stream in subsequent hipStream* commands. The stream is allocated on the heap and will remain allocated even if the handle goes out-of-scope. To release the memory used by the stream, applicaiton must call hipStreamDestroy.

Return

#hipSuccess, #hipErrorInvalidValue

Parameters

[inout] stream: Valid pointer to hipStream_t. This function writes the memory with the newly created stream.

Return: #hipSuccess, #hipErrorInvalidValue
See: hipStreamCreateWithFlags, hipStreamCreateWithPriority, hipStreamSynchronize, hipStreamWaitEvent, hipStreamDestroy

hipStreamCreateWithFlags¶

hipError_t hipStreamCreateWithFlags(hipStream_t *stream, unsigned int flags)¶

Create an asynchronous stream.

Create a new asynchronous stream.

stream returns an opaque handle that can be used to reference the newly created stream in subsequent hipStream* commands. The stream is allocated on the heap and will remain allocated even if the handle goes out-of-scope. To release the memory used by the stream, applicaiton must call hipStreamDestroy. Flags controls behavior of the stream. See hipStreamDefault, hipStreamNonBlocking.

Return

#hipSuccess, #hipErrorInvalidValue

Parameters

[inout] stream: Pointer to new stream
[in] flags: to control stream creation.

See: hipStreamCreate, hipStreamCreateWithPriority, hipStreamSynchronize, hipStreamWaitEvent, hipStreamDestroy

hipStreamCreateWithPriority¶

hipError_t hipStreamCreateWithPriority(hipStream_t *stream, unsigned int flags, int priority)¶

Create an asynchronous stream with the specified priority.

Create a new asynchronous stream with the specified priority.

stream returns an opaque handle that can be used to reference the newly created stream in subsequent hipStream* commands. The stream is allocated on the heap and will remain allocated even if the handle goes out-of-scope. To release the memory used by the stream, applicaiton must call hipStreamDestroy. Flags controls behavior of the stream. See hipStreamDefault, hipStreamNonBlocking.

Return

#hipSuccess, #hipErrorInvalidValue

Parameters

[inout] stream: Pointer to new stream
[in] flags: to control stream creation.
[in] priority: of the stream. Lower numbers represent higher priorities.

See: hipStreamCreate, hipStreamSynchronize, hipStreamWaitEvent, hipStreamDestroy

hipDeviceGetStreamPriorityRange¶

hipError_t hipDeviceGetStreamPriorityRange(int *leastPriority, int *greatestPriority)¶

Returns numerical values that correspond to the least and greatest stream priority.

Returns in *leastPriority and *greatestPriority the numerical values that correspond to the least and greatest stream priority respectively. Stream priorities follow a convention where lower numbers imply greater priorities. The range of meaningful stream priorities is given by [*greatestPriority, *leastPriority]. If the user attempts to create a stream with a priority value that is outside the the meaningful range as specified by this API, the priority is automatically clamped to within the valid range.

Parameters

[inout] leastPriority: pointer in which value corresponding to least priority is returned.
[inout] greatestPriority: pointer in which value corresponding to greatest priority is returned.

hipStreamDestroy¶

hipError_t hipStreamDestroy(hipStream_t stream)¶

Destroys the specified stream.

Return

#hipSuccess #hipErrorInvalidResourceHandle

Parameters

[inout] stream: Valid pointer to hipStream_t. This function writes the memory with the newly created stream.

If commands are still executing on the specified stream, some may complete execution before the queue is deleted.

The queue may be destroyed while some commands are still inflight, or may wait for all commands queued to the stream before destroying it.

See: hipStreamCreate, hipStreamCreateWithFlags, hipStreamCreateWithPriority, hipStreamQuery, hipStreamWaitEvent, hipStreamSynchronize

hipStreamQuery¶

hipError_t hipStreamQuery(hipStream_t stream)¶

Return #hipSuccess if all of the operations in the specified stream have completed, or #hipErrorNotReady if not.

This is thread-safe and returns a snapshot of the current state of the queue. However, if other host threads are sending work to the stream, the status may change immediately after the function is called. It is typically used for debug.

Return

#hipSuccess, #hipErrorNotReady, #hipErrorInvalidResourceHandle

Parameters

[in] stream: stream to query

See: hipStreamCreate, hipStreamCreateWithFlags, hipStreamCreateWithPriority, hipStreamWaitEvent, hipStreamSynchronize, hipStreamDestroy

hipStreamSynchronize¶

hipError_t hipStreamSynchronize(hipStream_t stream)¶

Wait for all commands in stream to complete.

This command is host-synchronous : the host will block until the specified stream is empty.

Return

#hipSuccess, #hipErrorInvalidResourceHandle

Parameters

[in] stream: stream identifier.

This command follows standard null-stream semantics. Specifically, specifying the null stream will cause the command to wait for other streams on the same device to complete all pending operations.

This command honors the hipDeviceLaunchBlocking flag, which controls whether the wait is active or blocking.

See: hipStreamCreate, hipStreamCreateWithFlags, hipStreamCreateWithPriority, hipStreamWaitEvent, hipStreamDestroy

hipStreamWaitEvent¶

hipError_t hipStreamWaitEvent(hipStream_t stream, hipEvent_t event, unsigned int flags)¶

Make the specified compute stream wait for an event.

This function inserts a wait operation into the specified stream. All future work submitted to

stream will wait until event reports completion before beginning execution.

Return

#hipSuccess, #hipErrorInvalidResourceHandle

Parameters

[in] stream: stream to make wait.
[in] event: event to wait on
[in] flags: control operation [must be 0]

This function only waits for commands in the current stream to complete. Notably,, this function does not impliciy wait for commands in the default stream to complete, even if the specified stream is created with hipStreamNonBlocking = 0.

See: hipStreamCreate, hipStreamCreateWithFlags, hipStreamCreateWithPriority, hipStreamSynchronize, hipStreamDestroy

hipStreamGetFlags¶

hipError_t hipStreamGetFlags(hipStream_t stream, unsigned int *flags)¶

Return flags associated with this stream.

Return flags associated with this stream in *

flags.

Return

#hipSuccess, #hipErrorInvalidValue, #hipErrorInvalidResourceHandle

Return

#hipSuccess #hipErrorInvalidValue #hipErrorInvalidResourceHandle

Parameters

[in] stream: stream to be queried
[inout] flags: Pointer to an unsigned integer in which the stream’s flags are returned

See: hipStreamCreateWithFlags

hipStreamGetPriority¶

hipError_t hipStreamGetPriority(hipStream_t stream, int *priority)¶

Query the priority of a stream.

Query the priority of a stream. The priority is returned in in priority.

Return

#hipSuccess, #hipErrorInvalidValue, #hipErrorInvalidResourceHandle

Return

#hipSuccess #hipErrorInvalidValue #hipErrorInvalidResourceHandle

Parameters

[in] stream: stream to be queried
[inout] priority: Pointer to an unsigned integer in which the stream’s priority is returned

See: hipStreamCreateWithFlags

hipStreamAddCallback¶

hipError_t hipStreamAddCallback(hipStream_t stream, hipStreamCallback_t callback, void *userData, unsigned int flags)¶

Adds a callback to be called on the host after all currently enqueued items in the stream have completed.

For each cudaStreamAddCallback call, a callback will be executed exactly once. The callback will block later work in the stream until it is finished.

Return

#hipSuccess, #hipErrorInvalidResourceHandle, #hipErrorNotSupported

See

hipStreamCreate, hipStreamCreateWithFlags, hipStreamQuery, hipStreamSynchronize, hipStreamWaitEvent, hipStreamDestroy, hipStreamCreateWithPriority

Parameters

[in] stream: - Stream to add callback to
[in] callback: - The function to call once preceding stream operations are complete
[in] userData: - User specified data to be passed to the callback function
[in] flags: - Reserved for future use, must be 0