aclrtCreateStreamWithConfig

Applicability

Product	Supported
Atlas 350 Accelerator Card	√
Atlas A3 training product / Atlas A3 inference product	√
Atlas A2 training product / Atlas A2 inference product	√
Atlas 200I/500 A2 inference product	√
Atlas inference product	√
Atlas training product	√

Description

Creates a stream in the current process or thread.

For the following product models, compared with aclrtCreateStream, this API can create a stream that features fast task launching. However, it consumes more memory or CPU resources.
Atlas 350 Accelerator Card

Atlas A3 training product / Atlas A3 inference product

Atlas A2 training product / Atlas A2 inference product

Atlas inference product

Atlas training product
For the following product model, this API functions equivalently to aclrtCreateStream.
Atlas 200I/500 A2 inference product

Prototype

      
           aclError aclrtCreateStreamWithConfig(aclrtStream *stream, uint32_t priority, uint32_t flag)

Parameters

Parameter	Input/Output	Description
stream	Output	Stream pointer. For details about the type definition, see aclrtStream.
priority	Input	Priority. For the Atlas inference product , the value range of this parameter is [0, 7]. A maximum of eight priorities are supported. A smaller value indicates a higher priority. The value 0 indicates the highest priority and the value 7 indicates the lowest priority. If the specified value is out of the value range, it is changed to the nearest boundary value. For the following products, this parameter is reserved and is not used currently. The value is fixed to 0. Atlas 350 Accelerator Card Atlas A3 training product / Atlas A3 inference product Atlas A2 training product / Atlas A2 inference product Atlas 200I/500 A2 inference product Atlas training product
flag	Input	Flag of the stream pointer. For details about the value of the flag parameter, see "flag Values."

Parameter

Input/Output

Description

stream

Output

Stream pointer. For details about the type definition, see aclrtStream.

priority

Input

Priority.

For the Atlas inference product , the value range of this parameter is [0, 7]. A maximum of eight priorities are supported. A smaller value indicates a higher priority. The value 0 indicates the highest priority and the value 7 indicates the lowest priority. If the specified value is out of the value range, it is changed to the nearest boundary value.

For the following products, this parameter is reserved and is not used currently. The value is fixed to 0.

Atlas 350 Accelerator Card
Atlas A3 training product / Atlas A3 inference product
Atlas A2 training product / Atlas A2 inference product
Atlas 200I/500 A2 inference product
Atlas training product

flag

Input

Flag of the stream pointer.

For details about the value of the flag parameter, see "flag Values."

flag Values

flag can be set to the macros below. Set one or combine multiple using the bitwise OR operator (|), for example, ACL_STREAM_FAST_LAUNCH | ACL_STREAM_FAST_SYNC. If a macro that does not support bitwise OR is specified, the API returns an error. Setting this parameter to other values creates the same stream as calling aclrtCreateStream.

ACL_STREAM_FAST_LAUNCH: creates a stream that features fast task launching.
In ACL_STREAM_FAST_LAUNCH mode, the internal system resources are pre-allocated when the stream is created. Therefore, the stream creation duration is prolonged but the task launching duration is shortened. If a stream is created once and used for multiple times, the total duration will be shortened. However, pre-allocation for internal resources during stream creation increases memory consumption. By contrast, if you create a stream by calling aclrtCreateStream, the internal system resources are allocated only when the stream is used. As a result, the task launching duration is prolonged.
```
#define ACL_STREAM_FAST_LAUNCH      0x00000001U
```
ACL_STREAM_FAST_SYNC: creates a stream that blocks the current thread and queries the task execution status to return a result upon task completion after you call aclrtSynchronizeStream.
In ACL_STREAM_FAST_SYNC mode, the total duration is shortened. However, the query operation increases the CPU performance consumption. By contrast, if you create a stream by calling aclrtCreateStream, after you call aclrtSynchronizeStream, the stream waits for the notification indicating that the task execution on the device is complete, which is time-consuming.
```
#define ACL_STREAM_FAST_SYNC        0x00000002U
```
ACL_STREAM_PERSISTENT: creates a stream where tasks are not executed right away or deleted immediately after execution. Resources for these tasks are destroyed only when the stream itself is destroyed. The stream created in this mode is bound to a model and applies to model building scenarios. For details about the APIs related to model building, see aclmdlRIBindStream.
```
#define ACL_STREAM_PERSISTENT       0x00000004U
```
ACL_STREAM_HUGE: creates a stream that can hold more tasks than streams created with other flags.
In the current version, this flag does not take effect.
```
#define ACL_STREAM_HUGE             0x00000008U
```
ACL_STREAM_CPU_SCHEDULE: creates a stream that carries AI CPU scheduling tasks in queue-based model inference scenarios. This flag is reserved.
```
#define ACL_STREAM_CPU_SCHEDULE     0x00000010U
```
ACL_STREAM_DEVICE_USE_ONLY: creates a stream that can be invoked exclusively on the device.
```
#define ACL_STREAM_DEVICE_USE_ONLY  0x00000020U
```
ACL_STREAM_DEVICE_USE_ONLY is supported only by the following models:

Atlas 350 Accelerator Card

Atlas A3 training product / Atlas A3 inference product

Atlas A2 training product / Atlas A2 inference product

Atlas inference product

Returns

0 on success; otherwise, failure. For details, see aclError.

API Call Example

For the API call example, see Stream Priority Configuration.

Parent topic: Stream Management