Go runtime.AddCleanup 怎样复用已有缓冲空间

如果资源对象已经拿到一块可复用的 []byte，可以把这块缓冲区放进独立清理状态，再用 runtime.AddCleanup 在包装对象失去可达性后把它归还给 sync.Pool。关键不是让 cleanup 代替正常关闭，而是让显式 Close 和 GC 兜底路径共享同一个幂等释放协议。

推荐的边界是：包装对象只持有清理状态，清理状态持有已有缓冲区；cleanup 函数和参数都不能反向持有包装对象。这样可以复用容量，又不会因为闭包捕获或错误的参数设计让对象永远无法回收。

官方接口：https://pkg.go.dev/runtime#AddCleanup

官方说明：https://go.dev/blog/cleanups-and-weak

版本说明：https://go.dev/doc/go1.24

1. 先按负载选择：缓冲区复用是主路径，AddCleanup 只是兜底

这类设计适合短生命周期的编码、拼接或临时消息对象：调用方反复申请大小相近的字节缓冲区，而业务代码可以在正常路径结束时明确归还。缓冲区的“已有空间”指切片背后的容量，不等于每次都保留旧数据；交给下一个使用者前应把长度重置为零。

方案选择可以分成三层：

因此，不能把“注册成功”理解成“缓冲区一定会归还”。生产代码仍然应该让 Close 走主路径，AddCleanup 只覆盖遗漏关闭的场景。

2. 建立引用边界：arg 保存缓冲区，但不能保存包装对象

Go 1.24 的 runtime.AddCleanup 接受包装对象指针、清理函数和清理参数。官方文档特别强调：如果从 cleanup 或 arg 能够到达 ptr，ptr 就可能一直可达，清理也就无法按预期发生；最简单的 arg == ptr 情况还会触发 panic。

本例把可复用缓冲区放进 bufferState。bufferOwner 只保存这个状态和清理句柄，状态不保存 owner 指针，顶层函数也不捕获 owner。这样清理参数可以继续保留缓冲区，直到它被归还池中，但不会形成指回包装对象的路径。

还要把所有权写进接口约定：调用 NewBufferOwner 后，传入的缓冲区不应继续被外部代码写入；调用 Close 后，外部也不能继续使用之前拿到的切片。否则，即使引用关系正确，池化缓冲区也可能被两个使用者同时修改。

3. 推荐架构：从 sync.Pool 取得已有容量并注册兜底清理

下面的例子模拟一个可复用消息缓冲区。构造器优先从池中取出已有容量的切片，拿不到时才创建新切片。清理函数只接收独立状态，不会读取 owner；它在同一个锁保护下标记释放，再把长度为零的切片放回池中。

package main

import (
    "errors"
    "fmt"
    "runtime"
    "sync"
)

var errOwnerClosed = errors.New("缓冲区所有者已关闭")

type bufferState struct {
    mu       sync.Mutex
    pool     *sync.Pool
    buf      []byte
    released bool
}

type bufferOwner struct {
    state   *bufferState
    cleanup runtime.Cleanup
}

func releaseBuffer(s *bufferState) {
    if s == nil {
        return
    }
    s.mu.Lock()
    if s.released {
        s.mu.Unlock()
        return
    }
    // 先摘下缓冲区，再标记释放，避免重复归还同一块空间。
    buf, pool := s.buf[:0], s.pool
    s.buf = nil
    s.released = true
    s.mu.Unlock()
    if pool != nil && buf != nil {
        // 放回池前长度归零，下一位使用者只能看到可用容量。
        pool.Put(buf)
    }
}

func NewBufferOwner(pool *sync.Pool) *bufferOwner {
    var buf []byte
    if pool != nil {
        if value := pool.Get(); value != nil {
            // 池中只接收 []byte，取出后复用原有容量而不是旧长度。
            buf, _ = value.([]byte)
        }
    }
    if buf == nil {
        buf = make([]byte, 0, 1024)
    }
    state := &bufferState{pool: pool, buf: buf[:0]}
    owner := &bufferOwner{state: state}
    // arg 只保存独立状态；cleanup 和 state 都不反向引用 owner。
    owner.cleanup = runtime.AddCleanup(owner, releaseBuffer, state)
    return owner
}

