使用Node-API进行线程安全开发

一、Node-API线程安全机制概述

        Node-API线程安全开发主要用于异步多线程之间共享和调用场景中使用，以避免出现竞争条件或死锁。

        1、适用场景

• 异步计算：如果需要进行耗时的计算或IO操作，可以创建一个线程安全函数，将计算或IO操作放在另一个线程中执行，避免阻塞主线程，提高程序的响应速度。
• 数据共享：如果多个线程需要访问同一份数据，可以创建一个线程安全函数，确保数据的读写操作不会发生竞争条件或死锁等问题。
• 多线程开发：如果需要进行多线程开发，可以创建一个线程安全函数，确保多个线程之间的通信和同步操作正确无误。

        2、总体步骤

        Node-API接口只能在ArkTS主线程上进行调用。当C++子线程或者work子线程需要调用ArkTS回调接口或者Node-API接口时，这些线程是需要与ArkTS主线程进行通信才能完成的。Node-API提供了类型napi_threadsafe_function（线程安全函数）以及创建、销毁和调用该类型对象的 API来完成此操作。Node-API主要是通过创建一个线程安全函数，然后在C++子线程或者work子线程中调用线程安全函数来实现线程安全开发。

        步骤如下：

1. 在Native接口函数中，创建一个线程安全函数对象，并注册绑定ArkTS回调接口callback和线程安全回调函数call_js_cb，然后立即返回一个临时结果给ArkTS调用者；
2. 通过系统调度C++子线程完成异步业务逻辑的执行，并在子线程的执行函数中调用napi_call_threadsafe_function，将call_js_cb抛给EventLoop事件循环进行调度；
3. 通过call_js_cb执行，调用napi_call_function调用ArkTS回调接口callback，从而将异步计算结果反馈到ArkTS应用侧，用于应用侧UI刷新。

        3、原理流程 

        线程安全函数的底层机制依然是基于libuv异步库来实现的。

        4、关键接口 

        线程安全函数机制中关键的两个接口napi_create_threadsafe_function()和napi_call_threadsafe_function()。

        （1）napi_create_threadsafe_function

        该接口主要用于创建线程安全对象，在创建的过程中，会注册异步过程中的关键信息：ArkTS侧回调接口callback、线程安全回调函数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);
参数说明：
[in] env：传入接口调用者的环境，包含方舟引擎等。由框架提供，默认情况下直接传入即可。
[in] func：ArkTS应用侧传入的回调接口callback，可为空。当该值为nullptr时，下文call_js_cb不能为nullptr。反之，亦然。两者不可同时为空。
[in] async_resource：关联async_hooks，可为空。
[in] async_resource_name：异步资源标识符，主要用于async_hooks API暴露断言诊断信息。
[in] max_queue_size：缓冲队列容量，0表示无限制。线程安全函数实现实质为生产者-消费者模型。
[in] initial_thread_count：初始线程，包括将使用此函数的主线程，可为空。
[in] thread_finalize_data：传递给thread_finalize_cb接口的参数，可为空。
[in] thread_finalize_cb：当线程安全函数结束释放时的回调接口，可为空。
[in] context：附加的上下文数据，可为空。
[in] call_js_cb：子线程需要处理的线程安全回调任务，类似于异步工作项中的complete回调。当调用napi_call_threadsafe_function后，被抛到ArkTS主线程EventLoop中，等待调度执行。当该值为空时，系统将会调用默认回调接口。
[out] result：线程安全函数对象指针。

        （2）napi_call_threadsafe_function

        该接口主要用于子线程中，将需要回到ArkTS主线程处理的任务抛到EventLoop中，等待调度执行。

NAPI_EXTERN napi_status napi_call_threadsafe_function(napi_threadsafe_function func, void* data, napi_threadsafe_function_call_mode is_blocking);
参数说明：
[in] func：线程安全函数对象。
[in] data：上述线程安全回调任务call_js_cb需要处理的数据。
[in] is_blocking：该参数控制接口是否以阻塞的方式运行。
                  如果参数为napi_tsfn_nonblocking，该接口将以非阻塞的方式运行。当缓冲队列已满，调用该接口后，则返回napi_queue_full错误码。
                  如果参数为napi_tsfn_blocking，该接口将以阻塞的方式运行，直到缓冲队列中有可用空间。
                  如果创建线程安全函数时，设置的最大队列容量为0，则napi_call_threadsafe_function()永远不会阻塞。

二、线程安全开发时序交互图

        从上图中，可以看出，当Native线程安全异步接口被调用时，该接口会完成参数解析、数据类型转换、线程安全创建、在创建过程中的注册绑定ArkTS回调处理函数以及创建生产者和消费者线程等。异步任务的调度、执行以及反馈计算结果，均由C++子线程和EventLoop机制进行系统调度完成。

三、线程安全开发步骤（简介）

        

        

        

        

        

四、线程安全开发步骤（实例）   

        1、ArkTS应用侧开发      

// 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;
            });
          })
      ...
      }
      ...
    }
    ...
  }
}

        2、Native侧开发

        导出Native接口：将Native接口导出到ArkTS侧，用于支撑ArkTS对象调用和模块编译构建。

// index.d.ts文件
export const getImagePathAsyncTSF: (imageName: string, callBack: (result: string) => void) => void;

        全局变量定义：定义线程安全函数对象、队列容量、初始化线程数。

// 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回调处理定义：定义消费者子线程中，通过napi_call_threadsafe_function抛到ArkTS主线程EventLoop中的回调处理函数。在该函数中，通过napi_call_function调用ArkTS应用侧传入的回调callback，将异步任务搜索到的图片路径结果反馈到ArkTS应用侧。

// 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线程安全函数异步开发接口：解析ArkTS应用侧参数，使用napi_create_threadsafe_function创建线程安全函数对象，并在消费者线程执行函数ConsumeElementTSF中使用napi_call_threadsafe_function将异步回调处理函数call_js_cb抛到EventLoop中，等待调度执行。

// 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, &paraNum, paraArray, nullptr, nullptr);
    if (operStatus != napi_ok) {
        return nullptr;
    }
    napi_valuetype paraDataType = napi_undefined;
    operStatus = napi_typeof(env, paraArray[0], &paraDataType);
    if ((operStatus != napi_ok) || (paraDataType != napi_string)) {
        return nullptr;
    }
    operStatus = napi_typeof(env, paraArray[1], &paraDataType);
    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;
}