Node-API的數(shù)據(jù)類型

napi_status

是一個(gè)枚舉數(shù)據(jù)類型冬骚，表示Node-API接口返回的狀態(tài)信息矾踱。

每當(dāng)調(diào)用一個(gè)Node-API函數(shù)蓬推，都會(huì)返回該值婴渡，表示操作成功與否的相關(guān)信息济炎。

typedef enum {
    napi_ok,
    napi_invalid_arg,
    napi_object_expected,
    napi_string_expected,
    napi_name_expected,
    napi_function_expected,
    napi_number_expected,
    napi_boolean_expected,
    napi_array_expected,
    napi_generic_failure,
    napi_pending_exception,
    napi_cancelled,
    napi_escape_called_twice,
    napi_handle_scope_mismatch,
    napi_callback_scope_mismatch,
    napi_queue_full,
    napi_closing,
    napi_bigint_expected,
    napi_date_expected,
    napi_arraybuffer_expected,
    napi_detachable_arraybuffer_expected,
    napi_would_deadlock, /* unused */
    napi_no_external_buffers_allowed,
    napi_cannot_run_js
} napi_status;

napi_extended_error_info

一個(gè)結(jié)構(gòu)體川抡，在調(diào)用函數(shù)不成功時(shí)存儲(chǔ)了較為詳細(xì)的錯(cuò)誤信息。

typedef struct {
    const char *error_message;
    void *engine_reserved;
    uint32_t engine_error_code;
    napi_status error_code;
} napi_extended_error_info;

napi_value

在C++代碼中，表示一個(gè)JavaScript值崖堤。

napi_env

• 用于表示Node-API執(zhí)行時(shí)的上下文侍咱，Native側(cè)函數(shù)入?yún)ⅲ鬟f給函數(shù)中的Node-API接口密幔。

• 退出Native側(cè)插件時(shí)楔脯，napi_env將失效，該事件通過回調(diào)傳遞給napi_add_env_cleanup_hook和napi_set_instance_data胯甩。

• 禁止緩存napi_env昧廷，禁止在不同Worker中傳遞napi_env。

napi_threadsafe_function

napi_threadsafe_function用來創(chuàng)建一個(gè)線程安全的JavaScript函數(shù)偎箫，可以在不同的線程中調(diào)用木柬。可以用于將異步操作的結(jié)果傳遞給JavaScript環(huán)境淹办，例如從另一個(gè)線程中讀取數(shù)據(jù)或執(zhí)行計(jì)算密集型操作眉枕。此外，它還可以用于從JavaScript環(huán)境中調(diào)用C++代碼中的函數(shù)娇唯，以便在另一個(gè)線程中執(zhí)行。通過使用napi_threadsafe_function寂玲，可以實(shí)現(xiàn)JavaScript和C++之間的高效通信塔插，同時(shí)保持線程安全性。

napi_threadsafe_function_release_mode

該枚舉類型定義了兩個(gè)常量拓哟，用于指定在何時(shí)釋放線程安全函數(shù)的回調(diào)函數(shù)想许。

typedef enum {
  napi_tsfn_release,
  napi_tsfn_abort
} napi_threadsafe_function_release_mode;

該值會(huì)傳給napi_release_threadsafe_function。

napi_release_threadsafe_function(napi_threadsafe_function func,
                                 napi_threadsafe_function_release_mode mode);

• mode值為napi_tsfn_release時(shí)：表示當(dāng)前線程不再調(diào)用此tsfn断序。

• mode值為napi_tsfn_abort時(shí)：表示除了當(dāng)前線程流纹，其他線程不能再調(diào)用此tsfn。 如果設(shè)置為napi_tsfn_abort违诗，利用napi_call_threadsafe_function接口調(diào)用此tsfn時(shí)將返回napi_closing漱凝，tsfn函數(shù)并不會(huì)被放入queue中。

napi_threadsafe_function_call_mode

該枚舉類型定義了兩個(gè)常量诸迟，用于指定線程安全函數(shù)的調(diào)用模式茸炒。

數(shù)據(jù)結(jié)構(gòu)如下所示：

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode;

• napi_tsfn_nonblocking：napi_call_threadsafe_function是非阻塞的，如果隊(duì)列已滿阵苇，則返回napi_queue_full壁公，從而阻止數(shù)據(jù)添加到隊(duì)列中。

• napi_tsfn_blocking：napi_call_threadsafe_function是阻塞的绅项，直至隊(duì)列中有空間可用紊册。

內(nèi)存管理類型

Node-API包含以下內(nèi)存管理類型：

