aclrtCreateStreamWithConfig

Applicability

Product	Supported
Atlas A3 training products/Atlas A3 inference products	√
Atlas A2 training products/Atlas A2 inference products	√
Atlas 200I/500 A2 inference products	√
Atlas inference products	√
Atlas training products	√

Description

Creates a stream in the current process or thread.

For the Atlas A3 training products/Atlas A3 inference products, compared with aclrtCreateStream, this API can create a stream that features fast task launching. However, it consumes more memory or CPU resources.

For the Atlas A2 training products/Atlas A2 inference products, compared with aclrtCreateStream, this API can create a stream that features fast task launching. However, it consumes more memory or CPU resources.

For the Atlas 200I/500 A2 inference products, this API functions equivalently to aclrtCreateStream.

For the Atlas inference products, compared with aclrtCreateStream, this API can create a stream that features fast task launching. However, it consumes more memory or CPU resources.

For the Atlas training products, compared with aclrtCreateStream, this API can create a stream that features fast task launching. However, it consumes more memory or CPU resources.

Prototype

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

Parameters

Parameter	Input/Output	Description
stream	Output	Stream pointer.
priority	Input	Priority. For the Atlas Inference Series 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 this parameter is set to a value beyond the value range, an error is returned. For the following products, this parameter is reserved and is not used currently. The value is fixed to 0. Atlas A3 training products/Atlas A3 inference products Atlas A2 training products/Atlas A2 inference products Atlas 200I/500 A2 inference products Atlas training products
flag	Input	Flag of the stream pointer. Currently, the flag can be set to the following macros. 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

Parameter

Input/Output

Description

stream

Output

Stream pointer.

priority

Input

Priority.

For the Atlas Inference Series 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 this parameter is set to a value beyond the value range, an error is returned.

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

Atlas A3 training products/Atlas A3 inference products
Atlas A2 training products/Atlas A2 inference products
Atlas 200I/500 A2 inference products
Atlas training products

flag

Input

Flag of the stream pointer.

Currently, the flag can be set to the following macros. 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
```

Returns

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

Parent topic: Stream Management