HarmonyOS中使用Node-API開發(fā)的典型場景示例
更新時間：2025年09月13日 10:09:09 作者：ChinaDragon10
在Native側(cè)C/C++開發(fā),計算密集型場景,對需要執(zhí)行耗時操作的邏輯,為避免阻塞應(yīng)用側(cè)主線程,確保應(yīng)用程序的性能和響應(yīng)效率,開發(fā)者需要將該部分業(yè)務(wù)邏輯設(shè)計在Native側(cè)進(jìn)行異步執(zhí)行,本文基于ArkTS多線程場景,講解同步、callback、promise異步模型及線程安全開發(fā)的機制與流程
一、引言
在Native側(cè)C/C++開發(fā)場景中，對于計算簡單、應(yīng)用側(cè)主線程需要實時等待結(jié)果的情況下，開發(fā)者往往會采用常見的同步方式開發(fā)業(yè)務(wù)邏輯。然而，在計算密集型場景中，對于需要執(zhí)行耗時操作的邏輯，為了避免阻塞應(yīng)用側(cè)主線程，確保應(yīng)用程序的性能和響應(yīng)效率，開發(fā)者需要將該部分業(yè)務(wù)邏輯設(shè)計在Native側(cè)進(jìn)行異步執(zhí)行。在異步開發(fā)中，開發(fā)者需要將C/C++子線程異步處理的結(jié)果反饋到ArkTS主線程，用以應(yīng)用側(cè)UI界面刷新。以下是基于ArkTS的多線程場景開發(fā)案例，詳細(xì)講解同步開發(fā)、callback異步模型開發(fā)、promise異步模型開發(fā)以及線程安全開發(fā)等典型場景的機制原理和開發(fā)流程。
二、典型開發(fā)場景概述
2.1 使用Node-API進(jìn)行同步任務(wù)開發(fā)
在同步任務(wù)開發(fā)中，ArkTS應(yīng)用側(cè)主線程將阻塞等待Native側(cè)計算結(jié)果，Native側(cè)計算結(jié)果通過方舟引擎反饋給ArkTS應(yīng)用側(cè)。此過程中，Native接口代碼與ArkTS應(yīng)用側(cè)均運行在ArkTS主線程上。例如，應(yīng)用側(cè)需要讀取文件，阻塞等待Native側(cè)文件讀取完成，然后再繼續(xù)運行。類似地，異步模式下，應(yīng)用側(cè)將收到臨時結(jié)果，并繼續(xù)執(zhí)行UI操作。
從上圖可以看出，當(dāng)Native同步任務(wù)接口被調(diào)用時，該接口會完成參數(shù)解析、數(shù)據(jù)類型轉(zhuǎn)換、創(chuàng)建生產(chǎn)者和消費者線程等。在等待生產(chǎn)者和消費者線程執(zhí)行結(jié)束后，將圖片路徑結(jié)果轉(zhuǎn)換為napi_value，由方舟引擎直接反饋到ArkTS應(yīng)用側(cè)。
2.2 使用Node-API進(jìn)行異步任務(wù)開發(fā)
在異步任務(wù)開發(fā)中，應(yīng)用側(cè)在調(diào)用Native接口后，將會收到臨時結(jié)果，并繼續(xù)執(zhí)行UI操作。Native側(cè)將異步執(zhí)行業(yè)務(wù)邏輯，不阻塞應(yīng)用側(cè)。例如，應(yīng)用側(cè)需要讀取文件，異步模式下，應(yīng)用側(cè)將不會等待Native側(cè)文件讀取完成，并繼續(xù)運行。
從上圖可以看出，當(dāng)Native異步任務(wù)接口被調(diào)用時，該接口會完成參數(shù)解析、數(shù)據(jù)類型轉(zhuǎn)換、異步工作項創(chuàng)建、異步任務(wù)壓入調(diào)度隊列以及返回空值（Callback方式）或者Promise對象（Promise方式）等。異步任務(wù)的調(diào)度、執(zhí)行以及反饋計算結(jié)果，均由libuv線程池和EventLoop機制進(jìn)行系統(tǒng)調(diào)度完成。
2.3 使用Node-API進(jìn)行線程安全開發(fā)
在異步多線程場景中，如果需要進(jìn)行耗時的計算或IO操作，或者需要在多個線程之間共享數(shù)據(jù)，可以創(chuàng)建一個線程安全函數(shù)，確保任務(wù)執(zhí)行過程中的線程安全。例如，異步計算：如果需要進(jìn)行耗時的計算或IO操作，可以創(chuàng)建一個線程安全函數(shù)，將計算或IO操作放在另一個線程中執(zhí)行，避免阻塞主線程，提高程序的響應(yīng)速度。數(shù)據(jù)共享：如果多個線程需要訪問同一份數(shù)據(jù)，可以創(chuàng)建一個線程安全函數(shù)，確保數(shù)據(jù)的讀寫操作不會發(fā)生競爭條件或死鎖等問題。
三、開發(fā)案例概述
本文將以一個圖片加載的案例為背景來詳細(xì)講解上述幾種典型場景的開發(fā)步驟和關(guān)鍵API使用方法。在此案例中，用戶將通過UI界面上呈現(xiàn)的按鈕分別選擇對應(yīng)的典型場景接口進(jìn)行圖片加載。
3.1 案例設(shè)計思路
本案例的實現(xiàn)分為ArkTS應(yīng)用側(cè)和Native側(cè)兩個部分，如下圖所示：
ArkTS應(yīng)用側(cè)
提供多種典型場景接口按鈕，以供用戶進(jìn)行場景選擇。分別為同步調(diào)用、callback異步調(diào)用、promise異步調(diào)用、tsf（線程安全函數(shù)）異步調(diào)用以及錯誤圖片。不同的按鈕觸發(fā)后，將會調(diào)用相應(yīng)的Native接口進(jìn)行同步或者異步處理，獲取圖片路徑信息，從而刷新UI界面。其中，錯誤圖片按鈕反饋的是一個錯誤圖片路徑，觸發(fā)后，界面上將會彈出一個錯誤提示彈窗。
Native側(cè)
根據(jù)應(yīng)用側(cè)觸發(fā)的不同場景，將會執(zhí)行不同的接口實現(xiàn)。整個業(yè)務(wù)邏輯分為以下兩個部分：
- Native接口，該部分主要實現(xiàn)Native接口的同步處理或者異步處理邏輯。
- 同步處理，Native接口將直接調(diào)用圖片路徑搜索功能，將應(yīng)用側(cè)傳入的圖片名稱輸入到生產(chǎn)者-消費者模型中，進(jìn)行相應(yīng)圖片路徑獲取，最后反饋到ArkTS應(yīng)用側(cè)。
- 異步處理，Native接口將通過異步工作項或者線程安全函數(shù)進(jìn)行異步任務(wù)創(chuàng)建，將應(yīng)用側(cè)傳入的圖片名稱輸入到上下文數(shù)據(jù)對象中，待后續(xù)異步任務(wù)調(diào)度處理。在異步任務(wù)處理中，同樣調(diào)度生產(chǎn)者-消費者模型進(jìn)行圖片路徑獲取，最后通過線程通信將結(jié)果反饋到ArkTS應(yīng)用側(cè)。
- 生產(chǎn)者-消費者模型，該部分邏輯主要通過C++子線程、信號量以及條件變量等關(guān)鍵特性來實現(xiàn)。
- 生產(chǎn)者線程負(fù)責(zé)根據(jù)圖片名稱搜索目標(biāo)圖片路徑。并且將搜索結(jié)果放入緩沖隊列中。
- 消費者線程負(fù)責(zé)從緩沖隊列中取出目標(biāo)圖片路徑，并通過線程通信的方式將結(jié)果反饋到ArkTS應(yīng)用側(cè)。
案例流程圖
案例效果圖
3.2 生產(chǎn)者-消費者模型實現(xiàn)
1. 模型緩沖隊列ProducerConsumer.h 頭文件
#ifndef MultiThreads_ProducerConsumer_H
#define MultiThreads_ProducerConsumer_H
#include <string>
#include <queue>
#include <mutex>
#include <condition_variable>
using namespace std;
// Principles of the producer-consumer model: Use buffer zones to balance the rate between production and consumption.
// Synchronization relationship 1: When the buffer is full, the producer needs to be blocked and wait. When a product
// pops up the buffer, the producer needs to be woken up for consumption. Synchronization relationship 2: When the
// buffer is empty, the consumer needs to be blocked and waited. When a product enters the buffer, the consumer needs to
// be woken up for consumption.
class ProducerConsumerQueue {
public:
// constructor
ProducerConsumerQueue() {}
ProducerConsumerQueue(int queueSize) : m_maxSize(queueSize) {}
// producer enqueue operation
void PutElement(string element);
// consumer dequeue operation
string TakeElement();
private:
// check whether the buffer queue is full
bool isFull() { return (m_queue.size() == m_maxSize); }
// check whether the buffer queue is empty
bool isEmpty() { return m_queue.empty(); }
private:
queue<string> m_queue{}; // buffer queue
int m_maxSize{}; // buffer queue capacity
mutex m_mutex{}; // the mutex is used to protect data consistency
condition_variable m_notEmpty{}; // condition variable, which is used to indicate whether the buffer queue is empty
condition_variable m_notFull{}; // condition variable, which is used to indicate whether the buffer queue is full
};
#endif // MultiThreads_ProducerConsumer_HProducerConsumer.cpp 源文件
#include "ProducerConsumer.h"
void ProducerConsumerQueue::PutElement(string element) {
unique_lock<mutex> lock(m_mutex); // add mutex
while (isFull()) {
// when the data buffer queue is full, the production is blocked and wakes up after consumer consumption
// m_mutex is automatically released at the same time
m_notFull.wait(lock);
}
// reacquire the lock
// if the queue is not full
// the product is added to the queue and the consumer is notified that the product can be consumed
m_queue.push(element);
m_notEmpty.notify_one();
}
string ProducerConsumerQueue::TakeElement() {
unique_lock<mutex> lock(m_mutex); // add mutex
while (isEmpty()) {
// when the data buffer queue is empty, the consumption is blocked and the producer is woken up after production
// m_mutex is automatically released at the same time
m_notEmpty.wait(lock);
}
// reacquire the lock
// if the queue is not empty, the product is ejected and the producer is notified that it is ready for production
string element = m_queue.front();
m_queue.pop();
m_notFull.notify_one();
return element;
}2. 全局變量及搜索接口定義
定義一個靜態(tài)全局的模型緩沖隊列。由于，每次只處理一張圖片，所以將容量設(shè)定為1。
定義一個靜態(tài)全局的圖片路徑集合，用于后文搜索。
MultiThreads.cpp文件
/*
* Copyright (c) 2024 Huawei Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#include "napi/native_api.h"
#include "ProducerConsumer.h"
#include <vector>
#include <thread>
using namespace std;
// define global thread safe function
static napi_threadsafe_function tsFun = nullptr;
static constexpr int MAX_MSG_QUEUE_SIZE = 0; // indicates that the queue length is not limited
static constexpr int INITIAL_THREAD_COUNT = 1;
// context data provided by users
// data is transferred between the native method (initialization data), ExecuteFunc, and CompleteFunc
struct ContextData {
napi_async_work asyncWork = nullptr; // async work object
napi_deferred deferred = nullptr; // associated object of the delay object promise
napi_ref callbackRef = nullptr; // reference of callback
string args = ""; // parameters from ArkTS --- imageName
string result = ""; // C++ sub-thread calculation result --- imagePath
};
// define the buffer queue and set the capacity to 1
static ProducerConsumerQueue buffQueue(1);
// defines the image path set, which is used for later search
static vector<string> imagePathVec{"sync.png", "callback.png", "promise.png", "tsf.png"};
// check the image paths based on the image name
static bool CheckImagePath(const string &imageName, const string &imagePath) {
// separate character strings by suffix
size_t pos = imagePath.find_first_of('.');
if (pos == string::npos) {
return false;
}
string nameTemp = imagePath.substr(0, pos);
if (nameTemp.empty()) {
return false;
}
// determine whether the image path is the target path based on whether the image names are the same
return (imageName == nameTemp);
}
// search for image paths by image name
static string SearchImagePath(const string &imageName) {
for (const string &imagePath : imagePathVec) {
if (CheckImagePath(imageName, imagePath)) {
return imagePath;
}
}
return string("");
}
static void ProductElement(void *data) {
buffQueue.PutElement(SearchImagePath(static_cast<ContextData *>(data)->args));
}
static void ConsumeElement(void *data) { static_cast<ContextData *>(data)->result = buffQueue.TakeElement(); }
static void ConsumeElementTSF(void *data) {
static_cast<ContextData *>(data)->result = buffQueue.TakeElement();
// bind consumer thread to the thread safe function
(void)napi_acquire_threadsafe_function(tsFun);
// send async task to the JS main thread EventLoop
(void)napi_call_threadsafe_function(tsFun, data, napi_tsfn_blocking);
// release thread reference
(void)napi_release_threadsafe_function(tsFun, napi_tsfn_release);
}
static void DeleteContext(napi_env env, ContextData *contextData) {
// delete callback reference
if (contextData->callbackRef != nullptr) {
(void)napi_delete_reference(env, contextData->callbackRef);
}
// delete async work
if (contextData->asyncWork != nullptr) {
(void)napi_delete_async_work(env, contextData->asyncWork);
}
// release context data
delete contextData;
}
static void ExecuteFunc([[maybe_unused]] napi_env env, void *data) {
// create producer thread
thread producer(ProductElement, data);
// the producer and consumer threads must be synchronized
// otherwise, the complete operation is triggered to communicate with the ArkTS after the executeFunc is complete
// the result is unpredictable
producer.join();
// create consumer thread
thread consumer(ConsumeElement, data);
consumer.join();
}
static void CompleteFuncCallBack(napi_env env, [[maybe_unused]] napi_status status, void *data) {
// parse context data
ContextData *contextData = static_cast<ContextData *>(data);
napi_value callBack = nullptr;
napi_status operStatus = napi_get_reference_value(env, contextData->callbackRef, &callBack);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// define the undefined variable, which is used in napi_call_function
// because no other data is transferred, the variable is defined as undefined
napi_value undefined = nullptr;
operStatus = napi_get_undefined(env, &undefined);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// convert the calculation result of C++ sub-thread to the napi_value type
napi_value callBackArgs = nullptr;
operStatus = napi_create_string_utf8(env, contextData->result.c_str(), contextData->result.length(), &callBackArgs);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// call the JS callback and send the async calculation result on the Native to ArkTS application
napi_value callBackResult = nullptr;
(void)napi_call_function(env, undefined, callBack, 1, &callBackArgs, &callBackResult);
// destroy data and release memory
DeleteContext(env, contextData);
}
static void CompleteFuncPromise(napi_env env, [[maybe_unused]] napi_status status, void *data) {
// parse context data
ContextData *contextData = static_cast<ContextData *>(data);
// convert the calculation result of C++ sub-thread to the napi_value type
napi_value promiseArgs = nullptr;
napi_status operStatus =
napi_create_string_utf8(env, contextData->result.c_str(), contextData->result.length(), &promiseArgs);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// the deferred and promise object are associated. the result is sent to ArkTS application through this interface
operStatus = napi_resolve_deferred(env, contextData->deferred, promiseArgs);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// destroy data and release memory
DeleteContext(env, contextData);
}
static void CallJsFunction(napi_env env, napi_value callBack, [[maybe_unused]] void *context, void *data) {
// parse context data
ContextData *contextData = static_cast<ContextData *>(data);
// define the undefined variable, which is used in napi_call_function
// because no other data is transferred, the variable is defined as undefined
napi_value undefined = nullptr;
napi_status operStatus = napi_get_undefined(env, &undefined);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// convert the calculation result of C++ sub-thread to the napi_value type
napi_value callBackArgs = nullptr;
operStatus = napi_create_string_utf8(env, contextData->result.c_str(), contextData->result.length(), &callBackArgs);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// call the JS callback and send the async calculation result on the Native to ArkTS application
napi_value callBackResult = nullptr;
(void)napi_call_function(env, undefined, callBack, 1, &callBackArgs, &callBackResult);
// destroy data and release memory
DeleteContext(env, contextData);
}
// sync interface
static napi_value GetImagePathSync(napi_env env, napi_callback_info info) {
size_t paraNum = 1;
napi_value paraArray[1] = {nullptr};
// parse parameters
napi_status operStatus = napi_get_cb_info(env, info, ?Num, paraArray, nullptr, nullptr);
if (operStatus != napi_ok) {
return nullptr;
}
napi_valuetype paraDataType = napi_undefined;
operStatus = napi_typeof(env, paraArray[0], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_string)) {
return nullptr;
}
// convert napi_value to char *
constexpr size_t buffSize = 100;
char strBuff[buffSize]{}; // char buffer for imageName string
size_t strLength = 0;
operStatus = napi_get_value_string_utf8(env, paraArray[0], strBuff, buffSize, &strLength);
if ((operStatus != napi_ok) || (strLength == 0)) {
return nullptr;
}
// defines context data. the memory will be released in CompleteFunc
auto contextData = new ContextData;
contextData->args = strBuff;
// create producer thread
thread producer(ProductElement, static_cast<void *>(contextData));
producer.join();
// create consumer thread
thread consumer(ConsumeElement, static_cast<void *>(contextData));
consumer.join();
// convert the result to napi_value and send it to ArkTs application
napi_value result = nullptr;
(void)napi_create_string_utf8(env, contextData->result.c_str(), contextData->result.length(), &result);
// delete context data
DeleteContext(env, contextData);
return result;
}
// callback async interface
static napi_value GetImagePathAsyncCallBack(napi_env env, napi_callback_info info) {
size_t paraNum = 2;
napi_value paraArray[2] = {nullptr};
// parse parameters
napi_status operStatus = napi_get_cb_info(env, info, ?Num, paraArray, nullptr, nullptr);
if (operStatus != napi_ok) {
return nullptr;
}
napi_valuetype paraDataType = napi_undefined;
operStatus = napi_typeof(env, paraArray[0], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_string)) {
return nullptr;
}
operStatus = napi_typeof(env, paraArray[1], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_function)) {
return nullptr;
}
// napi_value convert to char *
constexpr size_t buffSize = 100;
char strBuff[buffSize]{}; // char buffer for imageName string
size_t strLength = 0;
operStatus = napi_get_value_string_utf8(env, paraArray[0], strBuff, buffSize, &strLength);
if ((operStatus != napi_ok) || (strLength == 0)) {
return nullptr;
}
// defines context data. the memory will be released in CompleteFunc
auto contextData = new ContextData;
contextData->args = strBuff;
operStatus = napi_create_reference(env, paraArray[1], 1, &contextData->callbackRef);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// async resource
napi_value asyncName = nullptr;
string asyncStr = "async callback";
operStatus = napi_create_string_utf8(env, asyncStr.c_str(), asyncStr.length(), &asyncName);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// create async work
operStatus = napi_create_async_work(env, nullptr, asyncName, ExecuteFunc, CompleteFuncCallBack,
static_cast<void *>(contextData), &contextData->asyncWork);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// add the async work to the queue and wait for scheduling
operStatus = napi_queue_async_work(env, contextData->asyncWork);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
}
return nullptr;
}
// promise async interface
static napi_value GetImagePathAsyncPromise(napi_env env, napi_callback_info info) {
size_t paraNum = 1;
napi_value paraArray[1] = {nullptr};
// parse parameters
napi_status operStatus = napi_get_cb_info(env, info, ?Num, paraArray, nullptr, nullptr);
if (operStatus != napi_ok) {
return nullptr;
}
napi_valuetype paraDataType = napi_undefined;
operStatus = napi_typeof(env, paraArray[0], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_string)) {
return nullptr;
}
// napi_value convert to char *
constexpr size_t buffSize = 100;
char strBuff[buffSize]{}; // char buffer for imageName string
size_t strLength = 0;
operStatus = napi_get_value_string_utf8(env, paraArray[0], strBuff, buffSize, &strLength);
if ((operStatus != napi_ok) || (strLength == 0)) {
return nullptr;
}
// defines context data. the memory will be released in CompleteFunc
auto contextData = new ContextData;
contextData->args = strBuff;
// async resource
napi_value asyncName = nullptr;
string asyncStr = "async promise";
operStatus = napi_create_string_utf8(env, asyncStr.c_str(), asyncStr.length(), &asyncName);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// create async work
operStatus = napi_create_async_work(env, nullptr, asyncName, ExecuteFunc, CompleteFuncPromise,
static_cast<void *>(contextData), &contextData->asyncWork);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// add the async work to the queue and wait for scheduling
operStatus = napi_queue_async_work(env, contextData->asyncWork);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// create promise object
napi_value promiseObj = nullptr;
operStatus = napi_create_promise(env, &contextData->deferred, &promiseObj);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
return promiseObj;
}
// thread safe function async interface
static napi_value GetImagePathAsyncTSF(napi_env env, napi_callback_info info) {
size_t paraNum = 2;
napi_value paraArray[2] = {nullptr};
// parse parameters
napi_status operStatus = napi_get_cb_info(env, info, ?Num, paraArray, nullptr, nullptr);
if (operStatus != napi_ok) {
return nullptr;
}
napi_valuetype paraDataType = napi_undefined;
operStatus = napi_typeof(env, paraArray[0], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_string)) {
return nullptr;
}
operStatus = napi_typeof(env, paraArray[1], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_function)) {
return nullptr;
}
// napi_value convert to char *
constexpr size_t buffSize = 100;
char strBuff[buffSize]{}; // char buffer for imageName string
size_t strLength = 0;
operStatus = napi_get_value_string_utf8(env, paraArray[0], strBuff, buffSize, &strLength);
if ((operStatus != napi_ok) || (strLength == 0)) {
return nullptr;
}
// async resource
napi_value asyncName = nullptr;
string asyncStr = "async napi_threadsafe_function";
operStatus = napi_create_string_utf8(env, asyncStr.c_str(), asyncStr.length(), &asyncName);
if (operStatus != napi_ok) {
return nullptr;
}
// defines context data. the memory will be released in CompleteFunc
auto contextData = new ContextData;
contextData->args = strBuff;
// create thread safe function
if (tsFun == nullptr) {
operStatus =
napi_create_threadsafe_function(env, paraArray[1], nullptr, asyncName, MAX_MSG_QUEUE_SIZE,
INITIAL_THREAD_COUNT, nullptr, nullptr, nullptr, CallJsFunction, &tsFun);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
}
// create producer thread
thread producer(ProductElement, static_cast<void *>(contextData));
producer.detach(); // must be detached
// create consumer thread
thread consumer(ConsumeElementTSF, static_cast<void *>(contextData));
consumer.detach();
return nullptr;
}
EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports) {
napi_property_descriptor desc[] = {
{"getImagePathSync", nullptr, GetImagePathSync, nullptr, nullptr, nullptr, napi_default, nullptr},
{"getImagePathAsyncCallBack", nullptr, GetImagePathAsyncCallBack, nullptr, nullptr, nullptr, napi_default,
nullptr},
{"getImagePathAsyncPromise", nullptr, GetImagePathAsyncPromise, nullptr, nullptr, nullptr, napi_default,
nullptr},
{"getImagePathAsyncTSF", nullptr, GetImagePathAsyncTSF, nullptr, nullptr, nullptr, napi_default, nullptr}};
napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
return exports;
}
EXTERN_C_END
static napi_module demoModule = {
.nm_version = 1,
.nm_flags = 0,
.nm_filename = nullptr,
.nm_register_func = Init,
.nm_modname = "entry",
.nm_priv = ((void *)0),
.reserved = {0},
};
extern "C" __attribute__((constructor)) void RegisterEntryModule(void) { napi_module_register(&demoModule); }3. 生產(chǎn)者線程執(zhí)行函數(shù)
生產(chǎn)者線程的執(zhí)行功能：通過解析上下文數(shù)據(jù)中的圖片名稱參數(shù)，來搜索相應(yīng)的圖片路徑，并將其置入模型緩沖隊列中。
MultiThreads.cpp文件
static void ProductElement(void *data) {
buffQueue.PutElement(SearchImagePath(static_cast<ContextData *>(data)->args));
}4. 消費者線程執(zhí)行函數(shù)
消費者線程的執(zhí)行功能：通過從模型緩沖隊列中獲取圖片路徑的搜索結(jié)果，并將其置入上下文數(shù)據(jù)中，用以后續(xù)反饋給ArkTS應(yīng)用側(cè)。
MultiThreads.cpp文件
非線程安全函數(shù)消費者執(zhí)行函數(shù)：
static void ConsumeElement(void *data) { static_cast<ContextData *>(data)->result = buffQueue.TakeElement(); }線程安全函數(shù)消費者執(zhí)行函數(shù)：
static void ConsumeElementTSF(void *data) {
static_cast<ContextData *>(data)->result = buffQueue.TakeElement();
// bind consumer thread to the thread safe function
(void)napi_acquire_threadsafe_function(tsFun);
// send async task to the JS main thread EventLoop
(void)napi_call_threadsafe_function(tsFun, data, napi_tsfn_blocking);
// release thread reference
(void)napi_release_threadsafe_function(tsFun, napi_tsfn_release);
}四、使用Node-API進(jìn)行同步任務(wù)開發(fā)
在同步任務(wù)開發(fā)中，ArkTS應(yīng)用側(cè)主線程將阻塞等待Native側(cè)計算結(jié)果，Native側(cè)計算結(jié)果通過方舟引擎反饋給ArkTS應(yīng)用側(cè)。此過程中，Native接口代碼與ArkTS應(yīng)用側(cè)均運行在ArkTS主線程上。為了Native側(cè)業(yè)務(wù)處理具有同步效果，案例中的生產(chǎn)者與消費者線程則采用join()的方式來進(jìn)行同步處理。
同步調(diào)用也支持帶Callback，具體方式由應(yīng)用開發(fā)者決定，通過是否傳遞Callback函數(shù)進(jìn)行區(qū)分。
同步任務(wù)開發(fā)時序交互圖
從上圖中，可以看出，當(dāng)Native同步任務(wù)接口被調(diào)用時，該接口會完成參數(shù)解析、數(shù)據(jù)類型轉(zhuǎn)換、創(chuàng)建生產(chǎn)者和消費者線程等。在等待生產(chǎn)者線程和消費者線程執(zhí)行結(jié)束后，將圖片路徑結(jié)果轉(zhuǎn)換為napi_value，由方舟引擎直接反饋到ArkTS應(yīng)用側(cè)。
4.1 同步任務(wù)開發(fā)步驟
4.1.1 ArkTS應(yīng)用側(cè)開發(fā)
用戶在界面點擊“多線程同步調(diào)用”按鈕，觸發(fā)onClick()回調(diào)。在回調(diào)處理中，將會調(diào)用Native接口進(jìn)行圖片路徑獲取，以刷新UI界面。
Index.ets文件
import testNapi from 'libentry.so';
import Constants from '../../common/constants/CommonConstants';
@Entry
@Component
struct Index {
@State imagePath: string = Constants.INIT_IMAGE_PATH;
imageName: string = '';
build() {
Column() {
...
// button list, prompting the user to click the button to select the target image.
Column() {
...
// multi-threads sync call button
Button($r('app.string.sync_button_title'))
.width(Constants.FULL_PARENT)
.margin($r('app.float.button_common_margin'))
.onClick(() => {
this.imageName = Constants.SYNC_BUTTON_IMAGE;
this.imagePath = Constants.IMAGE_ROOT_PATH + testNapi.getImagePathSync(this.imageName);
})
...
}
...
}
...
}
}4.1.2 Native側(cè)開發(fā)
在同步任務(wù)開發(fā)中，Native側(cè)接口原生代碼仍然運行在ArkTS主線程上。
導(dǎo)出Native接口：將Native接口導(dǎo)出到ArkTS側(cè)，用于支撐ArkTS對象調(diào)用和模塊編譯構(gòu)建。
index.d.ts文件
// export sync interface export const getImagePathSync: (imageName: string) => string;
上下文數(shù)據(jù)結(jié)構(gòu)定義：用于任務(wù)執(zhí)行過程中，上下文數(shù)據(jù)存儲。后文異步任務(wù)開發(fā)和線程安全開發(fā)中實現(xiàn)相同，后續(xù)不再贅述。
MultiThreads.cpp文件
// context data provided by users
// data is transferred between the native method (initialization data), ExecuteFunc, and CompleteFunc
struct ContextData {
napi_async_work asyncWork = nullptr; // async work object
napi_deferred deferred = nullptr; // associated object of the delay object promise
napi_ref callbackRef = nullptr; // reference of callback
string args = ""; // parameters from ArkTS --- imageName
string result = ""; // C++ sub-thread calculation result --- imagePath
};銷毀上下文數(shù)據(jù)：在任務(wù)執(zhí)行結(jié)束或者失敗后，需要銷毀上下文數(shù)據(jù)進(jìn)行內(nèi)存釋放。后文異步任務(wù)開發(fā)和線程安全開發(fā)中實現(xiàn)相同，后續(xù)不再贅述。
MultiThreads.cpp文件
static void DeleteContext(napi_env env, ContextData *contextData) {
// delete callback reference
if (contextData->callbackRef != nullptr) {
(void)napi_delete_reference(env, contextData->callbackRef);
}
// delete async work
if (contextData->asyncWork != nullptr) {
(void)napi_delete_async_work(env, contextData->asyncWork);
}
// release context data
delete contextData;
}Native同步任務(wù)開發(fā)接口：解析ArkTS應(yīng)用側(cè)參數(shù)、數(shù)據(jù)類型轉(zhuǎn)換、創(chuàng)建生產(chǎn)者和消費者線程，并使用join()進(jìn)行同步處理。最后在獲取結(jié)果后，將數(shù)據(jù)轉(zhuǎn)換為napi_value類型，返回給ArkTS應(yīng)用側(cè)。
MultiThreads.cpp文件
// sync interface
static napi_value GetImagePathSync(napi_env env, napi_callback_info info) {
size_t paraNum = 1;
napi_value paraArray[1] = {nullptr};
// parse parameters
napi_status operStatus = napi_get_cb_info(env, info, ?Num, paraArray, nullptr, nullptr);
if (operStatus != napi_ok) {
return nullptr;
}
napi_valuetype paraDataType = napi_undefined;
operStatus = napi_typeof(env, paraArray[0], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_string)) {
return nullptr;
}
// convert napi_value to char *
constexpr size_t buffSize = 100;
char strBuff[buffSize]{}; // char buffer for imageName string
size_t strLength = 0;
operStatus = napi_get_value_string_utf8(env, paraArray[0], strBuff, buffSize, &strLength);
if ((operStatus != napi_ok) || (strLength == 0)) {
return nullptr;
}
// defines context data. the memory will be released in CompleteFunc
auto contextData = new ContextData;
contextData->args = strBuff;
// create producer thread
thread producer(ProductElement, static_cast<void *>(contextData));
producer.join();
// create consumer thread
thread consumer(ConsumeElement, static_cast<void *>(contextData));
consumer.join();
// convert the result to napi_value and send it to ArkTs application
napi_value result = nullptr;
(void)napi_create_string_utf8(env, contextData->result.c_str(), contextData->result.length(), &result);
// delete context data
DeleteContext(env, contextData);
return result;
}五、使用Node-API進(jìn)行異步任務(wù)開發(fā)
5.1 Node-API異步任務(wù)機制概述
Node-API異步任務(wù)開發(fā)主要用于執(zhí)行耗時操作的場景中使用，以避免阻塞主線程，確保應(yīng)用程序的性能和響應(yīng)效率。例如以下場景：
- 文件操作：讀取大型文件或執(zhí)行復(fù)雜的文件操作時，可以使用異步工作項來避免阻塞主線程。
- 網(wǎng)絡(luò)請求：當(dāng)需要進(jìn)行網(wǎng)絡(luò)請求并等待響應(yīng)時，可以使用異步工作項來避免阻塞主線程，從而提高應(yīng)用程序的響應(yīng)性能。
- 數(shù)據(jù)庫操作：當(dāng)需要執(zhí)行復(fù)雜的數(shù)據(jù)庫查詢或?qū)懭氩僮鲿r，可以使用異步工作項來避免阻塞主線程，從而提高應(yīng)用程序的并發(fā)性能。
- 圖形處理：當(dāng)需要對大型圖像進(jìn)行處理或執(zhí)行復(fù)雜的圖像算法時，可以使用異步工作項來避免阻塞主線程，從而提高應(yīng)用程序的實時性能。
異步方式與同步方式的區(qū)別在于，同步方式中所有代碼的處理都在ArkTS主線程中完成，而異步方式中的所有代碼在多線程中完成。Node-API主要是通過創(chuàng)建一個異步工作項來實現(xiàn)異步任務(wù)開發(fā)?？傮w步驟如下：
- 在Native接口函數(shù)中，創(chuàng)建一個異步工作項，并置入libuv調(diào)度隊列中，然后立即返回一個臨時結(jié)果給ArkTS調(diào)用者；
- 通過libuv線程池創(chuàng)建并調(diào)度work子線程完成異步業(yè)務(wù)邏輯的執(zhí)行；
- 通過Callback回調(diào)或者Promise延時對象返回真正的處理結(jié)果，并用于應(yīng)用側(cè)UI刷新。
異步工作項的底層機制是基于libuv異步庫來實現(xiàn)的，具體流程原理如下：
依賴Node-API提供的napi_create_async_work接口創(chuàng)建異步工作項：
NAPI_EXTERN napi_status napi_create_async_work(napi_env env,
napi_value async_resource,
napi_value async_resource_name,
napi_async_execute_callback execute,
napi_async_complete_callback complete,
void* data,
napi_async_work* result);
參數(shù)說明：
[in] env：傳入接口調(diào)用者的環(huán)境，包含方舟引擎等。由框架提供，默認(rèn)情況下直接傳入即可。
[in] async_resource：可選項，關(guān)聯(lián)async_hooks。
[in] async_resource_name：異步資源標(biāo)識符，主要用于async_hooks API暴露斷言診斷信息。
[in] execute：執(zhí)行業(yè)務(wù)邏輯計算函數(shù)，由libuv線程池調(diào)度執(zhí)行。在該函數(shù)中執(zhí)行IO、CPU密集型任務(wù)，不阻塞主線程。
[in] complete：execute回調(diào)函數(shù)執(zhí)行完成或取消后，觸發(fā)執(zhí)行該函數(shù)。此函數(shù)在EventLoop子線程中執(zhí)行。
[in] data：用戶提供的上下文數(shù)據(jù)，用于傳遞數(shù)據(jù)。
[out] result：napi_async_work*指針，用于返回當(dāng)前此處函數(shù)調(diào)用創(chuàng)建的異步工作項。 返回值：返回napi_ok表示轉(zhuǎn)換成功，其他值失敗。Execute回調(diào)
- execute函數(shù)用于執(zhí)行工作項的業(yè)務(wù)邏輯，異步工作項被調(diào)度后，該函數(shù)從上下文數(shù)據(jù)中獲取輸入數(shù)據(jù)，在work子線程中完成業(yè)務(wù)邏輯計算（不阻塞主線程）并將結(jié)果寫入上下文數(shù)據(jù)。
- 因為execute函數(shù)不在ArkTS線程中，所以不允許execute函數(shù)調(diào)用napi的接口。業(yè)務(wù)邏輯的返回值可以返回到complete回調(diào)中處理。
Complete回調(diào)
- 業(yè)務(wù)邏輯處理execute函數(shù)執(zhí)行完成或被取消后，通過事件通知EventLoop執(zhí)行complete函數(shù)，complete函數(shù)從上下文數(shù)據(jù)中獲取結(jié)果，轉(zhuǎn)換為napi_value類型，調(diào)用ArkTS回調(diào)函數(shù)或通過Promise resolve()返回結(jié)果。
- 該函數(shù)運行在ArkTS主線程下，因此可以調(diào)用napi的接口，將execute中的返回值封裝成ArkTS對象返回。
Node-API異步接口實現(xiàn)支持Callback方式和Promise方式，具體使用哪種方式由應(yīng)用開發(fā)者決定，通過是否傳遞callback函數(shù)進(jìn)行區(qū)分。下文將對兩種異步模型作簡要介紹：
Callback異步模型
- 用戶在調(diào)用Native接口的時候，Native接口將異步執(zhí)行任務(wù)，并臨時返回空值給ArkTS應(yīng)用側(cè)。
- 異步任務(wù)執(zhí)行結(jié)果以參數(shù)的形式提供給用戶注冊的ArkTS回調(diào)函數(shù)，并通過napi_call_function將ArkTS回調(diào)函數(shù)進(jìn)行調(diào)用執(zhí)行以反饋結(jié)果到ArkTS應(yīng)用側(cè)。
Promise異步模型
- 用戶在調(diào)用Native接口的時候，Native接口將異步執(zhí)行任務(wù)，并返回一個Promise對象給ArkTS應(yīng)用側(cè)。
- Promise對象提供了API使得異步執(zhí)行可以按照同步的流程表示出來，避免了層層嵌套的回調(diào)引用。
- 異步任務(wù)執(zhí)行結(jié)果以參數(shù)的形式提供給與ArkTS應(yīng)用側(cè)Promise對象關(guān)聯(lián)的deferred對象，并通過napi_resolve_deferred將計算結(jié)果反饋到ArkTS應(yīng)用側(cè)。
5.2 異步任務(wù)開發(fā)時序交互圖
Callback異步開發(fā)時序交互
Promise異步開發(fā)時序交互
從上圖中，可以看出，當(dāng)Native異步任務(wù)接口被調(diào)用時，該接口會完成參數(shù)解析、數(shù)據(jù)類型轉(zhuǎn)換、異步工作項創(chuàng)建、異步任務(wù)壓入調(diào)度隊列以及返回空值（Callback方式）或者Promise對象（Promise方式）等。異步任務(wù)的調(diào)度、執(zhí)行以及反饋計算結(jié)果，均由libuv線程池和EventLoop機制進(jìn)行系統(tǒng)調(diào)度完成。
六、異步任務(wù)開發(fā)步驟
6.1 Callback異步開發(fā)步驟
6.1.1 ArkTS應(yīng)用側(cè)開發(fā)
用戶在界面點擊“多線程callback異步調(diào)用”按鈕，觸發(fā)onClick()回調(diào)。在回調(diào)處理中，將會調(diào)用Native接口進(jìn)行圖片路徑獲取，以刷新UI界面。
Index.ets文件
import testNapi from 'libentry.so';
import Constants from '../../common/constants/CommonConstants';
@Entry
@Component
struct Index {
@State imagePath: string = Constants.INIT_IMAGE_PATH;
imageName: string = '';
build() {
Column() {
...
// button list, prompting the user to click the button to select the target image.
Column() {
...
// multi-threads callback async button
Button($r('app.string.async_callback_button_title'))
.width(Constants.FULL_PARENT)
.margin($r('app.float.button_common_margin'))
.onClick(() => {
this.imageName = Constants.CALLBACK_BUTTON_IMAGE;
testNapi.getImagePathAsyncCallBack(this.imageName, (result: string) => {
this.imagePath = Constants.IMAGE_ROOT_PATH + result;
});
})
...
}
...
}
...
}
}6.1.2 Native側(cè)開發(fā)
導(dǎo)出Native接口： 將Native接口導(dǎo)出到ArkTS側(cè)，用于支撐ArkTS對象調(diào)用和模塊編譯構(gòu)建。
index.d.ts文件
// export async callback interface export const getImagePathAsyncCallBack: (imageName: string, callBack: (result: string) => void) => void;
execute回調(diào)：定義異步工作項的第一個回調(diào)函數(shù)，該函數(shù)在work子線程中執(zhí)行，處理具體的業(yè)務(wù)邏輯。
MultiThreads.cpp文件
static void ExecuteFunc([[maybe_unused]] napi_env env, void *data) {
// create producer thread
thread producer(ProductElement, data);
// the producer and consumer threads must be synchronized
// otherwise, the complete operation is triggered to communicate with the ArkTS after the executeFunc is complete
// the result is unpredictable
producer.join();
// create consumer thread
thread consumer(ConsumeElement, data);
consumer.join();
}complete回調(diào)： 定義異步工作項的第二個回調(diào)函數(shù)，該函數(shù)在ArkTS主線程中執(zhí)行，將結(jié)果傳遞給ArkTS側(cè)。
MultiThreads.cpp文件
static void CompleteFuncCallBack(napi_env env, [[maybe_unused]] napi_status status, void *data) {
// parse context data
ContextData *contextData = static_cast<ContextData *>(data);
napi_value callBack = nullptr;
napi_status operStatus = napi_get_reference_value(env, contextData->callbackRef, &callBack);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// define the undefined variable, which is used in napi_call_function
// because no other data is transferred, the variable is defined as undefined
napi_value undefined = nullptr;
operStatus = napi_get_undefined(env, &undefined);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// convert the calculation result of C++ sub-thread to the napi_value type
napi_value callBackArgs = nullptr;
operStatus = napi_create_string_utf8(env, contextData->result.c_str(),
contextData->result.length(), &callBackArgs);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// call the JS callback and send the async calculation result on the Native to ArkTS application
napi_value callBackResult = nullptr;
(void)napi_call_function(env, undefined, callBack, 1, &callBackArgs, &callBackResult);
// destroy data and release memory
DeleteContext(env, contextData);
}Native異步任務(wù)開發(fā)接口：解析ArkTS應(yīng)用側(cè)參數(shù)，使用napi_create_async_work創(chuàng)建異步工作項，并使用napi_queue_async_work將異步任務(wù)加入隊列，等待調(diào)度執(zhí)行。
MultiThreads.cpp文件
// callback async interface
static napi_value GetImagePathAsyncCallBack(napi_env env, napi_callback_info info) {
size_t paraNum = 2;
napi_value paraArray[2] = {nullptr};
// parse parameters
napi_status operStatus = napi_get_cb_info(env, info, ?Num, paraArray, nullptr, nullptr);
if (operStatus != napi_ok) {
return nullptr;
}
napi_valuetype paraDataType = napi_undefined;
operStatus = napi_typeof(env, paraArray[0], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_string)) {
return nullptr;
}
operStatus = napi_typeof(env, paraArray[1], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_function)) {
return nullptr;
}
// napi_value convert to char *
constexpr size_t buffSize = 100;
char strBuff[buffSize]{}; // char buffer for imageName string
size_t strLength = 0;
operStatus = napi_get_value_string_utf8(env, paraArray[0], strBuff, buffSize, &strLength);
if ((operStatus != napi_ok) || (strLength == 0)) {
return nullptr;
}
// defines context data. the memory will be released in CompleteFunc
auto contextData = new ContextData;
contextData->args = strBuff;
operStatus = napi_create_reference(env, paraArray[1], 1, &contextData->callbackRef);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// async resource
napi_value asyncName = nullptr;
string asyncStr = "async callback";
operStatus = napi_create_string_utf8(env, asyncStr.c_str(), asyncStr.length(), &asyncName);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// create async work
operStatus = napi_create_async_work(env, nullptr, asyncName, ExecuteFunc, CompleteFuncCallBack,
static_cast<void *>(contextData), &contextData->asyncWork);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// add the async work to the queue and wait for scheduling
operStatus = napi_queue_async_work(env, contextData->asyncWork);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
}
return nullptr;
}6.2 Promise異步開發(fā)步驟
6.2.1 ArkTS應(yīng)用側(cè)開發(fā)
用戶在界面點擊“多線程promise異步調(diào)用”按鈕，觸發(fā)onClick()回調(diào)。在回調(diào)處理中，將會調(diào)用Native接口進(jìn)行圖片路徑獲取，以刷新UI界面。
Index.ets文件
import testNapi from 'libentry.so';
import Constants from '../../common/constants/CommonConstants';
@Entry
@Component
struct Index {
@State imagePath: string = Constants.INIT_IMAGE_PATH;
imageName: string = '';
build() {
Column() {
...
// button list, prompting the user to click the button to select the target image.
Column() {
...
// multi-threads promise async button
Button($r('app.string.async_promise_button_title'))
.width(Constants.FULL_PARENT)
.margin($r('app.float.button_common_margin'))
.onClick(() => {
this.imageName = Constants.PROMISE_BUTTON_IMAGE;
let promiseObj = testNapi.getImagePathAsyncPromise(this.imageName);
promiseObj.then((result: string) => {
this.imagePath = Constants.IMAGE_ROOT_PATH + result;
})
})
...
}
...
}
...
}
}6.2.2 Native側(cè)開發(fā)
導(dǎo)出Native接口：將Native接口導(dǎo)出到ArkTS側(cè)，用于支撐ArkTS對象調(diào)用和模塊編譯構(gòu)建。
index.d.ts文件
// export async promise interface export const getImagePathAsyncPromise: (imageName: string) => Promise<string>;
execute回調(diào)：定義異步工作項的第一個回調(diào)函數(shù)，該函數(shù)在work子線程中執(zhí)行，處理具體的業(yè)務(wù)邏輯。
MultiThreads.cpp文件
static void ExecuteFunc([[maybe_unused]] napi_env env, void *data) {
// create producer thread
thread producer(ProductElement, data);
// the producer and consumer threads must be synchronized
// otherwise, the complete operation is triggered to communicate with the ArkTS after the executeFunc is complete
// the result is unpredictable
producer.join();
// create consumer thread
thread consumer(ConsumeElement, data);
consumer.join();
}complete回調(diào)：定義異步工作項的第二個回調(diào)函數(shù)，該函數(shù)在ArkTS主線程中執(zhí)行，將結(jié)果傳遞給ArkTS側(cè)。
MultiThreads.cpp文件
static void CompleteFuncPromise(napi_env env, [[maybe_unused]] napi_status status, void *data) {
// parse context data
ContextData *contextData = static_cast<ContextData *>(data);
// convert the calculation result of C++ sub-thread to the napi_value type
napi_value promiseArgs = nullptr;
napi_status operStatus =
napi_create_string_utf8(env, contextData->result.c_str(), contextData->result.length(), &promiseArgs);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// the deferred and promise object are associated. the result is sent to ArkTS application through this interface
operStatus = napi_resolve_deferred(env, contextData->deferred, promiseArgs);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// destroy data and release memory
DeleteContext(env, contextData);
}Native異步任務(wù)開發(fā)接口：解析ArkTS應(yīng)用側(cè)參數(shù)，使用napi_create_async_work創(chuàng)建異步工作項，并使用napi_queue_async_work將異步任務(wù)加入隊列，等待調(diào)度執(zhí)行。
MultiThreads.cpp文件
// promise async interface
static napi_value GetImagePathAsyncPromise(napi_env env, napi_callback_info info) {
size_t paraNum = 1;
napi_value paraArray[1] = {nullptr};
// parse parameters
napi_status operStatus = napi_get_cb_info(env, info, ?Num, paraArray, nullptr, nullptr);
if (operStatus != napi_ok) {
return nullptr;
}
napi_valuetype paraDataType = napi_undefined;
operStatus = napi_typeof(env, paraArray[0], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_string)) {
return nullptr;
}
// napi_value convert to char *
constexpr size_t buffSize = 100;
char strBuff[buffSize]{}; // char buffer for imageName string
size_t strLength = 0;
operStatus = napi_get_value_string_utf8(env, paraArray[0], strBuff, buffSize, &strLength);
if ((operStatus != napi_ok) || (strLength == 0)) {
return nullptr;
}
// defines context data. the memory will be released in CompleteFunc
auto contextData = new ContextData;
contextData->args = strBuff;
// async resource
napi_value asyncName = nullptr;
string asyncStr = "async promise";
operStatus = napi_create_string_utf8(env, asyncStr.c_str(), asyncStr.length(), &asyncName);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// create async work
operStatus = napi_create_async_work(env, nullptr, asyncName, ExecuteFunc, CompleteFuncPromise,
static_cast<void *>(contextData), &contextData->asyncWork);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// add the async work to the queue and wait for scheduling
operStatus = napi_queue_async_work(env, contextData->asyncWork);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// create promise object
napi_value promiseObj = nullptr;
operStatus = napi_create_promise(env, &contextData->deferred, &promiseObj);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
return promiseObj;
}七、使用Node-API進(jìn)行線程安全開發(fā)
7.1 Node-API線程安全機制概述
Node-API線程安全開發(fā)主要用于異步多線程之間共享和調(diào)用場景中使用，以避免出現(xiàn)競爭條件或死鎖。例如以下場景：
- 異步計算：如果需要進(jìn)行耗時的計算或IO操作，可以創(chuàng)建一個線程安全函數(shù)，將計算或IO操作放在另一個線程中執(zhí)行，避免阻塞主線程，提高程序的響應(yīng)速度。
- 數(shù)據(jù)共享：如果多個線程需要訪問同一份數(shù)據(jù)，可以創(chuàng)建一個線程安全函數(shù)，確保數(shù)據(jù)的讀寫操作不會發(fā)生競爭條件或死鎖等問題。
- 多線程開發(fā)：如果需要進(jìn)行多線程開發(fā)，可以創(chuàng)建一個線程安全函數(shù)，確保多個線程之間的通信和同步操作正確無誤。
Node-API接口只能在ArkTS主線程上進(jìn)行調(diào)用。當(dāng)C++子線程或者work子線程需要調(diào)用ArkTS回調(diào)接口或者Node-API接口時，這些線程是需要與ArkTS主線程進(jìn)行通信才能完成的。Node-API提供了類型napi_threadsafe_function（線程安全函數(shù)）以及創(chuàng)建、銷毀和調(diào)用該類型對象的 API來完成此操作。Node-API主要是通過創(chuàng)建一個線程安全函數(shù)，然后在C++子線程或者work子線程中調(diào)用線程安全函數(shù)來實現(xiàn)線程安全開發(fā)?？傮w步驟如下：
- 在Native接口函數(shù)中，創(chuàng)建一個線程安全函數(shù)對象，并注冊綁定ArkTS回調(diào)接口callback和線程安全回調(diào)函數(shù)call_js_cb，然后立即返回一個臨時結(jié)果給ArkTS調(diào)用者；
- 通過系統(tǒng)調(diào)度C++子線程完成異步業(yè)務(wù)邏輯的執(zhí)行，并在子線程的執(zhí)行函數(shù)中調(diào)用napi_call_threadsafe_function，將call_js_cb拋給EventLoop事件循環(huán)進(jìn)行調(diào)度；
- 通過call_js_cb執(zhí)行，調(diào)用napi_call_function調(diào)用ArkTS回調(diào)接口callback，從而將異步計算結(jié)果反饋到ArkTS應(yīng)用側(cè)，用于應(yīng)用側(cè)UI刷新。
線程安全函數(shù)的底層機制依然是基于libuv異步庫來實現(xiàn)的，其原理流程如下：
線程安全函數(shù)機制中關(guān)鍵的兩個接口napi_create_threadsafe_function()和napi_call_threadsafe_function()參數(shù)列表詳解：
napi_create_threadsafe_function
該接口主要用于創(chuàng)建線程安全對象，在創(chuàng)建的過程中，會注冊異步過程中的關(guān)鍵信息：ArkTS側(cè)回調(diào)接口callback、線程安全回調(diào)函數(shù)call_js_cb等。
NAPI_EXTERN napi_status napi_create_threadsafe_function(napi_env env,
napi_value func,
napi_value async_resource,
napi_value async_resource_name,
size_t max_queue_size,
size_t initial_thread_count,
void* thread_finalize_data,
napi_finalize thread_finalize_cb,
void* context,
napi_threadsafe_function_call_js call_js_cb,
napi_threadsafe_function* result);
參數(shù)說明：
[in] env：傳入接口調(diào)用者的環(huán)境，包含方舟引擎等。由框架提供，默認(rèn)情況下直接傳入即可。
[in] func：ArkTS應(yīng)用側(cè)傳入的回調(diào)接口callback，可為空。當(dāng)該值為nullptr時，下文call_js_cb不能為nullptr。反之，亦然。兩者不可同時為空。
[in] async_resource：關(guān)聯(lián)async_hooks，可為空。
[in] async_resource_name：異步資源標(biāo)識符，主要用于async_hooks API暴露斷言診斷信息。
[in] max_queue_size：緩沖隊列容量，0表示無限制。線程安全函數(shù)實現(xiàn)實質(zhì)為生產(chǎn)者-消費者模型。
[in] initial_thread_count：初始線程，包括將使用此函數(shù)的主線程，可為空。
[in] thread_finalize_data：傳遞給thread_finalize_cb接口的參數(shù)，可為空。
[in] thread_finalize_cb：當(dāng)線程安全函數(shù)結(jié)束釋放時的回調(diào)接口，可為空。
[in] context：附加的上下文數(shù)據(jù)，可為空。
[in] call_js_cb：子線程需要處理的線程安全回調(diào)任務(wù)，類似于異步工作項中的complete回調(diào)。當(dāng)調(diào)用napi_call_threadsafe_function后，被拋到ArkTS主線程EventLoop中，等待調(diào)度執(zhí)行。當(dāng)該值為空時，系統(tǒng)將會調(diào)用默認(rèn)回調(diào)接口。
[out] result：線程安全函數(shù)對象指針。napi_call_threadsafe_function
該接口主要用于子線程中，將需要回到ArkTS主線程處理的任務(wù)拋到EventLoop中，等待調(diào)度執(zhí)行。
線程安全開發(fā)時序交互圖
從上圖中，可以看出，當(dāng)Native線程安全異步接口被調(diào)用時，該接口會完成參數(shù)解析、數(shù)據(jù)類型轉(zhuǎn)換、線程安全創(chuàng)建、在創(chuàng)建過程中的注冊綁定ArkTS回調(diào)處理函數(shù)以及創(chuàng)建生產(chǎn)者和消費者線程等。異步任務(wù)的調(diào)度、執(zhí)行以及反饋計算結(jié)果，均由C++子線程和EventLoop機制進(jìn)行系統(tǒng)調(diào)度完成。
7.2 線程安全開發(fā)步驟
7.2.1 ArkTS應(yīng)用側(cè)開發(fā)
用戶在界面點擊“多線程tsf異步調(diào)用”按鈕，觸發(fā)onClick()回調(diào)。在回調(diào)處理中，將會調(diào)用Native接口進(jìn)行圖片路徑獲取，以刷新UI界面。
Index.ets文件
import testNapi from 'libentry.so';
import Constants from '../../common/constants/CommonConstants';
@Entry
@Component
struct Index {
@State imagePath: string = Constants.INIT_IMAGE_PATH;
imageName: string = '';
build() {
Column() {
...
// button list, prompting the user to click the button to select the target image.
Column() {
...
// multi-threads tsf async button
Button($r('app.string.async_tsf_button_title'))
.width(Constants.FULL_PARENT)
.margin($r('app.float.button_common_margin'))
.onClick(() => {
this.imageName = Constants.TSF_BUTTON_IMAGE;
testNapi.getImagePathAsyncTSF(this.imageName, (result: string) => {
this.imagePath = Constants.IMAGE_ROOT_PATH + result;
});
})
...
}
...
}
...
}
}7.2.2 Native側(cè)開發(fā)
導(dǎo)出Native接口：將Native接口導(dǎo)出到ArkTS側(cè)，用于支撐ArkTS對象調(diào)用和模塊編譯構(gòu)建。
index.d.ts文件
// export thread safe function interface export const getImagePathAsyncTSF: (imageName: string, callBack: (result: string) => void) => void;
全局變量定義：定義線程安全函數(shù)對象、隊列容量、初始化線程數(shù)。
MultiThreads.cpp文件
// define global thread safe function static napi_threadsafe_function tsFun = nullptr; static constexpr int MAX_MSG_QUEUE_SIZE = 0; // indicates that the queue length is not limited static constexpr int INITIAL_THREAD_COUNT = 1;
call_js_cb回調(diào)處理定義：定義消費者子線程中，通過napi_call_threadsafe_function拋到ArkTS主線程EventLoop中的回調(diào)處理函數(shù)。在該函數(shù)中，通過napi_call_function調(diào)用ArkTS應(yīng)用側(cè)傳入的回調(diào)callback，將異步任務(wù)搜索到的圖片路徑結(jié)果反饋到ArkTS應(yīng)用側(cè)。
MultiThreads.cpp文件
static void CallJsFunction(napi_env env, napi_value callBack, [[maybe_unused]] void *context, void *data) {
// parse context data
ContextData *contextData = static_cast<ContextData *>(data);
// define the undefined variable, which is used in napi_call_function
// because no other data is transferred, the variable is defined as undefined
napi_value undefined = nullptr;
napi_status operStatus = napi_get_undefined(env, &undefined);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// convert the calculation result of C++ sub-thread to the napi_value type
napi_value callBackArgs = nullptr;
operStatus = napi_create_string_utf8(env, contextData->result.c_str(), contextData->result.length(), &callBackArgs);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// call the JS callback and send the async calculation result on the Native to ArkTS application
napi_value callBackResult = nullptr;
(void)napi_call_function(env, undefined, callBack, 1, &callBackArgs, &callBackResult);
// destroy data and release memory
DeleteContext(env, contextData);
}Native線程安全函數(shù)異步開發(fā)接口：解析ArkTS應(yīng)用側(cè)參數(shù)，使用napi_create_threadsafe_function創(chuàng)建線程安全函數(shù)對象，并在消費者線程執(zhí)行函數(shù)ConsumeElementTSF中使用napi_call_threadsafe_function將異步回調(diào)處理函數(shù)call_js_cb拋到EventLoop中，等待調(diào)度執(zhí)行。
MultiThreads.cpp文件
// thread safe function async interface
static napi_value GetImagePathAsyncTSF(napi_env env, napi_callback_info info) {
size_t paraNum = 2;
napi_value paraArray[2] = {nullptr};
// parse parameters
napi_status operStatus = napi_get_cb_info(env, info, ?Num, paraArray, nullptr, nullptr);
if (operStatus != napi_ok) {
return nullptr;
}
napi_valuetype paraDataType = napi_undefined;
operStatus = napi_typeof(env, paraArray[0], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_string)) {
return nullptr;
}
operStatus = napi_typeof(env, paraArray[1], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_function)) {
return nullptr;
}
// napi_value convert to char *
constexpr size_t buffSize = 100;
char strBuff[buffSize]{}; // char buffer for imageName string
size_t strLength = 0;
operStatus = napi_get_value_string_utf8(env, paraArray[0], strBuff, buffSize, &strLength);
if ((operStatus != napi_ok) || (strLength == 0)) {
return nullptr;
}
// async resource
napi_value asyncName = nullptr;
string asyncStr = "async napi_threadsafe_function";
operStatus = napi_create_string_utf8(env, asyncStr.c_str(), asyncStr.length(), &asyncName);
if (operStatus != napi_ok) {
return nullptr;
}
// defines context data. the memory will be released in CompleteFunc
auto contextData = new ContextData;
contextData->args = strBuff;
// create thread safe function
if (tsFun == nullptr) {
operStatus =
napi_create_threadsafe_function(env, paraArray[1], nullptr, asyncName, MAX_MSG_QUEUE_SIZE,
INITIAL_THREAD_COUNT, nullptr, nullptr, nullptr, CallJsFunction, &tsFun);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
}
// create producer thread
thread producer(ProductElement, static_cast<void *>(contextData));
producer.detach(); // must be detached
// create consumer thread
thread consumer(ConsumeElementTSF, static_cast<void *>(contextData));
consumer.detach();
return nullptr;
}八、完整代碼
ProducerConsumer.h
//
// Created on 2025/7/2.
//
// Node APIs are not fully supported. To solve the compilation error of the interface cannot be found,
// please include "napi/native_api.h".
// 生產(chǎn)者-消費者模型實現(xiàn)
// 模型緩沖隊列
#ifndef MultiThreads_ProducerConsumer_H
#define MultiThreads_ProducerConsumer_H
#include <string>
#include <queue>
#include <mutex>
#include <condition_variable>
using namespace std;
// Principles of the producer-consumer model: Use buffer zones to balance the rate between production and consumption.
// Synchronization relationship 1: When the buffer is full, the producer needs to be blocked and wait. When a product
// pops up the buffer, the producer needs to be woken up for consumption. Synchronization relationship 2: When the
// buffer is empty, the consumer needs to be blocked and waited. When a product enters the buffer, the consumer needs to
// be woken up for consumption.
class ProducerConsumerQueue {
public:
// constructor
ProducerConsumerQueue() {}
ProducerConsumerQueue(int queueSize) : m_maxSize(queueSize) {}
// producer enqueue operation
void PutElement(string element);
// consumer dequeue operation
string TakeElement();
private:
// check whether the buffer queue is full
bool isFull() { return (m_queue.size() == m_maxSize); }
// check whether the buffer queue is empty
bool isEmpty() { return m_queue.empty(); }
private:
queue<string> m_queue{}; // buffer queue
int m_maxSize{}; // buffer queue capacity
mutex m_mutex{}; // the mutex is used to protect data consistency
condition_variable m_notEmpty{}; // condition variable, which is used to indicate whether the buffer queue is empty
condition_variable m_notFull{}; // condition variable, which is used to indicate whether the buffer queue is full
};
#endif // MultiThreads_ProducerConsumer_HProducerConsumer.cpp
//
// Created on 2025/7/2.
//
// Node APIs are not fully supported. To solve the compilation error of the interface cannot be found,
// please include "napi/native_api.h".
// 生產(chǎn)者-消費者模型實現(xiàn)
#include "ProducerConsumer.h"
void ProducerConsumerQueue::PutElement(string element) {
unique_lock<mutex> lock(m_mutex); // add mutex
while (isFull()) {
// when the data buffer queue is full, the production is blocked and wakes up after consumer consumption
// m_mutex is automatically released at the same time
m_notFull.wait(lock);
}
// reacquire the lock
// if the queue is not full
// the product is added to the queue and the consumer is notified that the product can be consumed
m_queue.push(element);
m_notEmpty.notify_one();
}
string ProducerConsumerQueue::TakeElement() {
unique_lock<mutex> lock(m_mutex); // add mutex
while (isEmpty()) {
// when the data buffer queue is empty, the consumption is blocked and the producer is woken up after production
// m_mutex is automatically released at the same time
m_notEmpty.wait(lock);
}
// reacquire the lock
// if the queue is not empty, the product is ejected and the producer is notified that it is ready for production
string element = m_queue.front();
m_queue.pop();
m_notFull.notify_one();
return element;
}MultiThreads.cpp
/*
* Copyright (c) 2024 Huawei Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#include "napi/native_api.h"
#include "ProducerConsumer.h"
#include <vector>
#include <thread>
using namespace std;
// define global thread safe function
static napi_threadsafe_function tsFun = nullptr;
static constexpr int MAX_MSG_QUEUE_SIZE = 0; // indicates that the queue length is not limited
static constexpr int INITIAL_THREAD_COUNT = 1;
// context data provided by users
// data is transferred between the native method (initialization data), ExecuteFunc, and CompleteFunc
struct ContextData {
napi_async_work asyncWork = nullptr; // async work object
napi_deferred deferred = nullptr; // associated object of the delay object promise
napi_ref callbackRef = nullptr; // reference of callback
string args = ""; // parameters from ArkTS --- imageName
string result = ""; // C++ sub-thread calculation result --- imagePath
};
//定義一個靜態(tài)全局的模型緩沖隊列。由于，每次只處理一張圖片，所以將容量設(shè)定為1。
//
//定義一個靜態(tài)全局的圖片路徑集合，用于后文搜索。
// define the buffer queue and set the capacity to 1
static ProducerConsumerQueue buffQueue(1);
// defines the image path set, which is used for later search
static vector<string> imagePathVec{"sync.png", "callback.png", "promise.png", "tsf.png"};
// check the image paths based on the image name
static bool CheckImagePath(const string &imageName, const string &imagePath) {
// separate character strings by suffix
size_t pos = imagePath.find_first_of('.');
if (pos == string::npos) {
return false;
}
string nameTemp = imagePath.substr(0, pos);
if (nameTemp.empty()) {
return false;
}
// determine whether the image path is the target path based on whether the image names are the same
return (imageName == nameTemp);
}
// search for image paths by image name
static string SearchImagePath(const string &imageName) {
for (const string &imagePath : imagePathVec) {
if (CheckImagePath(imageName, imagePath)) {
return imagePath;
}
}
return string("");
}
//生產(chǎn)者線程執(zhí)行函數(shù)
//生產(chǎn)者線程的執(zhí)行功能：通過解析上下文數(shù)據(jù)中的圖片名稱參數(shù)，來搜索相應(yīng)的圖片路徑，并將其置入模型緩沖隊列中。
static void ProductElement(void *data) {
buffQueue.PutElement(SearchImagePath(static_cast<ContextData *>(data)->args));
}
//消費者線程執(zhí)行函數(shù)
//消費者線程的執(zhí)行功能：通過從模型緩沖隊列中獲取圖片路徑的搜索結(jié)果，并將其置入上下文數(shù)據(jù)中，用以后續(xù)反饋給ArkTS應(yīng)用側(cè)。
//非線程安全函數(shù)消費者執(zhí)行函數(shù)：
static void ConsumeElement(void *data) { static_cast<ContextData *>(data)->result = buffQueue.TakeElement(); }
//線程安全函數(shù)消費者執(zhí)行函數(shù)：
static void ConsumeElementTSF(void *data) {
static_cast<ContextData *>(data)->result = buffQueue.TakeElement();
// bind consumer thread to the thread safe function
(void)napi_acquire_threadsafe_function(tsFun);
// send async task to the JS main thread EventLoop
(void)napi_call_threadsafe_function(tsFun, data, napi_tsfn_blocking);
// release thread reference
(void)napi_release_threadsafe_function(tsFun, napi_tsfn_release);
}
static void DeleteContext(napi_env env, ContextData *contextData) {
// delete callback reference
if (contextData->callbackRef != nullptr) {
(void)napi_delete_reference(env, contextData->callbackRef);
}
// delete async work
if (contextData->asyncWork != nullptr) {
(void)napi_delete_async_work(env, contextData->asyncWork);
}
// release context data
delete contextData;
}
static void ExecuteFunc([[maybe_unused]] napi_env env, void *data) {
// create producer thread
thread producer(ProductElement, data);
// the producer and consumer threads must be synchronized
// otherwise, the complete operation is triggered to communicate with the ArkTS after the executeFunc is complete
// the result is unpredictable
producer.join();
// create consumer thread
thread consumer(ConsumeElement, data);
consumer.join();
}
static void CompleteFuncCallBack(napi_env env, [[maybe_unused]] napi_status status, void *data) {
// parse context data
ContextData *contextData = static_cast<ContextData *>(data);
napi_value callBack = nullptr;
napi_status operStatus = napi_get_reference_value(env, contextData->callbackRef, &callBack);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// define the undefined variable, which is used in napi_call_function
// because no other data is transferred, the variable is defined as undefined
napi_value undefined = nullptr;
operStatus = napi_get_undefined(env, &undefined);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// convert the calculation result of C++ sub-thread to the napi_value type
napi_value callBackArgs = nullptr;
operStatus = napi_create_string_utf8(env, contextData->result.c_str(), contextData->result.length(), &callBackArgs);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// call the JS callback and send the async calculation result on the Native to ArkTS application
napi_value callBackResult = nullptr;
(void)napi_call_function(env, undefined, callBack, 1, &callBackArgs, &callBackResult);
// destroy data and release memory
DeleteContext(env, contextData);
}
static void CompleteFuncPromise(napi_env env, [[maybe_unused]] napi_status status, void *data) {
// parse context data
ContextData *contextData = static_cast<ContextData *>(data);
// convert the calculation result of C++ sub-thread to the napi_value type
napi_value promiseArgs = nullptr;
napi_status operStatus =
napi_create_string_utf8(env, contextData->result.c_str(), contextData->result.length(), &promiseArgs);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// the deferred and promise object are associated. the result is sent to ArkTS application through this interface
operStatus = napi_resolve_deferred(env, contextData->deferred, promiseArgs);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// destroy data and release memory
DeleteContext(env, contextData);
}
static void CallJsFunction(napi_env env, napi_value callBack, [[maybe_unused]] void *context, void *data) {
// parse context data
ContextData *contextData = static_cast<ContextData *>(data);
// define the undefined variable, which is used in napi_call_function
// because no other data is transferred, the variable is defined as undefined
napi_value undefined = nullptr;
napi_status operStatus = napi_get_undefined(env, &undefined);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// convert the calculation result of C++ sub-thread to the napi_value type
napi_value callBackArgs = nullptr;
operStatus = napi_create_string_utf8(env, contextData->result.c_str(), contextData->result.length(), &callBackArgs);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return;
}
// call the JS callback and send the async calculation result on the Native to ArkTS application
napi_value callBackResult = nullptr;
(void)napi_call_function(env, undefined, callBack, 1, &callBackArgs, &callBackResult);
// destroy data and release memory
DeleteContext(env, contextData);
}
// sync interface
static napi_value GetImagePathSync(napi_env env, napi_callback_info info) {
size_t paraNum = 1;
napi_value paraArray[1] = {nullptr};
// parse parameters
napi_status operStatus = napi_get_cb_info(env, info, ?Num, paraArray, nullptr, nullptr);
if (operStatus != napi_ok) {
return nullptr;
}
napi_valuetype paraDataType = napi_undefined;
operStatus = napi_typeof(env, paraArray[0], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_string)) {
return nullptr;
}
// convert napi_value to char *
constexpr size_t buffSize = 100;
char strBuff[buffSize]{}; // char buffer for imageName string
size_t strLength = 0;
operStatus = napi_get_value_string_utf8(env, paraArray[0], strBuff, buffSize, &strLength);
if ((operStatus != napi_ok) || (strLength == 0)) {
return nullptr;
}
// defines context data. the memory will be released in CompleteFunc
auto contextData = new ContextData;
contextData->args = strBuff;
// create producer thread
thread producer(ProductElement, static_cast<void *>(contextData));
producer.join();
// create consumer thread
thread consumer(ConsumeElement, static_cast<void *>(contextData));
consumer.join();
// convert the result to napi_value and send it to ArkTs application
napi_value result = nullptr;
(void)napi_create_string_utf8(env, contextData->result.c_str(), contextData->result.length(), &result);
// delete context data
DeleteContext(env, contextData);
return result;
}
// callback async interface
static napi_value GetImagePathAsyncCallBack(napi_env env, napi_callback_info info) {
size_t paraNum = 2;
napi_value paraArray[2] = {nullptr};
// parse parameters
napi_status operStatus = napi_get_cb_info(env, info, ?Num, paraArray, nullptr, nullptr);
if (operStatus != napi_ok) {
return nullptr;
}
napi_valuetype paraDataType = napi_undefined;
operStatus = napi_typeof(env, paraArray[0], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_string)) {
return nullptr;
}
operStatus = napi_typeof(env, paraArray[1], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_function)) {
return nullptr;
}
// napi_value convert to char *
constexpr size_t buffSize = 100;
char strBuff[buffSize]{}; // char buffer for imageName string
size_t strLength = 0;
operStatus = napi_get_value_string_utf8(env, paraArray[0], strBuff, buffSize, &strLength);
if ((operStatus != napi_ok) || (strLength == 0)) {
return nullptr;
}
// defines context data. the memory will be released in CompleteFunc
auto contextData = new ContextData;
contextData->args = strBuff;
operStatus = napi_create_reference(env, paraArray[1], 1, &contextData->callbackRef);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// async resource
napi_value asyncName = nullptr;
string asyncStr = "async callback";
operStatus = napi_create_string_utf8(env, asyncStr.c_str(), asyncStr.length(), &asyncName);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// create async work
operStatus = napi_create_async_work(env, nullptr, asyncName, ExecuteFunc, CompleteFuncCallBack,
static_cast<void *>(contextData), &contextData->asyncWork);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// add the async work to the queue and wait for scheduling
operStatus = napi_queue_async_work(env, contextData->asyncWork);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
}
return nullptr;
}
// promise async interface
static napi_value GetImagePathAsyncPromise(napi_env env, napi_callback_info info) {
size_t paraNum = 1;
napi_value paraArray[1] = {nullptr};
// parse parameters
napi_status operStatus = napi_get_cb_info(env, info, ?Num, paraArray, nullptr, nullptr);
if (operStatus != napi_ok) {
return nullptr;
}
napi_valuetype paraDataType = napi_undefined;
operStatus = napi_typeof(env, paraArray[0], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_string)) {
return nullptr;
}
// napi_value convert to char *
constexpr size_t buffSize = 100;
char strBuff[buffSize]{}; // char buffer for imageName string
size_t strLength = 0;
operStatus = napi_get_value_string_utf8(env, paraArray[0], strBuff, buffSize, &strLength);
if ((operStatus != napi_ok) || (strLength == 0)) {
return nullptr;
}
// defines context data. the memory will be released in CompleteFunc
auto contextData = new ContextData;
contextData->args = strBuff;
// async resource
napi_value asyncName = nullptr;
string asyncStr = "async promise";
operStatus = napi_create_string_utf8(env, asyncStr.c_str(), asyncStr.length(), &asyncName);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// create async work
operStatus = napi_create_async_work(env, nullptr, asyncName, ExecuteFunc, CompleteFuncPromise,
static_cast<void *>(contextData), &contextData->asyncWork);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// add the async work to the queue and wait for scheduling
operStatus = napi_queue_async_work(env, contextData->asyncWork);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
// create promise object
napi_value promiseObj = nullptr;
operStatus = napi_create_promise(env, &contextData->deferred, &promiseObj);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
return promiseObj;
}
// thread safe function async interface
static napi_value GetImagePathAsyncTSF(napi_env env, napi_callback_info info) {
size_t paraNum = 2;
napi_value paraArray[2] = {nullptr};
// parse parameters
napi_status operStatus = napi_get_cb_info(env, info, ?Num, paraArray, nullptr, nullptr);
if (operStatus != napi_ok) {
return nullptr;
}
napi_valuetype paraDataType = napi_undefined;
operStatus = napi_typeof(env, paraArray[0], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_string)) {
return nullptr;
}
operStatus = napi_typeof(env, paraArray[1], ?DataType);
if ((operStatus != napi_ok) || (paraDataType != napi_function)) {
return nullptr;
}
// napi_value convert to char *
constexpr size_t buffSize = 100;
char strBuff[buffSize]{}; // char buffer for imageName string
size_t strLength = 0;
operStatus = napi_get_value_string_utf8(env, paraArray[0], strBuff, buffSize, &strLength);
if ((operStatus != napi_ok) || (strLength == 0)) {
return nullptr;
}
// async resource
napi_value asyncName = nullptr;
string asyncStr = "async napi_threadsafe_function";
operStatus = napi_create_string_utf8(env, asyncStr.c_str(), asyncStr.length(), &asyncName);
if (operStatus != napi_ok) {
return nullptr;
}
// defines context data. the memory will be released in CompleteFunc
auto contextData = new ContextData;
contextData->args = strBuff;
// create thread safe function
if (tsFun == nullptr) {
operStatus =
napi_create_threadsafe_function(env, paraArray[1], nullptr, asyncName, MAX_MSG_QUEUE_SIZE,
INITIAL_THREAD_COUNT, nullptr, nullptr, nullptr, CallJsFunction, &tsFun);
if (operStatus != napi_ok) {
DeleteContext(env, contextData);
return nullptr;
}
}
// create producer thread
thread producer(ProductElement, static_cast<void *>(contextData));
producer.detach(); // must be detached
// create consumer thread
thread consumer(ConsumeElementTSF, static_cast<void *>(contextData));
consumer.detach();
return nullptr;
}
EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports) {
napi_property_descriptor desc[] = {
{"getImagePathSync", nullptr, GetImagePathSync, nullptr, nullptr, nullptr, napi_default, nullptr},
{"getImagePathAsyncCallBack", nullptr, GetImagePathAsyncCallBack, nullptr, nullptr, nullptr, napi_default,
nullptr},
{"getImagePathAsyncPromise", nullptr, GetImagePathAsyncPromise, nullptr, nullptr, nullptr, napi_default,
nullptr},
{"getImagePathAsyncTSF", nullptr, GetImagePathAsyncTSF, nullptr, nullptr, nullptr, napi_default, nullptr}};
napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
return exports;
}
EXTERN_C_END
static napi_module demoModule = {
.nm_version = 1,
.nm_flags = 0,
.nm_filename = nullptr,
.nm_register_func = Init,
.nm_modname = "entry",
.nm_priv = ((void *)0),
.reserved = {0},
};
extern "C" __attribute__((constructor)) void RegisterEntryModule(void) { napi_module_register(&demoModule); }九、注意事項
線程安全：在異步開發(fā)中，確保所有線程在執(zhí)行任務(wù)時不會發(fā)生數(shù)據(jù)競爭或死鎖。
錯誤處理：在處理圖片加載失敗的情況時，及時拋出異常并反饋錯誤信息。
性能優(yōu)化：通過優(yōu)化異步任務(wù)的執(zhí)行時間，減少主線程的阻塞等待時間。
資源管理：正確釋放隊列、線程和資源，避免資源泄漏和泄漏。
異常處理：確保所有異步任務(wù)都有明確的異常處理邏輯，避免程序崩潰或不響應(yīng)。
十、個人評價
優(yōu)點
開發(fā)流程清晰，代碼結(jié)構(gòu)合理，易于理解和維護(hù)。 靈活性高，支持多種場景的異步開發(fā)。 線程安全機制完善，確保了任務(wù)執(zhí)行過程中的并發(fā)安全。 配套的接口文檔詳細(xì)，便于開發(fā)和調(diào)試。
缺點
需要有一定的C/C++開發(fā)經(jīng)驗，才能熟練掌握異步開發(fā)的技巧。 異步任務(wù)的執(zhí)行結(jié)果反饋機制需要額外的配置和測試。 在處理大規(guī)模數(shù)據(jù)或復(fù)雜場景時，性能可能會有所瓶頸。
十一、更多案例
文件操作異步開發(fā)
用戶可以選擇“文件操作異步調(diào)用”按鈕，啟動異步文件讀取任務(wù)。 Native側(cè)將異步執(zhí)行文件讀取業(yè)務(wù)邏輯，不阻塞應(yīng)用側(cè)。 應(yīng)用側(cè)返回讀取結(jié)果，用于文件路徑刷新。
網(wǎng)絡(luò)請求異步開發(fā)
用戶可以選擇“網(wǎng)絡(luò)請求異步調(diào)用”按鈕，啟動異步網(wǎng)絡(luò)請求任務(wù)。 Native側(cè)將異步執(zhí)行網(wǎng)絡(luò)請求業(yè)務(wù)邏輯，不阻塞應(yīng)用側(cè)。 應(yīng)用側(cè)返回響應(yīng)結(jié)果，用于UI刷新。
數(shù)據(jù)庫操作異步開發(fā)
用戶可以選擇“數(shù)據(jù)庫操作異步調(diào)用”按鈕，啟動異步數(shù)據(jù)庫寫入任務(wù)。 Native側(cè)將異步執(zhí)行數(shù)據(jù)庫寫入業(yè)務(wù)邏輯，不阻塞應(yīng)用側(cè)。 應(yīng)用側(cè)返回寫入結(jié)果，用于業(yè)務(wù)狀態(tài)刷新。
十二、總結(jié)
在線程安全開發(fā)的基礎(chǔ)上，進(jìn)一步優(yōu)化線程調(diào)度和執(zhí)行效率，確保多線程場景下的性能穩(wěn)定。通過優(yōu)化異步工作項的執(zhí)行邏輯和隊列管理，提升異步任務(wù)的整體執(zhí)行效率。針對復(fù)雜的業(yè)務(wù)邏輯，設(shè)計更靈活的異步任務(wù)模型，確保異步開發(fā)的靈活性和擴展性。 使用性能監(jiān)控工具，分析異步任務(wù)的執(zhí)行時序和資源使用情況，優(yōu)化任務(wù)執(zhí)行效率。
通過以上步驟，用戶可以掌握基于Node-API的同步、異步和線程安全開發(fā)技巧，實現(xiàn)高效、安全的圖片加載和相關(guān)業(yè)務(wù)邏輯。
您可能感興趣的文章:
相關(guān)文章
粒子動畫經(jīng)常用于大畫幅的渲染效果,實際上難度并不高,但是在使用粒子動畫時,必須要遵循的一些要素,起點,矢量速度和符合運動學(xué)公式等,文中有詳細(xì)的代碼示例供大家參考,具有一定的參考價值,需要的朋友可以參考下2024-01-01
這篇文章主要介紹了如何利用Flutter實現(xiàn)手勢密碼的加密與解鎖，文中通過示例代碼介紹的非常詳細(xì)，具有一定的參考價值，感興趣的小伙伴們可以參考一下2022-04-04
Android自定義控件實現(xiàn)不規(guī)則區(qū)域點擊事件
這篇文章主要為大家詳細(xì)介紹了Android自定義控件實現(xiàn)不規(guī)則區(qū)域點擊事件，具有一定的參考價值，感興趣的小伙伴們可以參考一下2018-05-05
這篇文章主要介紹了Android Spinner列表選擇框的應(yīng)用的相關(guān)資料,這里對spinner的屬性和常用事件和數(shù)據(jù)綁定都做了介紹，需要朋友可以參考下2017-07-07
Android便攜式熱點的開啟狀態(tài)檢測和SSID的獲取方法
WIFI熱點的開啟狀態(tài)和開啟后的SSID如何獲取呢？接下來通過本文給大家分享Android便攜式熱點的開啟狀態(tài)檢測和SSID的獲取方法，需要的朋友參考下吧2017-01-01
這篇文章主要介紹了Android Handler的使用詳解,本篇文章通過簡要的案例,講解了該項技術(shù)的了解與使用,以下就是詳細(xì)內(nèi)容,需要的朋友可以參考下2021-09-09
這篇文章主要為大家詳細(xì)介紹了Android是如何實現(xiàn)陰影效果的，文中的示例代碼講解詳細(xì)，對我們學(xué)習(xí)Android有一定的幫助，需要的可以參考一下2022-06-06
這篇文章主要為大家詳細(xì)介紹了Android仿QQ個人標(biāo)簽添加與刪除功能，具有一定的參考價值，感興趣的小伙伴們可以參考一下2018-12-12
從"Show?tabs"了解Android?Input系統(tǒng)
這篇文章主要介紹了從"Show?tabs"了解Android?Input系統(tǒng)的相關(guān)資料,需要的朋友可以參考下2023-01-01
Android中ViewPager的PagerTabStrip與PagerTitleStrip用法實例
這篇文章主要介紹了Android中ViewPager的PagerTabStrip與PagerTitleStrip用法實例,這兩個子控件一般被用作添加標(biāo)題,在實際效果上并不是那么好控制,使用的時候需要謹(jǐn)慎,需要的朋友可以參考下2016-06-06