napi_handle_scope

napi_handle_scope數(shù)據(jù)類型是用來管理JavaScript對象的生命周期的。它允許JavaScript對象在一定范圍內(nèi)保持活動(dòng)狀態(tài)快耿，以便在JavaScript代碼中使用囊陡。在創(chuàng)建napi_handle_scope時(shí)芳绩，所有在該范圍內(nèi)創(chuàng)建的JavaScript對象都會(huì)保持活動(dòng)狀態(tài)，直到結(jié)束关斜。這樣可以避免在JavaScript代碼中使用已經(jīng)被釋放的對象示括，從而提高代碼的可靠性和性能。

napi_escapable_handle_scope

• 由napi_open_escapable_handle_scope接口創(chuàng)建痢畜，由napi_close_escapable_handle_scope接口關(guān)閉垛膝。

• 表示一種特殊類型的句柄范圍，用于將在escapable_handle_scope范圍內(nèi)創(chuàng)建的值返回給父scope丁稀。

• 用于napi_escape_handle接口吼拥，將escape_handle_scope提升到JS對象，以便在外部作用域使用线衫。

napi_ref

指向napi_value凿可，允許用戶管理JavaScript值的生命周期。

napi_type_tag

該結(jié)構(gòu)體定義了一個(gè)包含兩個(gè)無符號(hào)64位整數(shù)的類型標(biāo)簽授账，用于標(biāo)識(shí)一個(gè)Node-API值的類型信息枯跑。

typedef struct {
  uint64_t lower;
  uint64_t upper;
} napi_type_tag;

• 存儲(chǔ)了兩個(gè)無符號(hào)64位整數(shù)的128位值，用它來標(biāo)記JavaScript對象白热，確保它們屬于某種類型敛助。

• 比napi_instanceof更強(qiáng)的類型檢查，如果對象的原型被操縱屋确，napi_instanceof可能會(huì)報(bào)告誤報(bào)纳击。

• type_tag與napi_wrap結(jié)合非常有用，因?yàn)樗_保從包裝對象檢索的指針可以安全地轉(zhuǎn)換為與先前應(yīng)用于JavaScript對象的類型標(biāo)記相對應(yīng)的Native類型攻臀。

napi_async_cleanup_hook_handle

napi_async_cleanup_hook_handle用于注冊異步操作的回調(diào)函數(shù)焕数。它主要用于在異步操作完成或被取消時(shí)執(zhí)行清理操作，例如釋放資源或撤銷操作刨啸。使用napi_async_cleanup_hook_handle可以確保在異步操作完成或被取消時(shí)堡赔，相關(guān)資源得到正確的釋放和清理，從而避免內(nèi)存泄漏等問題设联。

回調(diào)類型

Node-API包含以下回調(diào)類型：

napi_callback_info

Native側(cè)獲取JS側(cè)參數(shù)信息加匈，傳遞給napi_get_cb_info，用于獲取JS側(cè)入?yún)⑿畔ⅰ?/p>

napi_callback

表示用戶定義的Native函數(shù)仑荐，暴露給JavaScript雕拼，即JS側(cè)調(diào)用的接口；一般不在此callback中創(chuàng)建handle或者callback scope粘招。

基本用法如下：

typedef napi_value (*napi_callback)(napi_env, napi_callback_info);

napi_finalize

函數(shù)指針啥寇，用于傳入napi_create_threadsafe_function和napi_set_instance_data接口。napi_finalize在對象被回收時(shí)會(huì)被調(diào)用。

napi_async_execute_callback

函數(shù)指針辑甜，用于napi_create_async_work接口衰絮。

• 異步執(zhí)行的Native函數(shù)，從工作池線程調(diào)用磷醋，可與主事件循環(huán)線程并行執(zhí)行猫牡。

• 函數(shù)實(shí)現(xiàn)中必須避免執(zhí)行JavaScript或與JavaScript對象交互的Node-API調(diào)用。

• Node-API調(diào)用可以在napi_async_complete_callback中執(zhí)行邓线。

napi_async_complete_callback

napi_async_complete_callback用于異步操作完成后的回調(diào)淌友。當(dāng)需要進(jìn)行異步操作時(shí)，可以使用napi_create_async_work函數(shù)創(chuàng)建一個(gè)異步操作任務(wù)骇陈，并指定一個(gè)napi_async_complete_callback回調(diào)函數(shù)震庭，在異步操作完成后會(huì)自動(dòng)調(diào)用該回調(diào)函數(shù)，以便進(jìn)行后續(xù)的處理你雌。該回調(diào)函數(shù)的參數(shù)包括當(dāng)前異步操作任務(wù)的狀態(tài)和返回值等信息器联，可以根據(jù)這些信息進(jìn)行相應(yīng)的處理。

