Documentation

aclrtLaunchCallback

Description

Delivers a callback task in the task queue of the stream in the asynchronous task scenario. When the callback task is executed in the system, it is also executed in the thread registered on the stream (aclrtSubscribeReport). This API is asynchronous.

This API must be work with the following APIs to implement the callback function in asynchronous scenarios:
  1. Define and implement a callback function. Function prototype: typedef void (*aclrtCallback)(void *userData)
  2. Create a thread. Call aclrtProcessReport in the thread function to set the timeout interval (cyclic calling is required), and wait for the callback task execution.
  3. 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.
  4. Execute an asynchronous task (for example, an asynchronous inference job) on the specified stream.
  5. 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.
  6. After all asynchronous tasks are executed, call aclrtUnSubscribeReport to unsubscribe from the thread.

Restrictions

This API is asynchronous. The API call delivers a task rather than executes a task. After this API is called, you need to call a synchronization API (for example, aclrtSynchronizeStream) to ensure that the task is complete. Otherwise, service exceptions (such as training or inference exception) or unknown situations (such as device link or card disconnection) 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

Specify whether the callback task blocks subsequent tasks in the stream.

typedef enum aclrtCallbackBlockType {
    ACL_CALLBACK_NO_BLOCK,  // Not blocked. For the Atlas 200/300/500 Inference Product, this option is not supported and is reserved.
    ACL_CALLBACK_BLOCK, // Blocked.
} aclrtCallbackBlockType;

stream

Input

Stream.

Returns

The value 0 indicates success, and other values indicate failure. For details, see aclError.

Reference

For details about the API call sequence and sample code, see Asynchronous Model Inference.

Parent topic: Execution Control