Synchronization

aclError aclrtCreateEvent(aclrtEvent *event)

event, ret = acl.rt.create_event()

Creates an event. It is a synchronous interface.

None

event: int, event object pointer.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

None

None

aclError aclrtDestroyEvent(aclrtEvent event)

ret = acl.rt.destroy_event(event)

Destroys an event. Only the events created by calling acl.rt.create_event can be destroyed. It is a synchronous interface.

Before destroying an event, ensure that the tasks involved in acl.rt.synchronize_event or acl.rt.stream_wait_event are complete.

event: int, event pointer to be destroyed.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

Destruction API: The released or destroyed resources are no longer available after this API is called. You are advised to set the released or destroyed resources to invalid values (for example, 0 or None) after calling this API.

When calling the acl.rt.destroy_event API to destroy an event, ensure that the event is not being used by other APIs.

None

aclError aclrtRecordEvent(aclrtEvent event, aclrtStream stream)

ret = acl.rt.record_event(event, stream)

Records an event in a stream. It is a synchronous interface.

event: int, event pointer to be recorded.

stream: int. Record the event in the specified stream. If the default stream is used, set this parameter to 0.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

None

None

aclError aclrtResetEvent(aclrtEvent event, aclrtStream stream)

ret = acl.rt.reset_event(event, stream)

Resets an event. Resets the event only after all tasks in the stream are completely executed. It is a synchronous interface.

event: int, event object pointer to be reset.

stream: int, stream object pointer where the event is located.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

None

None

aclError aclrtQueryEvent(aclrtEvent event, aclrtEventStatus *status)

status, ret = acl.rt.query_event(event)

Queries the status of an event. It is a synchronous interface.

event: int, event object pointer to be queried.

status: int, event status.

• 0: completed
• 1: not completed
• 2: reserved

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

None

None

aclError aclrtSynchronizeEvent(aclrtEvent event)

ret = acl.rt.synchronize_event(event)

Blocks application execution and waits for the event to be complete. It is a synchronous interface.

event: int, event object pointer to be waited for.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

None

None

aclError aclrtEventElapsedTime(float *ms, aclrtEvent start, aclrtEvent end)

ms, ret = acl.rt.event_elapsed_time(start, end)

Collects statistics on the elapsed time between two events. It is a synchronous interface.

start: int, start event object pointer.

end: int, end event object pointer.

ms: float, duration between two events, in milliseconds.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

The API calling sequence is as follows: call acl.rt.create_event to create an event -> call acl.rt.record_event to record the start event and end event in the same stream-> call acl.rt.synchronize_stream to block application execution until all tasks in the specified stream are complete -> call acl.rt.event_elapsed_time to collect statistics on the elapsed time between two events.

None

aclError aclrtStreamWaitEvent(aclrtStream stream, aclrtEvent event)

ret = acl.rt.stream_wait_event(stream, event)

Blocks the execution of a stream until the specified event is complete. It is a synchronous interface. It is allowed for multiple streams to wait for a single event.

acl.rt.record_event and acl.rt.stream_wait_event are used in conjunction for synchronization between streams. When acl.rt.record_event is called, an event resource is allocated. After acl.rt.stream_wait_event is called, acl.rt.reset_event should be called to release the event resource in a timely manner.

Interfaces calling sequence: acl.rt.create_event --> acl.rt.record_event --> acl.rt.stream_wait_event --> acl.rt.reset_event.

stream: int, stream that needs to wait for the event to complete.

Pass 0 if the default stream is used.

event: int, event to be waited for.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

None

None

aclError ret = aclrtSynchronizeDevice();

ret = acl.rt.synchronize_device()

Blocks application execution until the ongoing computation on the device is complete. It is a synchronous interface.

In the multi-device scenario, device of the current context is waited.

None

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

Concurrent calls to synchronize_device in multithreaded processes is not allowed.

None

aclError aclrtSynchronizeStream(aclrtStream stream)

