OnceFunc 怎样保证并发关闭逻辑只执行一次

sync.OnceFunc 的做法是把一个固定的无参函数包装成新的函数，所有 goroutine 都调用这个同一个包装函数。第一次调用负责执行关闭回调；并发到达的其他调用会等待这次回调结束，之后直接返回，不会再次关闭资源。

它适合“同一个对象可能从多个出口触发关闭，但底层关闭动作只能执行一次”的场景，例如连接、订阅、后台循环或停止通知。需要注意：OnceFunc 只保护传入的关闭回调，不会自动阻止其他方法继续使用资源，也不会在关闭失败后重试。

先确认 OnceFunc 保护的是什么

OnceFunc 保护的是传给它的那一个函数调用。它内部使用一次性状态，因此回调只会运行一次；同时，首次执行未结束前，其他调用者不会提前越过关闭边界。这个“等待首次调用完成”的语义，比只用一个原子布尔值抢占执行权更完整。

但它没有扩大资源本身的并发保证。假设一个 goroutine 正在读连接，另一个 goroutine 调用关闭函数，读操作如何结束仍由该连接类型、Context 或你自己的生命周期协议决定。OnceFunc 只解决“关闭回调不要重复执行”，不解决“关闭与所有在途工作如何协调”。

四种方案先按约束比较

并发关闭并不是 API 越短越好，选择时先看回调是否固定、是否需要返回错误、失败后是否允许重试，以及资源是否已经有唯一所有者。

如果关闭动作完全固定，OnceFunc 通常比“结构体里放一个 sync.Once，每次再写一遍匿名函数”更不容易传错回调。若现有对象已经有清晰的单所有者事件循环，让所有者负责关闭通常比新增共享同步状态更自然。

在构造函数里冻结关闭回调

下面把底层 io.Closer 和停止通知封装进一个业务对象。Close 方法不再决定执行什么，只转调构造时创建的同一个 closeOnce。

package lifecycle

import (
    "io"
    "sync"
)

type Service struct {
    closer    io.Closer
    stopped   chan struct{}
    closeOnce func()
}

func NewService(closer io.Closer) *Service {
    s := &Service{
        closer:  closer,
        stopped: make(chan struct{}),
    }

    // 在构造阶段冻结关闭动作，后续所有调用者共享同一个包装函数。
    s.closeOnce = sync.OnceFunc(func() {
        // 关闭通知通道只能发生一次，否则重复 close 会触发 panic。
        close(s.stopped)

        // OnceFunc 没有返回值；这里只把底层关闭视为不可重试动作。
        _ = s.closer.Close()
    })
    return s
}

func (s *Service) Close() {
    // 多个 goroutine 可以并发调用，底层回调仍只执行一次。
    s.closeOnce()
}

func (s *Service) Stopped() 

这里最重要的是所有调用路径都持有同一个 s.closeOnce。如果每次 Close 都重新调用 sync.OnceFunc，就会创建多个互不共享状态的包装函数，当然无法阻止重复关闭。检查结果时，不要只看程序是否崩溃，还要确认底层资源的关闭副作用确实只出现一次。

需要错误返回时改用 OnceValue

OnceFunc 的签名是 func(func()) func()，无法把 Close 的错误返回给调用方。若所有调用者都应该看到第一次关闭的同一个结果，可以用 OnceValue 缓存 error：

package lifecycle

import (
    "io"
    "sync"
)

type ErrorCloser struct {
    closeOnce func() error
}

func NewErrorCloser(closer io.Closer) *ErrorCloser {
    e := &ErrorCloser{}
    e.closeOnce = sync.OnceValue(func() error {
        // 第一次关闭的结果会被缓存，后续调用得到同一个 error。
        return closer.Close()
    })
    return e
}

func (e *ErrorCloser) Close() error {
    // 并发调用者共享首次执行结果，nil 也会作为结果缓存。
    return e.closeOnce()
}

这种写法仍然不会重试：第一次返回非 nil 错误后，后续调用得到的还是这个错误。如果业务要求“暂时失败可以重试”，就不能使用一次性原语直接包住整个重试过程；应先定义可恢复错误、重试上限和资源状态机，再决定何时把资源标记为永久关闭。

panic 语义和 sync.Once 不完全相同

官方语义明确指出：如果传给 OnceFunc 的函数发生 panic，返回的包装函数在每次调用时都会以同一个值 panic。这样不会出现“第一次调用者看到失败，后来的调用者却像成功一样返回”的错觉。

这与直接使用 sync.Once.Do 的体验不同：Do 中的函数 panic 后，该 Once 仍视为已经返回，后续 Do 不会再次执行该函数，也不会自动重现相同 panic。关闭路径如果可能 panic，应优先消除 panic 根源；确实要转成错误时，在传给一次性原语的回调内部明确恢复和转换，不能指望 OnceFunc 自动处理。

关闭入口之外还要协调在途任务

若业务方法可能与关闭并发发生，还要补一层生命周期规则。常见做法是用 stopped 通道通知后台循环退出，用 context.CancelFunc 取消阻塞操作，再用 sync.WaitGroup 等待已启动任务结束。资源类型不允许并发使用与关闭时，则需要互斥锁或单所有者 goroutine 统一串行管理。

也就是说，OnceFunc 可以成为关闭入口，但不应被当成完整生命周期管理器。它保证回调次数和等待边界；谁还能启动新任务、在途任务何时结束、底层资源何时真正不可用，仍要由对象协议说明。

四种方案怎么选

最终判断可以很简单：固定且不可重试的无返回关闭，选 OnceFunc；需要结果，选 OnceValue；需要重试或复杂状态转换，使用显式状态机；已经有所有者，就不要再制造第二套关闭权。

相关问题

OnceFunc 会让其他 goroutine 立即返回吗？

不会。首次回调尚未结束时，并发调用者会等待；回调结束后，后续调用才直接返回。

OnceFunc 能避免重复关闭 channel 的 panic 吗？

可以，前提是所有关闭入口都调用同一个 OnceFunc 返回值，且没有其他代码绕过它直接关闭该 channel。

关闭失败后 OnceFunc 会再次尝试吗？

不会。OnceFunc 没有错误返回和重试语义；即便回调内部记录了错误，该回调也只执行一次。

使用 OnceFunc 后还需要锁吗？

关闭回调本身通常不需要再用锁防重复，但关闭与读写操作之间的互斥、在途任务等待和状态访问仍可能需要锁、Context、WaitGroup 或单所有者协议。