syncx

package
v0.39.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package syncx 并发编排原语(stdlib-only):在飞闸门(按键分档位 / 全局单一 配额,取用分排队与即拒两档)+ 按序扇出收集。 收编自消费方手写形态——LLM 按模型名限在飞(429 风暴治理)、「这个进程总共 最多 N 个在飞」的手搓信号量,与「按 index 写结果免锁」的并行扇出样板。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FanIn

func FanIn[T any](n int, fn func(i int) T) []T

FanIn 并行执行 fn(0..n-1),各 goroutine 只写自己的 results[i] 槽位(免锁), 全部完成后按 index 序返回。fn 经 async.GoSafe 收编(AGENTS.md「禁裸 go func」, v0.2.1 前为裸 go、fn panic 会打死宿主进程):单个 fn panic 被恢复并走全局 panic handler 落日志,该槽位保持零值、其余槽位与收口不受影响——消费方按 「空槽降级」处理(零值歧义由调用方区分)。n<=0 返回空切片。

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 NewGate added in v0.19.0

func NewGate(cap int) *Gate

NewGate 构造;cap<=0 = 不限(Acquire 直通零开销)。

func (*Gate) Acquire added in v0.19.0

func (g *Gate) Acquire(ctx context.Context) (func(), error)

Acquire 取一个在飞名额;ctx 取消(排队等待中)返回 ctx.Err()。 返回的 release 归还名额,幂等可重复调用(atomic CAS 实现,见 idempotentRelease——同包 KeyedGate 同款)。

ctx 为 nil 时按 context.Background() 处理(永不取消)。

func (*Gate) TryAcquire added in v0.20.0

func (g *Gate) TryAcquire() (release func(), ok bool)

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

func NewKeyedGate(cap int) *KeyedGate

NewKeyedGate 构造;cap<=0 = 不限(Acquire 直通零开销)。

func (*KeyedGate) Acquire

func (g *KeyedGate) Acquire(ctx context.Context, key string) (func(), error)

Acquire 取一个键下在飞名额;ctx 取消(排队等待中)返回 ctx.Err()。 返回的 release 归还名额,幂等可重复调用(atomic CAS 实现,见 idempotentRelease——与同包 Gate 共用同一实现,#263)。

ctx 为 nil 时按 context.Background() 处理(永不取消),与 Gate 一致。

func (*KeyedGate) TryAcquire added in v0.21.0

func (g *KeyedGate) TryAcquire(key string) (func(), bool)

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

type Slot[T any] struct {
	Val T
	// Err 正常错误,或 panic 收编的 *async.PanicError。
	Err error
}

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

func FanInErr[T any](n int, fn func(i int) (T, error)) []Slot[T]

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

func FanInLimit[T any](n, limit int, fn func(i int) (T, error)) []Slot[T]

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() 处理)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL