如何让Lua垃圾回收器感知外部堆内存占用？

问题背景 #

我们有一个C图像库my_image_library，提供以下接口：

image* image_new_from_file(const char* path);
void image_free(image*);

对应的Lua绑定代码将图像指针封装在my_image_t结构体的userdata中：

typedef struct my_image_t {
  image* inner;
} my_image_t;

int lua_image_new_from_file(lua_State* L) {
  my_image_t* img = lua_newuserdata(L, sizeof(my_image_t));
  const char* path = lua_tostring(L, 1);
  img->inner = image_new_from_file(path);
  // 已设置带__gc元方法的元表，用于释放inner指针
  return 1;
}

此时Lua GC仅统计userdata本身的8字节（指针大小），但图像实际占用的外部堆内存可达数十MB，大量创建释放对象时会导致GC触发不及时，外部内存堆积。

可行解决方案 #

1. 手动向GC报告外部内存占用（推荐） #

Lua 5.2+提供lua_gc的LUA_GC_ADJUST选项，可手动调整GC的内存统计值，让GC感知到外部内存的实际占用。

修改绑定代码：

首先扩展my_image_t结构体，存储图像实际内存大小：

typedef struct my_image_t {
  image* inner;
  size_t actual_size; // 记录图像实际占用的内存字节数
} my_image_t;

然后修改创建函数，获取图像大小并告知GC：

int lua_image_new_from_file(lua_State* L) {
  my_image_t* img = lua_newuserdata(L, sizeof(my_image_t));
  const char* path = lua_tostring(L, 1);
  img->inner = image_new_from_file(path);
  
  // 获取图像实际内存大小：
  // 方式1：如果C库提供获取接口
  img->actual_size = image_get_size(img->inner);
  // 方式2：自行计算（假设image结构体包含width/height/channels字段）
  // img->actual_size = img->inner->width * img->inner->height * img->inner->channels * sizeof(uint8_t);
  
  // 向GC追加统计的内存大小
  lua_gc(L, LUA_GC_ADJUST, img->actual_size);
  
  // 绑定元表（需提前注册带有__gc方法的元表）
  luaL_setmetatable(L, "my_image_mt");
  return 1;
}

最后修改__gc元方法，在释放图像后调整GC统计：

int lua_image_gc(lua_State* L) {
  my_image_t* img = lua_touserdata(L, 1);
  if (img->inner) {
    // 从GC统计中减去释放的内存
    lua_gc(L, LUA_GC_ADJUST, -img->actual_size);
    image_free(img->inner);
    img->inner = NULL;
  }
  return 0;
}

该方案无需修改C库，避免了内存复制，能让GC准确感知实际内存负载，及时触发回收。

2. 使用Lua自定义内存分配器 #

如果可以修改C库代码，将image_new_from_file中的内存分配替换为Lua的分配器（通过lua_getallocf获取），这样GC会自动统计这部分内存。但该方案侵入性强，仅适用于能修改C库的场景。

3. 手动触发GC（简易方案） #

如果上述方案无法实现，可在Lua层定期强制触发GC。比如每创建N张图像后调用collectgarbage()，或在业务逻辑的空闲节点触发：

local count = 0
function load_image(path)
  count = count + 1
  local img = my_image_library.new_from_file(path)
  if count % 100 == 0 then
    collectgarbage()
  end
  return img
end

该方案简单但不够自动化，依赖业务逻辑控制。

不推荐的方案 #

将image* inner改为image inner直接复制结构体的方式，会导致双重内存分配与复制，效率低下；若image结构体内部包含指向其他堆内存的指针（如像素数据），GC仍无法统计到这部分内存，因此不建议使用。

内容的提问来源于stack exchange，提问作者Lucas S.