Documentation
¶
Overview ¶
Package singleflight 提供并发请求合并(防击穿)工具。
同一个 key 的并发调用只执行一次 fn,其他调用共享结果。 适用于缓存穿透防护、token 刷新、配置加载等场景。
核心特性 ¶
- 基于 sync.Map + close(chan struct{}) 实现,零外部依赖
- 泛型支持,类型安全
- race detector 友好
- panic 安全:fn panic 不会导致等待者死锁
快速接入 ¶
sf := singleflight.New[string]()
val, err := sf.Do(ctx, "token:wechat_app", func(ctx context.Context) (string, error) {
return fetchAccessToken(ctx)
})
原理 ¶
调用 Do(key, fn) 时: 1. sync.Map.LoadOrStore 保证只有一个 goroutine 成为 caller 2. caller 执行 fn,完成后 close(ready) 广播通知 3. 其他 goroutine (waiter) 通过 <-ready 等待,读取共享结果 4. close 提供 happens-before 保证,字段读取无 data race
Index ¶
- type Flight
- func (f *Flight[T]) Do(ctx context.Context, key string, fn func(ctx context.Context) (T, error)) (T, error)
- func (f *Flight[T]) DoChan(ctx context.Context, key string, fn func(ctx context.Context) (T, error)) <-chan Result[T]
- func (f *Flight[T]) DoShared(ctx context.Context, key string, fn func(ctx context.Context) (T, error)) (T, bool, error)
- func (f *Flight[T]) Forget(key string)
- type Result
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Flight ¶
type Flight[T any] struct { // contains filtered or unexported fields }
Flight 对同一个 key 的并发调用只执行一次 fn。 零值可用,无需初始化。
func (*Flight[T]) Do ¶
func (f *Flight[T]) Do(ctx context.Context, key string, fn func(ctx context.Context) (T, error)) (T, error)
Do 执行 fn,同一个 key 的并发调用共享结果。
如果多个 goroutine 同时调用 Do 且 key 相同:
- 只有第一个 goroutine(caller)实际执行 fn
- 其他 goroutine(waiter)阻塞等待结果
- caller 完成后所有 waiter 同时获得返回值
panic 处理(与 golang.org/x/sync/singleflight 语义一致):
- 若 fn panic,panic 向首个 caller 自然传播(保留原始调用栈)
- waiter 被唤醒并拿到由 panic 转化的 error(而非零值+nil 的伪成功—— 调用方无法区分"合法零值"与"执行失败",会静默污染下游缓存/状态)
- map 中的 key 记录会被清理,不会因 panic 残留导致后续调用死锁
ctx 为 nil 时按 context.Background() 处理(永不取消,口径单源:pkg/contextx.OrBackground)。
func (*Flight[T]) DoChan ¶ added in v0.6.0
func (f *Flight[T]) DoChan(ctx context.Context, key string, fn func(ctx context.Context) (T, error)) <-chan Result[T]
DoChan 与 Do 语义相同,但结果经 channel 返回,调用方可用 select 组合:
// leader 恒免疫取消(内部已 WithoutCancel)+ waiter 各自 ctx 退出
resCh := f.DoChan(ctx, key, dial)
select {
case r := <-resCh:
...
case <-ctx.Done():
return ctx.Err() // 仅本调用方放弃等待,不影响 leader 的 fn
}
fn 始终在内部 goroutine 执行;返回的 channel 缓冲 1,调用方放弃读取 不会泄漏 goroutine。leader 的 fn **恒免疫取消**:内部固定以 context.WithoutCancel(ctx) 执行——即使传入可取消 ctx,fn 也不会被调用方的 放弃等待腰斩(合并语义:同 key 的其他调用方还在等这次结果)。 需要「调用方取消即中止执行」的取消传播用 Do/DoShared(fn 直接收到调用方 ctx)。 ctx 为 nil 时按 context.Background() 处理(WithoutCancel(nil) 会 panic,口径单源:pkg/contextx.OrBackground)。
func (*Flight[T]) DoShared ¶ added in v0.8.0
func (f *Flight[T]) DoShared(ctx context.Context, key string, fn func(ctx context.Context) (T, error)) (T, bool, error)
DoShared 是 Do 的折叠可观测形态(#18):额外返回 Shared——true 表示 本次调用与其他调用方共享了同一次 fn(自己是 waiter 而非 leader)。 用于埋点区分「本轮真采集」与「复用了并发中的那一轮」;Do 保持 (T, error) 不动,不破坏现有调用点。 ctx 为 nil 时按 context.Background() 处理(与 Do 同口径)。
type Result ¶ added in v0.6.0
type Result[T any] struct { Val T Err error // Waiters 是本轮折叠掉的**其他**调用方数(不含自己,>=0——leader 与 // waiter 两条路径同口径:leader 从未自增 waiters,waiter 读 Load()-1 // 扣掉自己;concurrency#340 此前 waiter 路径含自己,单 waiter 恒 1、 // 埋点多算且两路径不可比)。排障时可直接看出「这一轮合并了几个调用方」 // (#18)。 Waiters int }
Result 是 DoChan 的单次结果。