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

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

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

【運(yùn)行】不導(dǎo)致原生模塊程序崩潰— 精讀每一版changelogs清單和微調(diào)原生模塊源碼更耗時費(fèi)力。

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

名詞解釋

nodejs c-addon

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

接入nodejs的JS VM，并

與nodejs交換數(shù)據(jù)·互操作。

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

JS堆對象

它既包括由JS程序自身構(gòu)造的對象實(shí)例，也包含由系統(tǒng)程序從addon內(nèi)調(diào)用N-API接口（比如，napi_create_object()）實(shí)例化的JS對象。它們都

被保存在JS VM的堆內(nèi)存中，和

被Rust棧內(nèi)存中的napi_value可修改原始指針引用。

N-API引用計(jì)數(shù)

它是指向JS堆對象的“FFI引用計(jì)數(shù)”智能指針（后文有圖，應(yīng)該會更直觀些）。其

被保存于JS VM的堆內(nèi)存中，和

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

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

WASM墊片程序

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

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

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

“裸奔的”原始指針

簡陋的Rust Bindings— 與C頭文件概念對等的Rust語言項(xiàng)

“安慰劑”式的宏編程工具。因?yàn)槿狈α薺s墊片程序的協(xié)同呼應(yīng)，幾個Rust宏也只是杯水車薪，能“糖”的內(nèi)容很少。

轉(zhuǎn)移更多精力從【業(yè)務(wù)邏輯實(shí)現(xiàn)】至【FFI編程】，并與各種FFI技術(shù)細(xì)節(jié)做“斗爭”。趕快補(bǔ)課內(nèi)存布局理論知識去吧！

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

static全局緩存JS堆對象。而不必?fù)?dān)心僅活躍于addon的JS堆對象會被JS VM的GC回收。

相對FFI函數(shù)的單次調(diào)用執(zhí)行周期，延長JS堆對象的生命周期。

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

相對FFI函數(shù)的單次調(diào)用執(zhí)行周期，縮短JS堆對象的生命周期

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

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

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

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

N-API JS堆對象生命周期管理的技術(shù)細(xì)節(jié)

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

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

N-API引用計(jì)數(shù)智能指針不智能

沒有RAII Guard對活躍引用數(shù)量的自動跟蹤。@Rustacean 還需書面編寫N-API接口調(diào)用和人工增減引用個數(shù)跟蹤引用復(fù)本數(shù)量 — 這是傳統(tǒng)的缺陷產(chǎn)出“大戶”。

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