# Function QnnGraph\_executeAsync

- Defined in [File QnnGraph.h](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnGraph_h.html#file-include-qnn-qnngraph-h)

## Function Documentation

- [Qnn\_ErrorHandle\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/typedef_QnnCommon_8h_1a8e21e7c6a7471103b59098ef81c28570.html#_CPPv417Qnn_ErrorHandle_t) QnnGraph\_executeAsync([Qnn\_GraphHandle\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/typedef_QnnCommon_8h_1aac60af5d8bde388852ae15bd89fbcd3c.html#_CPPv417Qnn_GraphHandle_t) graphHandle, const [Qnn\_Tensor\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/structQnn__Tensor__t.html#_CPPv412Qnn_Tensor_t) \*inputs, uint32\_t numInputs, [Qnn\_Tensor\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/structQnn__Tensor__t.html#_CPPv412Qnn_Tensor_t) \*outputs, uint32\_t numOutputs, [Qnn\_ProfileHandle\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/typedef_QnnCommon_8h_1a3d859a5097d3fe96b8d5bad77bf0afd5.html#_CPPv419Qnn_ProfileHandle_t) profileHandle, [Qnn\_SignalHandle\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/typedef_QnnCommon_8h_1a57c5e514635d2d61c8c396974da8999a.html#_CPPv418Qnn_SignalHandle_t) signalHandle, [Qnn\_NotifyFn\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/typedef_QnnGraph_8h_1a7962dbaaab857587b6b0b15a9d3b87e0.html#_CPPv414Qnn_NotifyFn_t) notifyFn, void \*notifyParam)

    - Asynchronously execute a finalized graph. Graphs will be enqueued for execution in FIFO order. There is no guarantee that graphs will finish execution in the same order they were enqueued. If the the execution queue is full, this function will block until space is available.

- Parameters

    - - **graphHandle** – **[in]** Handle of finalized graph to execute.
- **inputs** – **[in]** Array of input tensors with which to populate graph inputs.
- **numInputs** – **[in]** Number of input tensors.
- **outputs** – **[out]** Array of tensors which the graph will populate with output values.
- **numOutputs** – **[in]** Number of output tensors.
- **profileHandle** – **[in]** The profile handle on which metrics is populated and can be queried. Use NULL handle to disable profile collection. A handle being reused would reset and is populated with values from the enqueued execute call. Profile handle management/reuse across asynchronous calls is client’s responsibility. Behavior is undefined if same profile handle is used by two enqueued execute instances at the same time. This handle must be NULL when a continuous profile handle has been configured via the QNN\_GRAPH\_CONFIG\_OPTION\_PROFILE\_HANDLE option
- **signalHandle** – **[in]** Signal object which may be used to control the execution of this call. NULL indicates execution should proceed as normal. All pending executions in the queue are affected by Signal control. Instance executing when Signal control is issued may not be affected. The signal object, if not NULL, is considered to be in-use for the duration of the call. For timeout signals, the timeout duration applies from the QnnGraph\_executeAsync call until the callback is called. The same Qnn\_GraphHandle\_t can be used for multiple calls to QnnGraph\_executeAsync, however, different Qnn\_SignalHandle\_t must be supplied.
- **notifyFn** – **[in]** Pointer to notification function, called when execution is finished. NULL indicates no notification is requested. *notifyFn* will be called in context of backend owned thread, with priority equal or lower than client’s calling thread. Please note that a failed call to QnnGraph\_executeAsync does not call the notification function.
- **notifyParam** – **[in]** Client-supplied data object which will be passed back via *notifyFn* and can be used to identify asynchronous execution instance. Can be NULL.

- Returns

    - Error code:

- QNN\_SUCCESS: the graph was successfully executed
- QNN\_GRAPH\_ERROR\_INVALID\_HANDLE: *graph* is not a valid handle
- QNN\_GRAPH\_ERROR\_GRAPH\_NOT\_FINALIZED: graph was not finalized
- QNN\_GRAPH\_ERROR\_SUBGRAPH: cannot execute a subgraph
- QNN\_GRAPH\_ERROR\_INVALID\_ARGUMENT:

    - *inputs* or *outputs* is NULL or ill-formed OR
    - *inputs* is NOT NULL and *numInputs* is 0 OR
    - *outputs* is NOT NULL and *numOutputs* is 0 OR
    - *profile* handle is invalid OR
    - continuous graph profiling is enabled and the per-API handle is not NULL.
- QNN\_GRAPH\_ERROR\_INVALID\_TENSOR: one or more tensors in *inputs* or *outputs* is invalid or not recognized by graph
- QNN\_GRAPH\_ERROR\_UNSUPPORTED\_FEATURE: asynchronous graph execution is not supported on this backend or some API feature is not supported yet, e.g. signal, profile, or batch multiplier
- QNN\_GRAPH\_ERROR\_SIGNAL\_IN\_USE: the supplied control signal is already in-use by another call.
- QNN\_GRAPH\_ERROR\_ABORTED: the call is aborted before completion due to user cancellation
- QNN\_GRAPH\_ERROR\_TIMED\_OUT: the call is aborted before completion due to a timeout
- QNN\_GRAPH\_ERROR\_DISABLED: the graph was not enabled when the context was deserialized
- QNN\_GRAPH\_ERROR\_DYNAMIC\_TENSOR\_SHAPE: An error occurred that is related to dynamic tensor shape. For example, a tensor maximum dimension was exceeded.
- QNN\_GRAPH\_ERROR\_TENSOR\_SPARSITY: An error occurred that is related to tensor sparsity. For example, the maximum number of specified elements was exceeded.
- QNN\_GRAPH\_ERROR\_EARLY\_TERMINATION: Graph execution terminated early due to defined op behavior.
- QNN\_GRAPH\_ERROR\_INVALID\_CONTEXT: Graph execution failed due to context already being freed.
- QNN\_COMMON\_ERROR\_SYSTEM\_COMMUNICATION: SSR occurence (successful recovery)
- QNN\_COMMON\_ERROR\_SYSTEM\_COMMUNICATION\_FATAL: SSR occurence (unsuccessful recovery)

Note

Tensors in *inputs* and *outputs* must carry the same ID that was assigned when they were created. Values for all other attributes in [Qnn\_Tensor\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnTypes_h.html#structQnn__Tensor__t) are assumed from the point at which they were registered with a backend at the time of tensor creation, with the following exceptions:

- Tensor data provided by client in structs such as *clientBuf* can be changed between invocations to execute().
- Batch multiple: An *inputs* or *outputs* tensor *dimensions* field, if non-null, should match the values provided at tensor creation, with the following exception. The batch dimension, as determined by the op definition, can be an integer multiple of the respective dimension provided at tensor creation. All *inputs* and *outputs* tensors must have the same batch multiple.
- Dynamic output dimensions: An *outputs* tensor [Qnn\_TensorV1\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnTypes_h.html#structQnn__TensorV1__t) *dimensions* field, if non-null, can vary after graph execution. As determined by the op definition, non-batch dimensions may be less than the respective dimension at tensor creation.
- Dynamic dimensions: If an *inputs* tensor was created with a non-null [Qnn\_TensorV2\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnTypes_h.html#structQnn__TensorV2__t) *isDynamicDimensions* field, the corresponding dynamic dimensions must be provided by the caller. If an *outputs* tensor was created with a non-null [Qnn\_TensorV2\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnTypes_h.html#structQnn__TensorV2__t) *isDynamicDimensions* field, the *dimensions* must be non-null and the output dimensions will be written by the backend. In a scenario where maximum dimensions will be exceeded, the backend will generate an error code indicating loss of data and will fill the tensor with as much data as possible.
- Other fields like *dataType* can also be permitted to change between invocations to [QnnGraph\_execute()](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnGraph_h.html#QnnGraph_8h_1a3ea05f42a9295f9a74a2e3a0cdd64228)/QnnGraph\_executeAsync() for certain ops that perform data type conversions.
- Some backends may be able to execute a graph with no *inputs* provided the graph has no application-writable tensors.
- [QnnGraph\_executeAsync()](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnGraph_h.html#QnnGraph_8h_1a690b74571029dd9f36e38cd902c86784) can only accept tensors of type QNN\_TENSOR\_TYPE\_APP\_READ, QNN\_TENSOR\_TYPE\_APP\_WRITE, QNN\_TENSOR\_TYPE\_APP\_READ\_WRITE, QNN\_TENSOR\_TYPE\_OPTIONAL\_APP\_READ, QNN\_TENSOR\_TYPE\_OPTIONAL\_APP\_WRITE, and QNN\_TENSOR\_TYPE\_OPTIONAL\_APP\_READWRITE. Tensors provided with a different type will result in [QnnGraph\_execute()](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnGraph_h.html#QnnGraph_8h_1a3ea05f42a9295f9a74a2e3a0cdd64228) failure.
- Clients may exclude tensors of type QNN\_TENSOR\_TYPE\_OPTIONAL\_APP\_READ, QNN\_TENSOR\_TYPE\_OPTIONAL\_APP\_WRITE, and QNN\_TENSOR\_TYPE\_OPTIONAL\_APP\_READ from the *inputs* and *outputs* arguments. If a QNN\_TENSOR\_TYPE\_OPTIONAL\_APP\_WRITE tensor is excluded from the *inputs* argument, the value of that tensor will be dictated by the backend defined behavior for that model. QNN\_TENSOR\_TYPE\_OPTIONAL\_APP\_READ tensors may be excluded from the *outputs* argument. In this case a backend will not populate the tensor on the [QnnGraph\_execute()](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnGraph_h.html#QnnGraph_8h_1a3ea05f42a9295f9a74a2e3a0cdd64228) call, and the data of these tensors is null. This is an optional feature. Backends broadcast support for this feature with QNN\_PROPERTY\_TENSOR\_SUPPORT\_OPTIONAL\_APP\_WRITE, QNN\_PROPERTY\_TENSOR\_SUPPORT\_OPTIONAL\_APP\_READ, and QNN\_PROPERTY\_TENSOR\_SUPPORT\_OPTIONAL\_APP\_READWRITE.
- Mixing different tensor versions in the same graph (e.g. [Qnn\_TensorV1\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnTypes_h.html#structQnn__TensorV1__t) and [Qnn\_TensorV2\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnTypes_h.html#structQnn__TensorV2__t)) may result in performance degradation.

Note

If there are simultaneous calls to [QnnGraph\_execute()](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnGraph_h.html#QnnGraph_8h_1a3ea05f42a9295f9a74a2e3a0cdd64228) and [QnnGraph\_executeAsync()](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnGraph_h.html#QnnGraph_8h_1a690b74571029dd9f36e38cd902c86784), the priority for enqueuing or executing is equal. Both functions will add to the same queue, the only difference in behavior is whether the function returns when the execution is enqueued, or when the execution finishes.

Note

Use corresponding API through [QnnInterface\_t](https://docs.qualcomm.com/doc/80-63442-10/topic/api-rst_file_include_QNN_QnnInterface_h.html#structQnnInterface__t).

Last Published: Jun 04, 2026