N-API的JS堆對象生命周期管理

N-API是Node API的簡寫，同時也是nodejs的JS VM（鏈）接入原生模塊.node文件的應用程序二進制接口(i.e. ABI)。借助N-API引入的抽象隔離，升級nodejs運行時（虛擬機）

【編譯】不要求對原生擴展模塊重新編譯— 為nodejs的不同版本分別準備不同的原生模塊build真的好麻煩。

【運行】不導致原生模塊程序崩潰— 精讀每一版changelogs清單和微調原生模塊源碼更耗時費力。

N-API開放接口在nodejs 10+后才逐步穩定，和成為nodejs c-addon的主流編程標準。 不久前，我有機會在工程實踐中獨立完成“給node-webkit容器編寫原生擴展模塊的”程序開發任務。雖然擴展模塊自身的業務處理邏輯很簡單 — 餒餒的“膠水”代碼，但其涉及到了跨越多個FFI接口調用的JS對象緩存處理。初版程序緩存不住JS堆內存中的變量值，因為JS VM的GC總是在FFI接口調用的間隙回收由原生模塊緩存的JS對象和導致程序崩潰。由此，我特意“死磕”C/C++ addons with Node-API廠方文檔，在解決工程難題的同時匯總實踐收獲寫下此文。 文章以名詞解釋統一術語理解開篇，以對比不同版本ABI標準引題，以技術細節展開討論為依據，最后向讀者圖文并茂地描述我個人創新的實踐方案。

名詞解釋

nodejs c-addon

nodejs原生擴展模塊。所謂“原生”是相對JS模塊而言的。它必須由【系統編程語言C / Cpp / Rust】編寫，并經由nodejs開放接口N-API，

接入nodejs的JS VM，并

與nodejs交換數據·互操作。

為了文字簡練，下文也將其記作為addon。 nodejs c-addon與Commonjs Module在科技樹上處于相同的生態位，和對“上游”調用端的JS業務代碼呈現一致的調用方式。

JS堆對象

它既包括由JS程序自身構造的對象實例，也包含由系統程序從addon內調用N-API接口（比如，napi_create_object()）實例化的JS對象。它們都

被保存在JS VM的堆內存中，和

被Rust棧內存中的napi_value可修改原始指針引用。

N-API引用計數

它是指向JS堆對象的“FFI引用計數”智能指針（后文有圖，應該會更直觀些）。其

被保存于JS VM的堆內存中，和

被Rust棧內存中的napi_ref可修改原始指針引用。即，addon端Rust程序拿到的是指向了“智能指針”的“指針”。

被用于阻止JS VM的GC回收正活躍于addon端的JS堆對象。這就賦予了 @Rustacean 從JS VM外部干預JS對象生命周期的能力。React Native可都做不到這一點。

WASM墊片程序

它既包括由wasm-bindgen-cli生成的JS墊片程序文件，也包含由wasm-bindgen crate導出的Rust開發框架。正是js <-> Rust兩端墊片程序的協同配合，JS堆對象才幾乎被“投影為”Rust所有權（棧）變量。比如，JS堆對象的wasm_bindgen::JsValue（似智能指針）結構體就比nj_sys::napi_value可修改原始指針更能發揮Rust類型系統與Borrow / Drop Checker對程序正確性的保障力。沒有“黑魔法”，滿眼都是對墊片程序開發迭代的工作量。

WASM vs. N-API堆對象生命周期管理策略

簡單地講，生命周期策略的差異取決于【墊片程序】的“薄/厚”。因為WASM應用場景多（包括但不限于：網頁、nodejs，wasm-runtime獨立虛擬機），社區關注度高，wasm-bindgen工具鏈迭代速度快，所以，wasm <-> js墊片程序就“厚”。JS堆對象向Rust的“投影”就更像【智能指針】，而不是“裸奔的”原始指針。WebAssembly工作組甚至規劃將墊片程序逐步“固化”至wasm-runtime內（比如，TC39弱引用提案與引用類型提案等）以完備核心功能。工作量到位自然對接平滑！這不是黑魔法，而是真金白銀的血汗努力。 相反，nodejs c-addon的應用場景就要少得多了。所以，技術社區鮮有熱情面向N-API開放接口編寫功能豐富的addon <-> js墊片程序。于是，@Rustacean 不得不直面

“裸奔的”原始指針

簡陋的Rust Bindings— 與C頭文件概念對等的Rust語言項

“安慰劑”式的宏編程工具。因為缺乏了js墊片程序的協同呼應，幾個Rust宏也只是杯水車薪，能“糖”的內容很少。

轉移更多精力從【業務邏輯實現】至【FFI編程】，并與各種FFI技術細節做“斗爭”。趕快補課內存布局理論知識去吧！

具體地講，在Rust - WASM程序上下文中，披上了“智能指針”馬甲的JS堆對象幾乎完全“銹化”了。@Rustacean 可忽視JS VM垃圾收集器的干擾和：

static全局緩存JS堆對象。而不必擔心僅活躍于addon的JS堆對象會被JS VM的GC回收。

相對FFI函數的單次調用執行周期，延長JS堆對象的生命周期。

{ .. }塊作用域限定JS堆對象，按需釋放不再訪問的變量值，提高內存利用效率。就有多局部變量的大函數而言，這可明顯地降低JS堆內存占用的瞬時峰值。

相對FFI函數的單次調用執行周期，縮短JS堆對象的生命周期

另一方面，N-API沒有功能面面俱到的墊片程序。所以，@Rustacean 做不到僅憑Rust基本語法項就對FFI另一端的JS堆對象執行【全局緩存】或【塊作用域】按需回收的程序處理。甚至（重點來了），即便JS端代碼刻意保留了已FFI導出堆對象的引用，addon端（棧內存）所持有的原始指針依舊會，在FFI函數執行之后，丟失其原本指向的值和成為“野”指針。我懷疑JS VM就算沒有回收也至少挪動了被導出JS堆對象的內存位置。由此，@Rustacean 需要在addon業務代碼中額外實現部分本該由墊片程序完成的“公共服務”功能，包括但不限于：

徒手維護N-API引用計數智能指針，以“鎖住”JS堆對象不被JS VM的GC回收 —延長JS堆對象的生命周期。

調用N-API程序接口構造可層疊嵌套的作用域【塊】 —縮短JS堆對象的生命周期。

這的確是一次接觸底層“自己動手豐衣足食”的機會，但絕對不是什么令人愉快的開發體驗。千言萬語匯聚一張圖（左側WASM，右側nodejs c-addon）促成讀者思緒的豁然開朗：

N-API JS堆對象生命周期管理的技術細節

addon對JS堆對象生命周期的管理分為如下三種情況（看圖吧，一圖抵千詞）：

由上圖可見，真實數據被保存于JS端（堆）內存中。Rust端（棧）內存僅持有隨時可能失效的原始指針。所以，@Rustacean 需要調用特定的N-API接口，遠程操控JS堆對象的活躍周期。但是，N-API接口并不易用。這表現為...

N-API引用計數智能指針不智能

沒有RAII Guard對活躍引用數量的自動跟蹤。@Rustacean 還需書面編寫N-API接口調用和人工增減引用個數跟蹤引用復本數量 — 這是傳統的缺陷產出“大戶”。

零引用數量不意味著GC回收。@Rustacean 還需顯式地析構掉N-API【引用計數】智能指針實例，才能促使被“持久化于內存”的JS堆對象接受GC回收。否則，內存泄漏！具體作法請參見如下偽碼