ret = acl.rt.synchronize_stream(stream)

Block application execution until all tasks in a specified stream are complete. It is a synchronous interface.

event: int, stream object pointer that needs to complete all tasks.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

None

None

aclError ret = aclrtSubscribeReport(thread_id, stream);

ret = acl.rt.subscribe_report(thread_id, stream)

Specifies the thread that processes the callback function in the stream. It is a synchronous interface.

thread_id: int, thread ID.

stream: int, stream object pointer to be processed.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

• acl.rt.subscribe_report can be called for multiple times to register the same thread for processing the callback function in multiple streams of the same device.

• To ensure that tasks in a stream can be executed in order, acl.rt.subscribe_reportcannot be called to register multiple threads for processing more than one callback function in the same stream.

• If the number of threads registered by this call in a single process exceeds 128, a failure code is returned.

• Considering the thread switching performance overhead of the operating system, try to keep the number of threads registered by this call within 32.

• It is not allowed to pass the same thread ID for registering different callback functions on different devices in the same process.

None

aclError ret = aclrtLaunchCallback(aclrtCallback fn, void *userData, aclrtCallbackBlockType blockType, aclrtStream stream)

ret = acl.rt.launch_callback(fn, user_data_list, block_type, stream)

Adds a callback function executed on the host or device to the stream task queue. It is an asynchronous interface.

fn: function, callback function on the Python side.

user_data_list: parameters to be transferred to the callback function. Currently, data of the list type is transferred.

stream: int, stream.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

None

None

aclError ret = aclrtProcessReport(timeout);

ret = acl.rt.process_report(timeout)

Triggers callback handling after a specified period. (Thread specified by acl.rt.subscribe_report handles the callback.) It is a synchronous interface.

A thread needs to be created to call acl.rt.process_report in the thread function.

timeout: int, timeout interval, in milliseconds. The value can be as follows:

• –1: infinite waiting
• Values greater than 0 (excluding 0): waiting period

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

This function needs to be called in the callback function.

None

aclError ret = aclrtUnSubscribeReport(thread_id, stream);

ret = acl.rt.unsubscribe_report(thread_id, stream)

Unsubscribes a thread and specifies a callback function in a stream to not be handled by a specified thread. It is a synchronous interface.

thread_id: int, thread ID.

stream: int, stream object pointer to be processed.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

None

None

aclError ret = aclrtSetExceptionInfoCallback(aclrtExceptionInfoCallback callback)

ret = acl.rt.set_exception_info_callback(fn)

Sets the exception callback function. When an exception occurs during task execution on the device, the system transfers an aclExceptionInfo structure pointer that contains the task ID, stream ID, and thread ID to the exception callback function and executes the callback function.

fn: function, callback function on the Python side.

ret: int, error code.

• 0 indicates success.
• Other values indicate failure.

None

None

uint32_t streamId = aclrtGetTaskIdFromExceptionInfo(const aclrtExceptionInfo *info)

task_id = acl.rt.get_task_id_from_exception_info(info)

Obtains the current task ID from the pointer of the aclExceptionInfo structure.

info: int, pointer object of the aclrtExceptionInfo structure.

task_id: int, ID of the current task.

None

None

uint32_t streamId = aclrtGetStreamIdFromExceptionInfo(const aclrtExceptionInfo *info)

stream_id = acl.rt.get_stream_id_from_exception_info(info)

Obtains the current stream ID from the pointer of the aclExceptionInfo structure.

info: int, pointer object of the aclrtExceptionInfo structure.

stream_id: int, ID of the current stream.

None

None

uint32_t streamId = aclrtGetThreadIdFromExceptionInfo(const aclrtExceptionInfo *info)

thread_id = acl.rt.get_thread_id_from_exception_info(info)

Obtains the current thread ID from the pointer of the aclExceptionInfo structure.

info: int, pointer object of the aclrtExceptionInfo structure.

thread_id: int, ID of the current thread.

None

None