Documentation
¶
Overview ¶
Package syncx 并发编排原语(stdlib-only):在飞闸门(按键分档位 / 全局单一 配额,取用分排队与即拒两档)+ 按序扇出收集。 收编自消费方手写形态——LLM 按模型名限在飞(429 风暴治理)、「这个进程总共 最多 N 个在飞」的手搓信号量,与「按 index 写结果免锁」的并行扇出样板。
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Gate ¶ added in v0.19.0
type Gate struct {
// contains filtered or unexported fields
}
Gate 是**全局在飞上限闸门**:整个实例最多 cap 个在飞,排队者等 ctx 取消 即返回 ctx.Err()。与 KeyedGate 的区别:Gate 是单一全局配额(不分 key), KeyedGate 按 key 分档位(按模型名/租户名分别限流)。
两种取用语义并存、命名区分:
- Acquire(ctx):满额时**排队**等名额;
- TryAcquire():满额时**立即拒**(不等待、不占名额)——重活的并发上限 用满就该立刻拒,让调用方回 429 / 503,而不是把请求堆在队列里。
为什么需要这一档:现有原语都不覆盖"这个进程总共最多 N 个在飞"这类闸门。
- KeyedGate 按 key 隔离,用固定 key 硬凑可行,但那是把"多档位闸门"原语 当"单档位闸门"用,语义与命名都不对;
- gopool.Pool 是弹性 worker 池,**MaxIdleWorkers 是常驻 worker 上限, 不是并发上限**——任务队列满时回退为独立 goroutine 直跑,任务永不因 并发数被拒(实测 MaxIdleWorkers=2 时实际并发仍是 10);它与"硬配额" 的语义正好相反;
- ratelimit.KeyedLimiter 是速率型(令牌桶),不是并发闸门。
适用场景:保护下游 DB / 控制子进程数 / 限制外部 API 并发。
并发安全;release 幂等(可重复调用,只归还一次)。
func (*Gate) Acquire ¶ added in v0.19.0
Acquire 取一个在飞名额;ctx 取消(排队等待中)返回 ctx.Err()。 返回的 release 归还名额,幂等可重复调用(atomic CAS 实现,见 idempotentRelease——同包 KeyedGate 同款)。
ctx 为 nil 时按 context.Background() 处理(永不取消)。
func (*Gate) TryAcquire ¶ added in v0.20.0
TryAcquire 尝试取一个在飞名额,**不等待**:名额已满时**立即**返回 ok=false。
与 Acquire 的区别是**排队 vs 即拒**,两者并存、命名区分:
- Acquire(ctx):满额时**排队**等名额,等 ctx 取消才返回 ctx.Err();
- TryAcquire():满额时**立刻拒**,一个名都不占。
什么时候要即拒:Acquire 的排队语义会把「并发被占满」换成「请求堆在队列里」—— 那是另一种 DoS 形态。重活(图片全量解码、ffmpeg 子进程、模型推理)的并发 上限用满就该立刻拒,让调用方回 429 / 503,而不是让队列越堆越长、把内存 或子进程数推到别处爆掉。
ok=false 只有一个含义:**名额已满**(非阻塞取名额没有别的失败原因), 调用方可据此返回 429 / 503,而不是泛化成 500。
返回的 release 归还名额,幂等可重复调用(与 Acquire 一致)。 cap<=0(不限)时恒返回 ok=true——不限额的闸门没有「满」这回事。
用法:
release, ok := gate.TryAcquire()
if !ok {
return nil, ErrTooManyInFlight // 429 / 503
}
defer release()
type KeyedGate ¶
type KeyedGate struct {
// contains filtered or unexported fields
}
KeyedGate 按键在飞上限闸门(并发安全;channel 令牌先到先得;键集由调用方 保证有界——如按模型名/租户名,键量级恒小不回收)。
按 key 分档位("每个模型最多 N 个在飞")。要的是**单一全局配额** ("整个进程总共最多 N 个在飞")用 Gate——两者语义不同,不要用固定 key 硬凑。
func NewKeyedGate ¶
NewKeyedGate 构造;cap<=0 = 不限(Acquire 直通零开销)。
func (*KeyedGate) Acquire ¶
Acquire 取一个键下在飞名额;ctx 取消(排队等待中)返回 ctx.Err()。 返回的 release 归还名额,幂等可重复调用(atomic CAS 实现,见 idempotentRelease——与同包 Gate 共用同一实现,#263)。
ctx 为 nil 时按 context.Background() 处理(永不取消),与 Gate 一致。
func (*KeyedGate) TryAcquire ¶ added in v0.21.0
TryAcquire 尝试取一个键下在飞名额,**不等待**:该 key 档位已满时**立即**返回 ok=false(不排队、不占名额)。
与 Acquire 的区别是**排队 vs 即拒**,两者并存、命名区分(同包 Gate 的同款分档):
- Acquire(ctx, key):该 key 满额时**排队**等名额,等 ctx 取消才返回 ctx.Err();
- TryAcquire(key):该 key 满额时**立刻拒**,一个名都不占。
什么时候要即拒:防重入场景的常见形态——同一个 key 正在处理中就**立刻拒绝** (回 409/429),而不是排队等它做完。此前消费方只能手搓 map[K]*sync.Mutex + TryLock + sync.Once 兜底幂等归还:每仓各写一遍,once 包装又容易漏(漏了就是 双重解锁 panic)。KeyedGate.Acquire 是排队语义,套不上——要「忙即拒」就得上 调用方自己再套一层 goroutine + select,绕开了原语的语义。
ok=false 只有一个含义:**该 key 档位已满**(非阻塞取名额没有别的失败原因), 调用方可据此返回 409 / 429,而不是泛化成 500。
返回的 release 归还名额,幂等可重复调用(与 Acquire 一致,atomic CAS 实现)。 cap<=0(不限)时恒返回 ok=true——不限额的闸门没有「满」这回事。
用法:
release, ok := gate.TryAcquire("account:42:sync")
if !ok {
return errBusy // 409 / 429
}
defer release()
type KeyedMutex ¶ added in v0.29.0
type KeyedMutex[K comparable] struct { // contains filtered or unexported fields }
KeyedMutex 本地按键互斥原语(#195):**同一 key 同刻至多一个持有者**—— 「同名任务/通道/资源同刻只跑一个」的单进程内单源。
收编 git-ferry `localGuard` 式的 sync.Map 三件套手搓(LoadOrStore + 失败还 名额 + Delete 回调)——三步各自易错,且失效形态都是慢性的:
- LoadOrStore 失败(key 已在跑)时忘了归还先抢到的全局名额 ⇒ 每撞一次 同 key 竞争,全局并发名额永久 -1,最终「无流量也 ErrTooManyConcurrent」;
- release 回调里 Delete 抢跑(先 Delete 后做/漏做其它清理,或 Delete 了 新执行流刚 store 的标记)⇒ 互斥标记被误删,同 key 两个执行流并行。
本原语把三步收敛成一次固定顺序的临界区:命中即拒(ok=false,无名额可还)、 成功即持有(held 集合登记)、release 即注销(delete 与登记同一把段锁), 调用方没有「中间态」可以写错。
与同仓近邻的分工 ¶
- singleflight:同 key 并发调用**合并**成一次 fn(所有调用者共享同一份 结果)——要的是省执行;
- KeyedMutex:同 key 并发**互斥**(后来者立刻失败,不共享、不排队)—— 要的是「只跑一个」的排他性,两次调用是两次独立执行;
- KeyedGate(本包):同 key **并发上限 N**(TryAcquire 即拒 / Acquire 排队)——N>1 的闸门;KeyedMutex 是它的 N=1 且语义为「锁」的特化形态, 返回的是锁句柄而不是名额。
内存模型 ¶
持有标记是**逐段锁保护的 `map[K]struct{}` 集合**(16 段,key 哈希打散), 条目生命周期 = 持有期:release 注销即删除条目——表中只会存在**正在持有** 的 key,高基数/长尾 key 不残留(对比 KeyedGate 的槽位常驻、KeyedLimiterOf 的空闲 TTL 清扫:那两者缓存的是可复用的有状态实例,而互斥标记是无状态位, 持有结束即无信息量,保留只会变成慢性泄漏面)。无需清扫协程、无需 Close。
注意 Acquire/WithLock 不排队:key 忙时**立刻**返回(ok=false / false), 返回 409/429 由调用方决定;需要「排队等锁 + 超时放弃」的形态(等价 TryAcquireWithTimeout)请用 KeyedGate.Acquire(ctx, key)(cap=1 即排队互斥)。
KeyedMutex 按键互斥器(并发安全)。零值不可用,经 NewKeyedMutex 构造。
func NewKeyedMutex ¶ added in v0.29.0
func NewKeyedMutex[K comparable]() *KeyedMutex[K]
NewKeyedMutex 构造按键互斥器。key 类型任意 comparable(任务键通常为 string)。
用法:
guard := syncx.NewKeyedMutex[string]()
if !guard.WithLock(taskKey, func() { runOnce(taskKey) }) {
return ErrTaskRunning // 409 / 429
}
func (*KeyedMutex[K]) Acquire ¶ added in v0.29.0
func (m *KeyedMutex[K]) Acquire(key K) (release func(), ok bool)
Acquire 尝试持有 key 的互斥标记,**不等待**:该 key 已被持有 ⇒ 立即返回 (nil, false),不排队、不占任何名额。
ok=false 只有一个含义:**该 key 正在执行中**(非阻塞互斥没有别的失败原因), 调用方可据此返回 409 / 429,而不是泛化成 500。
返回的 release 注销持有标记,**幂等**(release 两次第二次 no-op)——吃掉 「超时清理路径与正常返回路径同时释放」这类下游 Double-release bug:标记用 atomic.Bool CAS 防护(同包 KeyedGate 同款做法),裸 bool 在两个 goroutine 并发调用同一 release 时是 data race,且第二次 delete 可能误删新执行流刚 登记的标记(即 git-ferry 注释自证的 ④ 号失效形态)。
release 必须被调用:持有标记在 release 前一直阻塞同 key 的后续 Acquire (fn panic 不会自动释放——需要「panic 也放锁」的包裹语义用 WithLock)。
func (*KeyedMutex[K]) Len ¶ added in v0.29.0
func (m *KeyedMutex[K]) Len() int
Len 返回当前持有中的 key 数(快照值,返回即过期——仅观测用,不做同步依据)。
func (*KeyedMutex[K]) WithLock ¶ added in v0.29.0
func (m *KeyedMutex[K]) WithLock(key K, fn func()) bool
WithLock 是 Acquire 的闭包糖:key 空闲则以独占方式执行 fn 并返回 true; key 忙则 fn **一次不调**、立即返回 false(即拒语义,与 Acquire 一致)。 fn 返回(含 panic 展开)后互斥标记必然已释放——release 挂 defer,fn 的 panic 不吞不转、原样上抛给调用方(本方法运行在调用方自己的 goroutine, 不跨 goroutine 收编;需要把 panic 转错误用 async.RunSafeErr 包裹本调用)。
用法:
if !guard.WithLock(key, func() { syncMirror(key) }) {
return ErrTaskRunning
}
type Slot ¶ added in v0.5.0
Slot 是 FanInErr 的逐槽结果:Val/Err 为 fn 的正常返回;fn panic 时 Err 承载 *async.PanicError(errors.As 可辨、携带栈,#12)且 Val 为零值。 (历史兼容字段 Panicked 已于 v0.36.0 删除——panic payload 改由 errors.As(&async.PanicError) 从 Err 读取。)
func FanInErr ¶ added in v0.5.0
FanInErr 逐槽错误变体:并行执行 fn(0..n-1)(fn 可返回 error),全部完成后 按 index 序返回逐槽结果。fn 正常返回 → Val/Err 如实记录;fn panic → 该槽 Err=*async.PanicError(v0.7.0 起统一收编,errors.As 可辨、携带栈;Panicked 同写原始 payload,已 Deprecated)、Val 零值,并经 ReportPanic 上报——不再 静默(FanIn 契约保留不动,供无 error 形态的轻量路径)。n<=0 返回空切片。
func FanInLimit ¶ added in v0.12.0
FanInLimit 是 FanInErr 的受限并发变体(#23):n 槽结果语义不变,内部固定 w = min(limit, n) 个 worker 经原子计数器拉取 index 执行——goroutine O(w), 供「n 可达数十以上、fn 是有成本 IO(DB/远端查询)」的 fan-out 限并发, 防下游过载(收编消费方手写的 channel 信号量样板)。其余语义与 FanInErr 一致:按 index 序返回逐槽结果、panic 进该槽 Err(*async.PanicError)并 ReportPanic 上报。limit<=0 = 不设上限(等价 FanInErr 行为)。
func FanInLimitCtx ¶ added in v0.14.0
func FanInLimitCtx[T any](ctx context.Context, n, limit int, fn func(ctx context.Context, i int) (T, error)) []Slot[T]
FanInLimitCtx 是 FanInLimit 的 ctx 感知变体(#27):fn 携带 ctx 供单项内部 使用;引擎级取消语义——worker 每轮拉取 index 前先查 ctx.Err()(worker 内 缓存,取消后零额外锁开销),命中即不再启动新工作(fn 一次都不调),当前及 剩余槽一次遍历快速排空为该错误(context.Canceled);已在飞 item 跑完、结果 照常落槽。其余语义与 FanInLimit 一致(panic 进槽并上报、limit<=0 = 不设上限、 n<=0 = nil;ctx 为 nil 时按 context.Background() 处理)。