aclrtLaunchCallback

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

Delivers a host callback task in the task queue of a stream. When the callback task is executed in the system, the callback function is also executed in the thread subscribed in the stream (the thread is user-created and subscribed by calling aclrtSubscribeReport). This API is asynchronous.

This API must be work with the following APIs to implement the callback function in asynchronous scenarios:

Define and implement a callback function. Function prototype: typedef void (*aclrtCallback)(void *userData)
Create a thread. Call aclrtProcessReport in the thread function to set the timeout interval (cyclic calling is required), and wait for the callback task to be executed.
Call aclrtSubscribeReport to bind the thread created in Step 2 to the stream. The callback function delivered by the stream is executed in the bound thread.
Execute an asynchronous task (for example, an asynchronous inference job) on the specified stream.
Call aclrtLaunchCallback to deliver a callback task in the task queue of the stream and trigger the thread created in step 2 to process the callback function. Each time aclrtLaunchCallback is called, the callback function is executed.
After all asynchronous tasks are executed, call aclrtUnSubscribeReport to unsubscribe from the thread.

This API implements callback in the asynchronous scenario. The difference between this API and aclrtLaunchHostFunc is that when aclrtLaunchHostFunc is used, the callback function is executed in the thread subscribed in the stream (the thread is created and subscribed within this API). By default, the callback task blocks the execution of subsequent tasks in the stream.

For the same stream, these two APIs cannot be used together to implement callback in the asynchronous scenario. Otherwise, an exception may occur.

Prototype

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

Parameters

Parameter	Input/Output	Description
fn	Input	Callback function. Prototype: *typedef void (aclrtCallback)(void userData)*
userData	Input	Pointer to the user specified data to be passed to the callback function.
blockType	Input	Whether the callback task blocks subsequent tasks in the stream. typedef enum aclrtCallbackBlockType { ACL_CALLBACK_NO_BLOCK, // Not blocked. ACL_CALLBACK_BLOCK, // Blocked. } aclrtCallbackBlockType;
stream	Input	Stream.

Returns

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

Restrictions

Callback functions involve shared resources (such as locks). Exercise caution when using callback functions. Do not call APIs for resource application, resource release, stream synchronization, device synchronization, task delivery, and task termination. Otherwise, errors or deadlocks may occur.