Openharmony应用NAPI详解--进阶篇1_napi使用

NAPI面向C++的异步接口

3.C++实现NAPI异步接口需要做到三步

• 同步返回结果给js/ets调用者

• 另起线程完成异步操作

• 通过回调(callback)或Promise将异步操作结果返回

4.异步接口

// foundation/filemanagement/dfs_service/frameworks/js/napi/src/sendfile_napi.cpp
...
    DECLARE_NAPI_FUNCTION("sendFile", JsSendFile),
...

根据映射，同步接口sendFile对应C++的实现是JsSendFile。

• 函数声明

// foundation/filemanagement/dfs_service/frameworks/js/napi/src/sendfile_napi.cpp
napi_value JsSendFile(napi_env env, napi_callback_info info)
{
......
}

• 获取入参

同样是获取参数个数与参数，根据d.ts里sendFile接口定义，第五个参数为callback或没有参数，callback接口返回一个void， promise接口返回一个promise对象。

// foundation/filemanagement/dfs_service
declare namespace SendFile {
  function sendFile(deviceId: string, sourPath: Array<string>, destPath: Array<string>, fileCount: number, callback: AsyncCallback<number>);
  function sendFile(deviceId: string, sourPath: Array<string>, destPath: Array<string>, fileCount: number): Promise<number>;
}

此时获取参数个数与参数类型与具体数据，被一个类NFuncArg对象funcArg进行解析。

// foundation/filemanagement/dfs_service/frameworks/js/napi/src/sendfile_napi.cpp
napi_value JsSendFile(napi_env env, napi_callback_info info)
{
	NFuncArg funcArg(env, info);
    if (!funcArg.InitArgs(DFS_ARG_CNT::FOUR, DFS_ARG_CNT::FIVE)) {
        NError(EINVAL).ThrowErr(env, "Number of arguments unmatched");
        return nullptr;
    }
...
}

我们熟悉的获取参数的方法napi_get_cb_info在类NFuncArg中可以找到。

bool NFuncArg::InitArgs(std::function<bool()> argcChecker)
{
    SetArgc(0);
    argv_.reset();
 
    size_t argc;
    napi_value thisVar;
    napi_status status = napi_get_cb_info(env_, info_, &argc, nullptr, &thisVar, nullptr);
    if (status != napi_ok) {
        HILOGE("Cannot get num of func args for %{public}d", status);
        return false;
    }
    if (argc) {
        argv_ = make_unique<napi_value[]>(argc);
        status = napi_get_cb_info(env_, info_, &argc, argv_.get(), &thisVar, nullptr);
        if (status != napi_ok) {
            HILOGE("Cannot get func args for %{public}d", status);
            return false;
        }
    }
    SetArgc(argc);
    SetThisVar(thisVar);
 
    return argcChecker();
}

略过参数的类型转化与参数值校验，直接进入callback与promise的判断。

napi_value JsSendFile(napi_env env, napi_callback_info info)
{
...
	if (funcArg.GetArgc() == DFS_ARG_CNT::FOUR) {
        return NAsyncWorkPromise(env, thisVar).Schedule(procedureName, cbExec, cbComplete).val_;
    } else if (funcArg.GetArgc() == DFS_ARG_CNT::FIVE) {
        NVal cb(env, funcArg[DFS_ARG_POS::FIFTH]);// cb为传入的回调函数
        return NAsyncWorkCallback(env, thisVar, cb).Schedule(procedureName, cbExec, cbComplete).val_;
    }
}

此时的判断的方式通过传入的参数个数是4还是5来判断callback与promise。

如果有参数个数相同的情况时，可以根据参数的类型来进行判断。

// 可以改写成如下判断
napi_value JsSendFile(napi_env env, napi_callback_info info)
{
...
	napi_valuetype valueType = napi_undefined;
    // (此处假设promise接口也有第5个参数，否则会报异常错误) 
	napi_typeof(env, funcArg[DFS_ARG_POS::FIFTH], &valueType);
    if (valueType == napi_function) { // Js调用的是callback接口
        ...
    } else {//Js调用的是promise接口
        ...
    }
...
}

此时，异步的方式需要另起线程，将参数传入线程后，JsSendFile直接返回。

NAPI框架中，异步的线程实现基于napi_create_async_work函数创建异步工作项。

代码中通过两个封装类NAsyncWorkPromise/NAsyncWorkCallback的Schedule来实现。可以在两个类的Schedule接口找到napi_create_async_work方法调用。

// foundation/filemanagement/file_api/interfaces/kits/js/src/common/napi/n_async/n_async_work_callback.cpp
NVal NAsyncWorkCallback::Schedule(string procedureName, NContextCBExec cbExec, NContextCBComplete cbComplete)
{
...
    napi_status status =
        napi_create_async_work(env_, nullptr, resource, CallbackExecute, CallbackComplete, ctx_, &ctx_->awork_);
    if (status != napi_ok) {
        HILOGE("INNER BUG. Failed to create async work for %{public}d", status);
        return NVal();
    }
...
}
 
