Lua 與 C++ 交互深度解析（一）：虛擬堆棧核心機制

理解 Lua 與 C/C++ 交互的第一步，是徹底掌握虛擬堆棧機制。這是 Lua 設計的核心：Lua 與宿主語言不直接共享內存對象，而是通過一個「無處不在」的虛擬堆棧作為唯一通信介質。本文深度解析堆棧索引模型、內存佈局、數據類型統一表示、以及垃圾回收交互邊界。

一、堆棧為何物？

• 定義：一個結構體數組 TValue stack[max_stack_len]，在 lua_State 創建時分配（見 lstate.c stack_init）
• 特性：先進後出（LIFO），但支持隨機索引訪問
• 角色：所有 Lua 值（數值、字符串、表、函數、userdata、線程等）在 C API 層面均通過堆棧傳遞

二、雙向索引體系

• 正數索引：從棧底（1）向上，1, 2, 3... top
• 負數索引：從棧頂（-1）向下，-1, -2, -3... -top
• 轉換公式：正索引 = 負索引 + top + 1
• 優勢：負索引天然適配「棧頂相對定位」，編寫通用函數時極其方便

三、統一值表示：TValue 結構

Lua 實現動態類型的關鍵：值與類型標籤綁定。

// 簡化版 TValue 結構
typedef struct TValue {
    Value value;  // 聯合體：存儲實際數據
    int tt;       // 類型標籤：LUA_TNIL, LUA_TBOOLEAN, LUA_TNUMBER...
} TValue;

typedef union Value {
    void* p;           // light userdata
    lua_Number n;      // 數值（double/float）
    int b;             // 布爾值（0/1）
    GCObject* gc;      // 所有需 GC 管理的對象：string, table, closure, userdata, thread, proto, upvalue
} Value;

3.1 類型分類與內存語義

核心結論：

1. 值類型：nil、boolean、number、light userdata —— 直接內嵌棧槽，無堆分配，無 GC 開銷
2. 引用類型：string、table、closure、userdata、thread —— 棧槽僅存指針，對象在堆上，受 GC 管理

四、堆棧操作的語義模型

4.1 C → Lua（壓入）：創建並綁定

所有 lua_push* 族函數均具備「創建 Lua 值並壓入棧頂」語義：

• lua_pushnumber(L, 5)：修改棧頂槽，tt = LUA_TNUMBER, value.n = 5
• lua_pushstring(L, "str")：Lua 內部創建 TString 對象（含內容拷貝/驻留），棧頂綁定其指針
• lua_pushcclosure(L, func, 0)：創建 Closure 對象封裝 C 函數指針
• lua_createtable(L, 0, 0)：創建 Table 對象

關鍵點：一旦壓入，該值進入 Lua 世界，生命周期完全由 Lua 管理，C 端不再持有所有權。

4.2 Lua → C（取出）：類型轉換與拷貝

lua_to* 族函數僅支持有 C 對應類型的值：

• lua_tonumber / lua_tointeger / lua_toboolean / lua_tostring / lua_topointer
• 無 lua_totable、lua_toclosure 等——引用類型無法直接「取出」，只能通過 API 間接操作

取出時實際上是從 TValue 讀取並轉換為 C 原生類型，不影響堆上對象。

五、實戰驗證：構造圖示棧狀態

執行以下代碼可復現文檔中的棧示意圖：

lua_State* L = luaL_newstate();

// 1. 壓入閉包
lua_pushcclosure(L, my_c_func, 0);  // stack[1] = closure

// 2. 壓入表
lua_createtable(L, 0, 0);           // stack[2] = table

// 3. 壓入數值
lua_pushnumber(L, 343);             // stack[3] = number

// 4. 壓入字符串
lua_pushstring(L, "mystr");         // stack[4] = string

// 當前棧頂索引 = 4，棧底 = 1
// 結構完全對應文檔圖示：closure, table, number, string

六、GC 邊界與所有權轉移

• C 創建值 → 壓入棧：所有權轉移給 Lua，Lua 負責 GC（字符串驻留、表/閉包/用戶數據跟蹤）
• Lua 值 → C 取出：不轉移所有權，C 獲得的是拷貝（基本類型）或非持有引用（指針類型）
• light userdata：特例，裸指針無 GC，C 需自行管理指向內存的生命周期
• 棧清理：lua_pop/lua_settop 彈出值時，僅移除棧槽引用，不直接銷毀堆對象（由 GC 掃描決定）

七、總結

虛擬堆棧是 Lua 與 C/C++ 交互的契約介面：

1. 統一值表示：TValue = {值, 類型標籤} 實現動態類型
2. 雙向索引：正負索引靈活定位，適配棧頂相對操作
3. 類型分層：值類型內嵌棧槽，引用類型棧存指針堆存對象
4. 所有權邊界：壓入 = 移交所有權給 Lua GC；取出 = 讀取拷貝/非持有引用
5. 通信協議：所有 API 操作均圍繞棧展開，保證 Lua 內部一致性

徹底理解上述機制，是編寫正確、高效、無內存泄漏的 Lua-C++ 綁定代碼的前提。下一篇將詳細講解具體堆棧操作 API 族與實戰模式。