• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Passing a Task with the Specified Priority to an ArkTS Thread from an Asynchronous Thread Using Node-API
2You can use **napi_call_threadsafe_function_with_priority** to pass a task to an ArkTS thread from an asynchronous thread in a thread-safe manner. Then, the task will be processed based on its priority and enqueuing mode.
3
4## Function Description
5
6```cpp
7napi_status napi_call_threadsafe_function_with_priority(napi_threadsafe_function func, void *data,
8                                                        napi_task_priority priority, bool isTail);
9```
10
11| Name           | Description         |
12| :------------- | :----------------------------- |
13| func           | Thread-safe function to call.                  |
14| data           | Data to be passed from the asynchronous thread to the main thread. |
15| priority       | Priority of the task. For details, see [napi_task_priority](napi-data-types-interfaces.md#thread-safe-task-priority).|
16| isTail         | Whether to add the task to the end (tail) of the task queue. The value **true** means to add the task to the end of the task queue; the value **false** means to add the task to the head of the queue.|
17
18## When to Use
19Pass a task to the ArkTS main thread from an asynchronous thread in a thread-safe manner. Then, the task will be processed based on its priority and enqueuing mode.
20
21## Calling an ArkTS API Asynchronously
22
23### Example
24
25- Register the module.
26
27   ```c++
28    // napi_init.cpp
29    #include "napi/native_api.h"
30    #include <string.h>
31    #include <stdlib.h>
32
33    static constexpr int INT_NUM_2 = 2;     // Integer 2
34    static constexpr int INT_NUM_12 = 12;   // Integer 12
35    static constexpr int INT_NUM_15 = 15;   // Integer 15
36
37    struct CallbackData {
38        napi_threadsafe_function tsfn;
39        napi_async_work work;
40    };
41    // Callback implementation in the ArkTS thread.
42    static void CallJs(napi_env env, napi_value jsCb, void *context, void *data) {
43        if (env == nullptr) {
44            return;
45        }
46        napi_value resultNumber = nullptr;
47        napi_value undefined = nullptr;
48        napi_get_undefined(env, &undefined);
49        napi_value number1 = nullptr;
50        napi_create_int32(env, INT_NUM_12, &number1);
51        napi_value number2 = nullptr;
52        napi_create_int32(env, INT_NUM_15, &number2);
53        napi_value argv[2] = {number1, number2};
54        napi_call_function(env, undefined, jsCb, INT_NUM_2, argv, &resultNumber);
55        int32_t res = 0;
56        napi_get_value_int32(env, resultNumber, &res);
57    }
58
59    // Call this API in an asynchronous thread to pass a task with the specified priority and enqueuing mode to an ArkTS thread.
60    static void ExecuteWork(napi_env env, void *data) {
61        CallbackData *callbackData = reinterpret_cast<CallbackData *>(data);
62        // The task priority is napi_priority_idle, and the task is added to the end of the task queue.
63        napi_call_threadsafe_function_with_priority(callbackData->tsfn, nullptr, napi_priority_idle, true);
64        napi_call_threadsafe_function_with_priority(callbackData->tsfn, nullptr, napi_priority_low, true);
65        napi_call_threadsafe_function_with_priority(callbackData->tsfn, nullptr, napi_priority_high, true);
66        napi_call_threadsafe_function_with_priority(callbackData->tsfn, nullptr, napi_priority_immediate, true);
67        // The task priority is napi_priority_high, and the task is added to the head of the task queue.
68        napi_call_threadsafe_function_with_priority(callbackData->tsfn, nullptr, napi_priority_high, false);
69    }
70
71    static void WorkComplete(napi_env env, napi_status status, void *data) {
72        CallbackData *callbackData = reinterpret_cast<CallbackData *>(data);
73        napi_release_threadsafe_function(callbackData->tsfn, napi_tsfn_release);
74        napi_delete_async_work(env, callbackData->work);
75        callbackData->work = nullptr;
76        callbackData->tsfn = nullptr;
77    }
78
79    static napi_value CallThreadSafeWithPriority(napi_env env, napi_callback_info info) {
80        size_t argc = 1;
81        napi_value jsCb = nullptr;
82        CallbackData *callbackData = nullptr;
83        napi_get_cb_info(env, info, &argc, &jsCb, nullptr, reinterpret_cast<void **>(&callbackData));
84        napi_value resourceName = nullptr;
85        napi_create_string_utf8(env, "Thread-safe Function Demo", NAPI_AUTO_LENGTH, &resourceName);
86        napi_create_threadsafe_function(env, jsCb, nullptr, resourceName, 0, 1, callbackData, nullptr, callbackData, CallJs,
87                                        &callbackData->tsfn);
88        napi_create_async_work(env, nullptr, resourceName, ExecuteWork, WorkComplete, callbackData, &callbackData->work);
89        napi_queue_async_work(env, callbackData->work);
90        return nullptr;
91    }
92
93    // Register the module.
94    EXTERN_C_START
95    static napi_value Init(napi_env env, napi_value exports)
96    {
97        CallbackData *callbackData = new CallbackData();
98        napi_property_descriptor desc[] = {
99            { "callThreadSafeWithPriority", nullptr, CallThreadSafeWithPriority, nullptr, nullptr, nullptr, napi_default, callbackData }
100        };
101        napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
102        return exports;
103    }
104    EXTERN_C_END
105
106    static napi_module nativeModule = {
107        .nm_version = 1,
108        .nm_flags = 0,
109        .nm_filename = nullptr,
110        .nm_register_func = Init,
111        .nm_modname = "entry",
112        .nm_priv = nullptr,
113        .reserved = { 0 },
114    };
115
116    extern "C" __attribute__((constructor)) void RegisterEntryModule()
117    {
118        napi_module_register(&nativeModule);
119    }
120   ```
121
122- Declare the API.
123
124    ```ts
125    // index.d.ts
126    export const callThreadSafeWithPriority: (cb: (a: number, b: number) => number) => void;
127    ```
128
129- Configure compile settings.
130
131  Configure the **CMakeLists.txt** file as follows:
132
133    ```
134    // CMakeLists.txt
135    # the minimum version of CMake.
136    cmake_minimum_required(VERSION 3.4.1)
137    project(myapplication)
138
139    set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})
140
141    if(DEFINED PACKAGE_FIND_FILE)
142        include(${PACKAGE_FIND_FILE})
143    endif()
144
145    include_directories(${NATIVERENDER_ROOT_PATH}
146                        ${NATIVERENDER_ROOT_PATH}/include)
147    add_library(entry SHARED hello.cpp)
148    target_link_libraries(entry PUBLIC libace_napi.z.so)
149    ```
150
151- ArkTS sample code
152
153    ```ts
154    // index.ets
155    import testNapi from 'libentry.so';
156
157    let callback = (a: number, b: number) : number => {
158        console.info('result is ' + (a + b));
159        return a + b;
160    }
161    testNapi.callThreadSafeWithPriority(callback);
162    ```
163