aclrtCreateEventExWithFlag

Applicable Products

Product	Supported
Ascend 950PR / Ascend 950DT	√
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	√

Function

Creates an event with a flag. Events with different flags provide different functions. When an event is created, multiple flags can be set (bitwise OR operation) to enable the corresponding functions. Event resources are not restricted by hardware for the creation of events.

Prototype

      
           aclError aclrtCreateEventExWithFlag(aclrtEvent *event, uint32_t flag)

Parameters

Parameter	Input/Output	Description
event	Output	Event pointer. For details about the type definition, see aclrtEvent.
flag	Input	Flag of the event pointer. flag is a bitmap. You can set the flag to a single macro or perform the OR operation on multiple macros. Currently, flag can be set to the following macros: ACL_EVENT_TIME_LINE: If this bit is used, the timestamp information needs to be recorded for the created event. Note: Using the timestamp function affects the performance of event-related APIs. ACL_EVENT_SYNC: If this bit is used, the created event supports synchronization between multiple streams. ACL_EVENT_CAPTURE_STREAM_PROGRESS: If this bit is used, the created event is used to trace the task execution progress of the stream. ACL_EVENT_IPC: If this bit is used, the created event is used for inter-process communication. For details, see aclrtIpcGetEventHandle. Note: The Ascend 950DT does not support the use of this flag to create events. This flag cannot be used with other flags in a bitwise OR operation. Events created using this flag cannot be used in the following APIs or scenarios: aclrtResetEvent, aclrtQueryEvent, aclrtQueryEventWaitStatus, aclrtEventElapsedTime, aclrtEventGetTimestamp, aclrtGetEventId, and model capture (see aclmdlRICaptureBegin). Otherwise, an error is reported. The macros are defined as follows: #define ACL_EVENT_TIME_LINE 0x00000008U #define ACL_EVENT_SYNC 0x00000001U #define ACL_EVENT_CAPTURE_STREAM_PROGRESS 0x00000002U #define ACL_EVENT_IPC 0x00000040U

Parameter

Input/Output

Description

event

Output

Event pointer. For details about the type definition, see aclrtEvent.

flag

Input

Flag of the event pointer.

flag is a bitmap. You can set the flag to a single macro or perform the OR operation on multiple macros.

Currently, flag can be set to the following macros:

ACL_EVENT_TIME_LINE: If this bit is used, the timestamp information needs to be recorded for the created event. Note: Using the timestamp function affects the performance of event-related APIs.

ACL_EVENT_SYNC: If this bit is used, the created event supports synchronization between multiple streams.
ACL_EVENT_CAPTURE_STREAM_PROGRESS: If this bit is used, the created event is used to trace the task execution progress of the stream.
ACL_EVENT_IPC: If this bit is used, the created event is used for inter-process communication. For details, see aclrtIpcGetEventHandle. Note: The Ascend 950DT does not support the use of this flag to create events. This flag cannot be used with other flags in a bitwise OR operation. Events created using this flag cannot be used in the following APIs or scenarios: aclrtResetEvent, aclrtQueryEvent, aclrtQueryEventWaitStatus, aclrtEventElapsedTime, aclrtEventGetTimestamp, aclrtGetEventId, and model capture (see aclmdlRICaptureBegin). Otherwise, an error is reported.

The macros are defined as follows:

#define ACL_EVENT_TIME_LINE 0x00000008U
#define ACL_EVENT_SYNC 0x00000001U
#define ACL_EVENT_CAPTURE_STREAM_PROGRESS 0x00000002U
#define ACL_EVENT_IPC 0x00000040U

Returns

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

Restrictions

Events created using this API cannot be used in the following APIs: aclrtResetEvent, aclrtQueryEvent, and aclrtQueryEventWaitStatus. Otherwise, an error is reported.
If the value of flag does not contain ACL_EVENT_SYNC, events created by this API cannot be used in the aclrtStreamWaitEvent API. If the value of flag contains the ACL_EVENT_SYNC macro, event resources are not actually allocated. Resources are allocated only when aclrtRecordEvent is called. Therefore, calling aclrtRecordEvent may cause the thread to block while waiting for event resources to be released.

The number of events supported varies depending on the hardware model.
- For the following product models, a maximum of 65,536 events are supported by a single device is:
  Ascend 950PR / Ascend 950DT
  
  Atlas A3 training products / Atlas A3 inference products
  
  Atlas A2 training products / Atlas A2 inference products
  
  Atlas 200I/500 A2 inference products
- For the Atlas inference products , a maximum of 1,023 events are supported by a single device.
- For the Atlas training products , a maximum of 65,535 events are supported by a single device.

API Call Example

For the API call example, see Event Creation and Destruction.

Parent topic: Event Management