func (o *bufferOwner) Append(text string) error {
    if o == nil || o.state == nil {
        return errOwnerClosed
    }
    o.state.mu.Lock()
    defer o.state.mu.Unlock()
    if o.state.released {
        return errOwnerClosed
    }
    // append 会优先使用已有容量，容量不足时才分配新的底层数组。
    o.state.buf = append(o.state.buf, text...)
    return nil
}

func (o *bufferOwner) Close() {
    if o == nil || o.state == nil {
        return
    }
    // Stop 只取消尚未排队的兜底回调，真正归还仍由 releaseBuffer 完成。
    o.cleanup.Stop()
    releaseBuffer(o.state)
    runtime.KeepAlive(o) // 确保 owner 跨过 Stop 和显式释放区间。
}

func main() {
    pool := &sync.Pool{}
    owner := NewBufferOwner(pool)
    if err := owner.Append("复用已有容量"); err != nil {
        fmt.Println(err)
        return
    }
    owner.Close()
}

这里的“复用”发生在 append 和 sync.Pool 两处：同一个 owner 追加内容时优先沿用原有容量；owner 关闭后，长度被清零的切片可以供下一次构造器取用。示例没有给出容量、分配次数或耗时输出，避免把未运行的推导写成实测数据。

4. 释放协议：Close 与兜底回调必须共享同一状态

显式关闭和 GC 兜底不是两份独立业务逻辑。若 Close 把缓冲区放回池中，而排队中的 cleanup 又放回一次，就可能让同一块底层数组同时出现在池中两次。上例用 released 标志和互斥锁把归还动作收敛到一处。

Cleanup.Stop 的职责只是取消清理调用；如果清理已经排队，Stop 不会替你撤销已排队的执行。因此 Close 必须继续调用 releaseBuffer，而不能把 Stop 当成“释放成功”。在只允许单线程拥有 owner 的简单程序里，也可以用 sync.Once 实现同样的幂等协议；若 Append 和 Close 可能并发，锁还要覆盖缓冲区访问本身。

5. 约束与风险：缓冲区复用不等于生命周期自动化

第一，AddCleanup 是异步且不保证时机的机制。它适合降低忘记 Close 的资源泄漏风险，不适合承担必须在请求返回前完成的提交、刷盘或协议发送。

第二，清理函数可能与业务 goroutine、其他 cleanup 并发运行。上例用锁阻止 Append 在释放后继续修改缓冲区，但调用方仍应遵守“不在 Close 后继续写入”的所有权合同；锁不能替代业务层的生命周期设计。

第三，清理参数会延长缓冲区和状态的存活时间，这是为了让兜底回调能访问它们，不是内存泄漏。真正需要避免的是状态继续反向持有 owner，或 cleanup 闭包捕获 owner。

第四，官方文档还说明：零尺寸对象、包级初始化对象以及某些小对象分配合并场景，不适合用来推断 cleanup 一定执行。不要用强制 GC 加短暂 sleep 伪造生产保证。

6. 落地清单：按所有权、释放和观测分别验收

• 把传入的已有 []byte 视为所有权转移，调用者不再并行写入。
• 让 cleanup 和 arg 都不能通过字段、闭包或方法值返回到 owner。
• 让 Close 作为主路径，先停止兜底句柄，再调用与 cleanup 相同的幂等释放函数。
• 归还池前把切片长度清零，并明确池化缓冲区不能在 Close 后继续使用。
• 为 Append、Close 和清理回调定义并发合同；不要只因为有互斥锁就宣称所有调用顺序都安全。
• 分别观测创建数量、显式关闭数量、实际归还数量和仅由兜底路径处理的数量；不要把这些指标混成一个数字。

runtime.AddCleanup 能保证缓冲区最终回到 sync.Pool 吗？

不能。回调不保证一定在进程退出前运行，且对象必须满足清理引用边界。sync.Pool 本身也不承诺元素永久保留，所以它只能作为临时复用池。

可以把 owner 直接作为 cleanup 的参数吗？

不建议，也可能触发运行时保护。cleanup 参数应保存释放缓冲区所需的独立状态，而不是保存会让 owner 继续可达的对象。

Close 后还能读取之前的 []byte 吗？

不应该。缓冲区已经可能被清零并重新交给池中其他使用者，读取旧切片会违反所有权合同；需要保留结果时应先复制。