Lua upvalue：延时回调自己注销自己的秘密

【语法算法】
一、先抛一个坑

写过延时回调的人一定见过这种两段式：先 local handle 声明，再把注册函数的返回值赋给它，而回调体里又引用了这个 handle。问题来了——scheduleScriptFunc 注册的那一刻，handle 还是 nil，回调函数却要在未来某次触发时读到它的真值。这段代码为什么能跑起来？答案是：upvalue 捕获的是变量本身，不是变量某一刻的值。

二、底层原理：upvalue 的开放与封闭

Lua 编译器为每个被内层函数引用的外层局部变量生成一个 upvalue。外层作用域还在栈上时，upvalue 处于"开放"状态，直接指向栈帧上那个槽位，内外读写的是同一个格子；外层函数返回、栈帧回收时，upvalue "封闭"——把值拷进自己私有的存储，从此这个变量由闭包独占托管。所以注册时 handle 为 nil 没关系：scheduleScriptFunc 返回的瞬间，返回值被写进同一个槽位；未来回调触发，读到的就是注册完成后的句柄。一个变量，越过"创建它的函数已退场"继续存活，这就是 upvalue 的全部秘密。

flowchart TD
    A["local handle 声明<br/>栈上开槽，初值 nil"] --> B["scheduleScriptFunc 注册闭包<br/>闭包把 handle 捕为 upvalue（开放态）"]
    B --> C["注册函数返回<br/>句柄写回同一槽位"]
    C --> D["外层函数退场<br/>栈帧回收，upvalue 封闭"]
    D --> E["未来某帧回调触发<br/>闭包读到封闭前的句柄真值"]

三、正确写法：自销毁延时器

function PerformWithDelayGlobal(listener, time)
    local handle
    handle =
        global.Scheduler:scheduleScriptFunc(
        function()
            -- 先注销自己，再执行回调，天然免疫重入
            global.Scheduler:unscheduleScriptEntry(handle)
            listener()
        end,
        time,
        false
    )
    return handle
end

四、这 13 行里的三个设计

1. 先注销再执行。unscheduleScriptEntry 放在 listener() 之前，回调里无论再注册什么新定时器，都不会与旧条目互相纠缠；执行完即焚，调度器里不留尸体。

1. 句柄照常外传。调用方拿到返回的 handle，仍可在到期前手动 UnSchedule 取消——自销毁与外部取消两条路并存，互不冲突。

1. 忘记注销的事故长什么样：界面只隐藏不移除，schedule 条目每帧空转；玩家连开几十个面板，帧时间被几百个僵尸回调吃掉，表现为"越玩越卡、重启恢复"。调度条目由引擎 C 侧持有，GC 看不见它，只有显式 unschedule 才能断开。

五、内存视角的收口

闭包 = 函数原型 + upvalue 表。upvalue 按引用共享：两个闭包捕获同一个局部变量，封的是同一份存储，一边写另一边读得到。这意味着闭包是隐式的长生命周期引用——被 upvalue 拽住的对象，比它的创建者活得更久；排查"面板销毁了、对象却不回收"，第一件事就是查有没有回调闭包把它捕获进 upvalue。让延时器自己注销自己，既是功能设计，也是内存纪律：每一条定时器都该有一个确定的终点，要么触发即焚，要么显式取消，没有第三种状态。