napi_threadsafe_function_call_js

函數(shù)指針婿崭，在主線程中與獨(dú)立線程中的JavaScript代碼進(jìn)行交互拨拓，從而實(shí)現(xiàn)更加復(fù)雜的功能，用于napi_create_threadsafe_function(napi_env env,…,napi_threadsafe_function_call_js call_js_cb,...)接口氓栈。

napi_cleanup_hook

函數(shù)指針渣磷，用于napi_add_env_cleanup_hook接口，當(dāng)環(huán)境銷毀時(shí)會(huì)被執(zhí)行颤绕。

napi_async_cleanup_hook

函數(shù)指針幸海，用于napi_add_async_cleanup_hook接口祟身，當(dāng)環(huán)境銷毀時(shí)會(huì)被執(zhí)行奥务。

調(diào)度優(yōu)先級

QoS決定了線程調(diào)度的優(yōu)先級，等級定義如下：

typedef enum {
  napi_qos_background = 0,
  napi_qos_utility = 1,
  napi_qos_default = 2,
  napi_qos_user_initiated = 3,
} napi_qos_t;

事件循環(huán)模式

napi提供了運(yùn)行底層事件循環(huán)的兩種模式, 其定義如下：

typedef enum {
    napi_event_mode_default = 0,
    napi_event_mode_nowait = 1,
} napi_event_mode;

支持的Node-API接口

Node-API接口在Node.js提供的原生模塊基礎(chǔ)上擴(kuò)展浇垦，目前支持部分接口，具體可見下文荣挨。

異步安全線程相關(guān)

buffer相關(guān)

string相關(guān)

date相關(guān)

arraybuffer相關(guān)

module相關(guān)

生命周期相關(guān)

promise相關(guān)

array相關(guān)

primitive相關(guān)

class相關(guān)

object相關(guān)

bigint相關(guān)

異常和錯(cuò)誤相關(guān)

屬性相關(guān)

異步任務(wù)相關(guān)

自定義異步操作

判斷給定的兩個(gè)JS value是否嚴(yán)格相等

uv相關(guān)

函數(shù)調(diào)用

擴(kuò)展能力

napi_queue_async_work_with_qos

napi_status napi_run_script_path(napi_env env,
                                 const char* abcPath,
                                 napi_value* result);

用法同napi_queue_async_work碾篡，但可以指定QoS等級虱而。

napi_run_script_path

napi_status napi_run_script_path(napi_env env,
                                 const char* abcPath,
                                 napi_value* result);

napi_load_module

napi_status napi_load_module(napi_env env,
                             const char* path,
                             napi_value* result);

napi_create_object_with_properties

napi_status napi_create_object_with_properties(napi_env env,
                                               napi_value* result,
                                               size_t property_count,
                                               const napi_property_descriptor* properties);

napi_create_object_with_named_properties

napi_status napi_create_object_with_named_properties(napi_env env,
                                                     napi_value* result,
                                                     size_t property_count,
                                                     const char** keys,
                                                     const napi_value* values);

napi_coerce_to_native_binding_object

napi_status napi_coerce_to_native_binding_object(napi_env env,
                                                 napi_value js_object,
                                                 napi_native_binding_detach_callback detach_cb,
                                                 napi_native_binding_attach_callback attach_cb,
                                                 void* native_object,
                                                 void* hint);  

napi_run_event_loop

napi_status napi_run_event_loop(napi_env env, napi_event_mode mode);

napi_stop_event_loop

napi_status napi_stop_event_loop(napi_env env);

環(huán)境生命周期

對象生命周期管理

ArkTs基礎(chǔ)運(yùn)行時(shí)環(huán)境

其他實(shí)用工具

寫在最后

• 如果你覺得這篇內(nèi)容對你還蠻有幫助峦耘，我想邀請你幫我三個(gè)小忙：
• 點(diǎn)贊剔蹋，轉(zhuǎn)發(fā)，有你們的 『點(diǎn)贊和評論』辅髓，才是我創(chuàng)造的動(dòng)力泣崩。
• 關(guān)注小編，同時(shí)可以期待后續(xù)文章ing??洛口，不定期分享原創(chuàng)知識(shí)矫付。
• 想要獲取更多完整鴻蒙最新學(xué)習(xí)知識(shí)點(diǎn)，請移步前往小編：https://gitee.com/MNxiaona/733GH/blob/master/jianshu