// foundation/filemanagement/file_api/interfaces/kits/js/src/common/napi/n_async/n_async_work_promise.cpp
NVal NAsyncWorkPromise::Schedule(string procedureName, NContextCBExec cbExec, NContextCBComplete cbComplete)
{
...
    napi_value resource = NVal::CreateUTF8String(env_, procedureName).val_;
    status = napi_create_async_work(env_, nullptr, resource, PromiseOnExec, PromiseOnComplete, ctx_, &ctx_->awork_);
    if (status != napi_ok) {
        HILOGE("INNER BUG. Failed to create async work for %{public}d", status);
        return NVal();
    }
...
}

首先先分析下napi_create_async_work的方法定义

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);

参数说明：

[in] env: 传入接口调用者的环境，包含js引擎等，由框架提供。

[in] async_resource: 可选项，关联async_hooks。

[in] async_resource_name: 异步资源标识符，主要用于async_hooks API暴露断言诊断信息。

[in] execute: 异步工作项的处理函数，当工作项被调度到后在worker线程中执行，用于处理业务逻辑，并得到结果。

[in] complete: execute参数指定的函数执行完成或取消后，触发执行该函数，将结果返回给JS。此函数在EventLoop中执行。

[in] data: 异步工作项上下文数据（Addon），用于在主线程接口实现方法、execute、complete之间传递数据。

[out] result: napi_async_work*指针，返回创建的异步工作项对象。

返回值：返回napi_ok表示转换成功，其他值失败

异步线程的处理由execute和complete两个自定义函数实现。data即是execute和complete两个自定义函数的主要传入参数。data的结构可以自定义结构。

// data类型定义
class NAsyncContext {
public:
    UniError err_;
    NVal res_;
    NContextCBExec cbExec_;
    NContextCBComplete cbComplete_;
    napi_async_work awork_;
    NRef thisPtr_;
 
    explicit NAsyncContext(NVal thisPtr) : err_(0), res_(NVal()), cbExec_(nullptr),
        cbComplete_(nullptr), awork_(nullptr), thisPtr_(thisPtr) {}
    virtual ~NAsyncContext() = default;
};

callback方式的处理方式

执行napi_create_async_work异步线程后，通过napi_queue_async_work将创建的async work添加到队列，由NAPI框架的底层去调度后执行。

// foundation/filemanagement/file_api/interfaces/kits/js/src/common/napi/n_async/n_async_work_callback.cpp
NVal NAsyncWorkCallback::Schedule(string procedureName, NContextCBExec cbExec, NContextCBComplete cbComplete)
{
    if (!ctx_->cb_ || !ctx_->cb_.Deref(env_).TypeIs(napi_function)) {
        UniError(EINVAL).ThrowErr(env_, "The callback shall be a funciton");
        return NVal();
    }
	// data内成员赋值
    ctx_->cbExec_ = move(cbExec);
    ctx_->cbComplete_ = move(cbComplete);
 
    napi_value resource = NVal::CreateUTF8String(env_, procedureName).val_;
 
    napi_status status =
        napi_create_async_work(env_, nullptr, resource, CallbackExecute, CallbackComplete, ctx_, &ctx_->awork_);
    if (status != napi_ok) {
        HILOGE("INNER BUG. Failed to create async work for %{public}d", status);
        return NVal();
    }
    status = napi_queue_async_work(env_, ctx_->awork_);// 创建的async work添加到队列
    if (status != napi_ok) {
        HILOGE("INNER BUG. Failed to queue async work for %{public}d", status);
        return NVal();
    }
 
    ctx_ = nullptr; // The ownership of ctx_ has been transfered
    return NVal::CreateUndefined(env_);
}

实现自定义的execute和complete，分别对应CallbackExecute, CallbackComplete。处理完成后将

// foundation/filemanagement/file_api/interfaces/kits/js/src/common/napi/n_async/n_async_work_callback.cpp
static void CallbackExecute(napi_env env, void *data)
{
...
}
 
static void CallbackComplete(napi_env env, napi_status status, void *data)
{
...
    //callback为js/ets传入的回调函数
    napi_value callback = ctx->cb_.Deref(env).val_;
...
    napi_status stat = napi_call_function(env, global, callback, argv.size(), argv.data(), &tmp);
    if (stat != napi_ok) {
        HILOGE("Failed to call function for %{public}d", stat);
    }
    napi_close_handle_scope(env, scope);
    napi_delete_async_work(env, ctx->awork_);
    delete ctx;
}

此处的ctx->cb_成员赋值，由NVal与NAsyncWorkCallback的两个构造函数完成

// foundation/filemanagement/dfs_service/frameworks/js/napi/src/sendfile_napi.cpp
napi_value JsSendFile(napi_env env, napi_callback_info info)
{
...
    if (funcArg.GetArgc() == DFS_ARG_CNT::FOUR) {
        return NAsyncWorkPromise(env, thisVar).Schedule(procedureName, cbExec, cbComplete).val_;
    } else if (funcArg.GetArgc() == DFS_ARG_CNT::FIVE) {
        NVal cb(env, funcArg[DFS_ARG_POS::FIFTH]);
        return NAsyncWorkCallback(env, thisVar, cb).Schedule(procedureName, cbExec, cbComplete).val_;
    }
...
}

至此NAPI的异步回调流程完成。

后续更精彩

1.Openharmony应用NAPI详解--进阶篇2