Go time.AfterFunc 怎样避免重复调度清理任务

在缓存失效、临时文件清理、会话回收这类场景里，同一个对象可能被连续触发多次“稍后清理”。直接连续调用 time.AfterFunc 会留下多个独立回调；只调用 Timer.Stop 也不能保证已经启动的回调停止。更稳妥的做法是：用互斥锁保护当前计时器和一个递增代次，在回调入口再次确认代次，并用运行标记保证清理函数不会重入。

官方地址：https://pkg.go.dev/time#AfterFunc

如果 Stop 返回 true，本次回调尚未启动，可以被取消；如果返回 false，回调可能已经在自己的 goroutine 中启动，Stop 不会等待它结束。要避免重复清理，关键不是反复调用 Stop，而是让回调自己确认“我是不是最新的一次调度”，并把真正的清理过程串行化。

AfterFunc 到底会返回什么

time.AfterFunc(d, f) 等待时长 d 到期，然后在独立 goroutine 中调用 f，返回的 *time.Timer 可以用 Stop 取消这次调用。它不是通过 Timer.C 传递时间值，AfterFunc 创建的 Timer 的 C 字段不会用于接收结果。

Stop 的返回值只描述“取消动作是否阻止了计时器触发”，不描述回调函数是否已经完成：

为什么只保存 Timer 还不够

下面这种写法看起来像“每次新请求都取消旧任务”，但它没有解决回调已经启动的情况：

type NaiveScheduler struct {
    mu    sync.Mutex
    timer *time.Timer
}

func (s *NaiveScheduler) Schedule(d time.Duration, cleanup func()) {
    s.mu.Lock()
    defer s.mu.Unlock()

    // Stop 只能尝试取消尚未启动的回调，不能等待已经启动的回调。
    if s.timer != nil {
        s.timer.Stop()
    }
    // 新 Timer 与旧回调彼此独立，旧回调仍可能继续执行。
    s.timer = time.AfterFunc(d, cleanup)
}

如果旧回调已经开始执行，Stop 返回 false，新的 AfterFunc 仍然会在未来执行。两个清理函数可能同时删除同一份数据、重复发送事件，或者一个清理函数刚重建状态，另一个旧回调又把它删掉。因此，Timer 只是调度句柄，不能单独充当并发控制器。

用代次让过期回调自动失效

每次收到新的调度请求就把代次加一。回调闭包捕获创建时的代次，真正执行前拿锁比较它和当前代次是否一致：

type CleanupScheduler struct {
    mu         sync.Mutex
    timer      *time.Timer
    generation uint64
    running    bool
    rerun      bool
    cleanup    func()
}

func NewCleanupScheduler(cleanup func()) *CleanupScheduler {
    return &CleanupScheduler{cleanup: cleanup}
}

func (s *CleanupScheduler) Schedule(delay time.Duration) {
    s.mu.Lock()
    defer s.mu.Unlock()

    // 代次代表“最新一次调度”，旧回调即使后来启动也会被识别为过期。
    s.generation++
    generation := s.generation

    // Stop 不等待回调，所以这里还必须依赖回调入口的代次检查。
    if s.timer != nil {
        s.timer.Stop()
    }

    // 清理正在运行时不再叠加计时器，记录一次待重跑请求即可。
    if s.running {
        s.rerun = true
        s.timer = nil
        return
    }

    s.timer = time.AfterFunc(delay, func() {
        s.run(generation)
    })
}

func (s *CleanupScheduler) run(generation uint64) {
    s.mu.Lock()
    s.timer = nil

    // 旧 Timer 的回调可能已经排队，但只允许最新代次进入清理。
    if generation != s.generation {
        s.mu.Unlock()
        return
    }
    if s.running {
        s.rerun = true
        s.mu.Unlock()
        return
    }
    s.running = true
    s.mu.Unlock()

    // 不持有锁执行外部清理，避免清理函数阻塞新的调度请求。
    s.cleanup()

    s.mu.Lock()
    s.running = false
    rerun := s.rerun
    s.rerun = false
    s.mu.Unlock()

    // 清理期间若收到新请求，完成当前清理后只补跑一次最新任务。
    if rerun {
        s.Schedule(0)
    }
}

这个实现有三个互补的保护点：

• 互斥锁：保证 timer、generation、running 和 rerun 的读写有一致的顺序。
• 代次检查：即使旧回调已经排队，也会在入口发现自己不是最新调度并直接退出。
• 运行标记：清理函数执行期间的新请求不会再开一份并发清理，而是合并成一次后续执行。

这段封装如何处理三个时序

新请求早于旧 Timer 到期

新请求拿到锁后递增代次并调用旧 Timer 的 Stop。如果返回 true，旧回调没有启动；即便返回值因为竞态是 false，旧回调进入 run 时仍会比较旧代次，因而不会执行清理。

旧回调已经启动，新请求同时到达

旧回调先把 running 设为 true，然后释放锁执行清理。新请求不会等待旧清理，也不会再创建并发 Timer，而是把 rerun 设为 true。旧清理结束后只补跑一次最新任务。这里的“串行”是调度器提供的串行，不是 Stop 提供的等待。

多个请求在清理完成前连续到达

每个请求都推进代次，但运行期间只保留一个 rerun 布尔值。清理结束后补跑一次即可覆盖“最新状态”，不会为每个重复请求排一条队。如果业务要求每个事件都处理，则不能使用这种合并策略，应改用带任务 ID 的队列或消息系统。

使用时最容易犯的错误

1. 把 Stop 当成 Join。 Stop 返回 false 后，不能立刻认为旧回调结束；需要像上面的 running 标记一样显式协调。
2. 只在 Schedule 里加锁。 回调入口也必须拿同一把锁检查代次，否则旧回调仍能绕过调度器状态。
3. 把 AfterFunc 当周期任务。 AfterFunc 只安排一次回调。周期工作应评估 time.Ticker 或明确的循环退出机制，不要在回调里无条件自我重排。
4. 清理函数里持有调度器锁。 外部 I/O、数据库删除和网络调用都可能阻塞，应先改变状态、释放锁，再执行清理。
5. 忽略清理函数的幂等性。 门控能减少重复进入，但服务退出、进程重启或其他调用方仍可能触发同一逻辑；删除与回收操作本身仍应尽量可重复执行。

最后怎么选

如果需求只是“延迟一次且无人更新”，直接保存 *time.Timer 并在不需要时调用 Stop 就够了。如果需求是“连续更新只保留最新一次”，加入代次检查。如果还要求清理不能重入，再加入 running 与 rerun，把 Stop 的取消语义和业务层的并发协调分开。

常见问题

Stop 返回 true 后还会执行回调吗？

对这次已经被停止的 AfterFunc 调度，返回 true 表示它在回调启动前被停止。但其他代码仍可能创建新的 Timer；如果业务需要全局只允许一份清理，仍应由共享状态控制。

Stop 返回 false 要不要再次调用？

通常没有意义。它说明当前 Timer 已到期或已停止；对 AfterFunc 来说，回调可能已经启动。应把注意力放到代次判断、运行状态和完成协调上。

为什么不在回调里一直持有锁？

清理通常包含文件、数据库或网络操作。持锁执行会把新的调度请求变成无界等待，也容易造成锁顺序问题。锁只保护状态转换，耗时工作放到锁外。