從C++ Addon看Napi的實(shí)現(xiàn)
本文轉(zhuǎn)載自微信公眾號(hào)「編程雜技」，作者theanarkh。轉(zhuǎn)載本文請(qǐng)聯(lián)系編程雜技公眾號(hào)。
Node.js的napi極大地方便了c++ addon的編寫，使得用戶不再那么需要面對(duì)復(fù)雜的v8。本文通過(guò)一個(gè)例子來(lái)分析一下napi的使用和napi到底做了什么。
1 導(dǎo)出給js使用的功能
- #include <node_api.h>
- NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
上面的代碼是使用napi時(shí)的通用模式，我們只需要實(shí)現(xiàn)Init函數(shù)就行(當(dāng)然也可以叫其他名字)。接下來(lái)我們看看Init的實(shí)現(xiàn)。
- napi_value Init(napi_env env, napi_value exports) {
- napi_value func;
- // 創(chuàng)建一個(gè)函數(shù)并且設(shè)置為exports對(duì)象的getArray屬性的值
- napi_create_function(env,
- NULL,
- NAPI_AUTO_LENGTH,
- newArray,
- NULL,
- &func);
- napi_set_named_property(env, exports, "getArray", func);
- return exports;
- }
napi_create_function也是napi提供的api，他的作用是創(chuàng)建一個(gè)函數(shù)，具體可以參考napi的文檔。接著把這個(gè)函數(shù)導(dǎo)出給js使用，名字是getArray。當(dāng)js執(zhí)行g(shù)etArray的時(shí)候就會(huì)執(zhí)行newArray函數(shù)。
2 newArray的實(shí)現(xiàn)
- static napi_value newArray(napi_env env, napi_callback_info info) {
- size_t argc = 1;
- napi_value args[1];
- // 拿到j(luò)s層的入?yún)ⅲ@里是一個(gè)
- napi_get_cb_info(env, info, &argc, args, NULL, NULL);
- int len;
- // js傳入的是一個(gè)數(shù)字，v8轉(zhuǎn)成了對(duì)象，這里再次把入?yún)⑥D(zhuǎn)成int型
- napi_get_value_int32(env, args[0], &len);
- napi_value ret;
- // 創(chuàng)建一個(gè)數(shù)組
- napi_create_array(env, &ret);
- // 根據(jù)js入?yún)⒃O(shè)置數(shù)組的初始值
- for (int i = 0; i < len; i++) {
- napi_value num;
- napi_create_int32(env, i, &num);
- napi_set_element(env, ret, i, num);
- }
- return ret;
- }
3 使用c++ addon
- const { getArray } = require('./build/Release/test.node');
- console.log(getArray(20));
執(zhí)行上面代碼最后輸出
- [
- 0, 1, 2, 3, 4, 5, 6,
- 7, 8, 9, 10, 11, 12, 13,
- 14, 15, 16, 17, 18, 19
- ]
4 分析
上面的代碼并不復(fù)雜，本文主要是分析napi提供的api，看看napi到底做了什么。很多api的原理是類似的，這里只以數(shù)組的api為例子。因?yàn)関8的api中，使用的參數(shù)基本都是v8提供的對(duì)象。napi做的事情其實(shí)就是幫我們處理這些對(duì)象的轉(zhuǎn)換。我們首先看看napi_create_array的實(shí)現(xiàn)。
- // 創(chuàng)建一個(gè)數(shù)組，對(duì)應(yīng)js的數(shù)組
- napi_status napi_create_array(napi_env env, napi_value* result) {
- // 調(diào)用v8接口v8::Array::New創(chuàng)建一個(gè)數(shù)組對(duì)象，然后轉(zhuǎn)成napi的類型，并設(shè)置返回值
- *result = v8impl::JsValueFromV8LocalValue(v8::Array::New(env->isolate));
- return napi_clear_last_error(env);
- }
我們看到napi_create_array的實(shí)現(xiàn)非常簡(jiǎn)單，就是對(duì)v8接口的封裝，然后轉(zhuǎn)換成napi的類型，最后清除錯(cuò)誤信息。這是napi典型的api使用方式。主要包括下面幾個(gè)
1 入?yún)⑿枰獋魅雃nv對(duì)象，并傳入一個(gè)二級(jí)指針napi_value *，用于保存接口返回值。napi的返回值不是通過(guò)函數(shù)體的return返回的，return返回的是api的執(zhí)行狀態(tài)(成功或失敗)。
2 處理v8的api
3 清除或返回錯(cuò)誤信息 每次執(zhí)行napi提供的api時(shí)，如果執(zhí)行出錯(cuò)則通過(guò)napi_set_last_error設(shè)置到env中并返回錯(cuò)誤碼，如果沒(méi)有則通過(guò)napi_clear_last_error清除錯(cuò)誤信息并返回napi_ok。我們看一下實(shí)現(xiàn)
- // 設(shè)置當(dāng)前函數(shù)調(diào)用的錯(cuò)誤信息
- static inline napi_status napi_set_last_error(napi_env env, napi_status error_code,
- uint32_t engine_error_code = 0,
- void* engine_reserved = nullptr) {
- env->last_error.error_code = error_code;
- env->last_error.engine_error_code = engine_error_code;
- env->last_error.engine_reserved = engine_reserved;
- return error_code;
- }
- // 清除上次調(diào)用的錯(cuò)誤信息
- static inline napi_status napi_clear_last_error(napi_env env) {
- env->last_error.error_code = napi_ok;
- // TODO(boingoing): Should this be a callback?
- env->last_error.engine_error_code = 0;
- env->last_error.engine_reserved = nullptr;
- return napi_ok;
- }
調(diào)用方在調(diào)用完api后，如果產(chǎn)生了錯(cuò)誤，則可以通過(guò)napi_get_last_error_info接口獲取執(zhí)行api的錯(cuò)誤信息。
- // 獲取上一個(gè)調(diào)用函數(shù)的錯(cuò)誤信息
- napi_status napi_get_last_error_info(napi_env env,
- const napi_extended_error_info** result) {
- // 初始化為非法值
- const int last_status = napi_detachable_arraybuffer_expected;
- // 根據(jù)錯(cuò)誤碼設(shè)置錯(cuò)誤描述信息（每次調(diào)用api后調(diào)用結(jié)果存到env中）
- env->last_error.error_message =
- error_messages[env->last_error.error_code];
- *result = &(env->last_error);
- return napi_ok;
- }
言歸正傳，調(diào)用napi_create_array后，我們拿到一個(gè)返回值，比如下面的ret。
- napi_value ret;
- napi_create_array(env, &ret);
之前分析過(guò)napi_value本質(zhì)上是一個(gè)一級(jí)指針。接著我們看如何使用從napi中拿到的數(shù)組。我們可以通過(guò)napi_set_element設(shè)置數(shù)組的內(nèi)容。
- // ret是數(shù)組，i是索引，num是一個(gè)napi_value變量，本質(zhì)是一個(gè)v8對(duì)象，即索引對(duì)應(yīng)的值
- napi_set_element(env, ret, i, num);
下面我們看看napi_set_element的實(shí)現(xiàn)。
- // 設(shè)置key對(duì)應(yīng)的值，key是數(shù)字
- napi_status napi_set_element(napi_env env,
- napi_value object,
- uint32_t index,
- napi_value value) {
- v8::Local<v8::Context> context = env->context();
- v8::Local<v8::Object> obj;
- // 把napi_value object轉(zhuǎn)成v8的Object，數(shù)組繼承Object
- CHECK_TO_OBJECT(env, context, obj, object);
- // 把值napi_value value轉(zhuǎn)成v8對(duì)象
- v8::Local<v8::Value> val = v8impl::V8LocalValueFromJsValue(value);
- // 調(diào)用v8 Object對(duì)象的Set方法設(shè)置對(duì)象的屬性，即數(shù)組的元素
- auto set_maybe = obj->Set(context, index, val);
- // 執(zhí)行結(jié)果處理
- RETURN_STATUS_IF_FALSE(env, set_maybe.FromMaybe(false), napi_generic_failure);
- return GET_RETURN_STATUS(env);
- }
從上面的分析中，我們大致可以看到napi實(shí)現(xiàn)中的一些規(guī)律，get的api的邏輯是調(diào)用v8接口拿到v8類型的對(duì)象，然后轉(zhuǎn)成napi_value類型返回給調(diào)用方，set的api是傳入napi_value類型，然后轉(zhuǎn)成v8類型的對(duì)象。
napi的實(shí)現(xiàn)幾乎都在js_native_api_v8.cc中，有興趣的同學(xué)可以看一下，大多數(shù)api的實(shí)現(xiàn)并不復(fù)雜，了解js_native_api_v8.cc的實(shí)現(xiàn)，不僅讓我們更好地使用napi，也讓我們更加了解v8的使用和原理。
