syncx —— 并发原语:计数信号量 + 固定大小工作池
限并发、隔离 goroutine 数量这类"每个后台都要重写一遍"的东西,抽成两个原语。 syncx 只有两个类型:
Semaphore(限同时进行中的数)和WorkerPool(固定 worker + 有界队列)。
功能
syncx 提供两件东西,只用 stdlib(并发原语本身)+ zap(打日志),不引第三方库:
Semaphore—— 计数信号量Acquire(ctx)阻塞取槽位 /TryAcquire()非阻塞 /Release()还槽位- 内部是预填 N 个 token 的 buffered chan,比手写 channel 少一个"忘记 release"的坑
WorkerPool—— 固定大小 goroutine 池- N 个 worker + 一个有界队列
- 队列满时
Submit阻塞(背压,防把内存吃光);SubmitCtx在 ctx 取消时放弃 Close优雅(跑完队列再退)/CloseNow立即(丢弃剩余队列)
不解决什么:单飞(singleflight)在 cachex 里;
按时间窗口的限流在 ratelimitx;定时触发在 cronx —— syncx 只管"并发数",不管"什么时候跑"。
接线状态(读源码前先看这个)
| 原语 | 生产调用方 |
|---|---|
Semaphore |
cachex 的启动预热限流(internal/pkg/cachex/warmer.go) |
WorkerPool |
零 —— 只有 examples/syncx 在用 |
框架层原语"先落地、后接线"是既定顺序(见 internal/pkg/cachex/memory_backend.go
的同一段说明)。WorkerPool 目前是零生产调用方的完整实现 —— 写业务时可以直接用,
但别假设它在框架里已经跑着。
配置
代码侧(构造选项)
syncx.NewSemaphore(cap int) *Semaphore
syncx.NewWorkerPool(size int, queueSize ...int) *WorkerPool
| 参数 | 默认 | 说明 |
|---|---|---|
NewSemaphore(cap) |
cap < 1 时静默改成 1 |
槽位总数。不报错,写 0 不会 panic,但也拿不到"零并发" |
NewWorkerPool(size) |
size < 1 时静默改成 4 |
worker 数量 |
NewWorkerPool(size, queueSize) |
64 |
任务队列缓冲。0 = 无缓冲,Submit 直接等 worker 来接 |
PoolConfig{Size, QueueSize} 这个结构体是导出的但没有任何构造函数接受它 ——
NewWorkerPool 走的是位置参数。想用这个结构体得自己传进去。
yaml 侧
该包无 yaml 配置。 并发上限是代码里的事(每个调用点的合理值不一样), 没有全局开关。
使用方法
Semaphore:限同时进行数
sem := syncx.NewSemaphore(2)
defer sem.Close()
fmt.Printf("容量 %d,当前空闲 %d\n", sem.Capacity(), sem.Available())
if err := sem.Acquire(ctx); err != nil {
return err
}
defer sem.Release()
// 不想排队就非阻塞拿
if sem.TryAcquire() {
defer sem.Release()
}
Acquire 拿不到时返回 ctx.Err();信号量已 Close 时返回 syncx.ErrSemaphoreClosed。
WorkerPool:固定 worker + 有界队列
pool := syncx.NewWorkerPool(2, 4)
defer pool.Close()
for _, job := range jobs {
pool.Submit(func() { process(job) }) // 队列满 → 这里阻塞
}
// "拿不到就放弃"用 SubmitCtx
if !pool.SubmitCtx(ctx, func() { process(job) }) {
// ctx 取消了,这个任务被丢弃 —— 调用方要自己兜底
}
看状态
st := pool.Stats()
// st.Submitted / Executed / Rejected / Blocked / Running / Queued
// st.Workers 是真实 worker 数,st.QueueSize 是队列缓冲容量
注意事项
- ⚠️
WorkerPool.Submit在队列满时是阻塞的,不是 fire-and-forget。 1 个 worker + 1 个队列位连续投 5 个任务,调用方会被卡住约 4 个任务的执行时间 (示例里专门演示了这一段)。要"塞不进去就跳过"必须用SubmitCtx。 - ⚠️
WorkerPool.Close()不能与Submit并发调用。Close会close(p.tasks), 而一个正阻塞在p.tasks <- task(队列满)上的Submit会 panic:send on closed channel。这是"关池子之后再投递就是 bug"的响亮违约方式。 - ⚠️
Semaphore.Close()不会唤醒阻塞在Acquire上的 goroutine。 源码注释写的是"清空 channel(让阻塞的 Acquire 退出)",但阻塞中的Acquire意味着 channel 是空的,清空它是空操作;而Close之后Release变成 no-op, token 再也回不来 ⇒ 那个 goroutine 只能靠 ctx 取消才能退出。 传进来的 ctx 一定要带超时。 - ⚠️
Semaphore.Close()之后再Release()是 no-op,槽位永远回不来; 此时Available()恒为 0、InUse()恒等于Capacity()—— Close 之后这两个诊断值没有意义。 - ⚠️
PoolStats.Executed统计的是"跑完的任务",不是"成功的任务"。safeRun会 recover 掉 panic(不让池子少一个并发位),但 recover 之后executed照样 +1。任务崩了指标是绿的 —— 唯一的痕迹是syncx: worker task panicked这条 warn 日志(带 stack)。 - ⚠️
PoolStats.Blocked只统计Submit路径的阻塞,SubmitCtx的阻塞不计数。 别把它当"所有阻塞等待次数"读。 - ⚠️
SubmitCtx在"队列有空位"和"ctx 已取消"同时成立时,可能照样把任务塞进去 —— Go 的select在多个 case 同时 ready 时是均匀随机挑的,没有优先级。 想严格保证"ctx 取消就不投",SubmitCtx的返回值必须检查。 - ⚠️
Submit(nil)返回 false 但不计入Rejected—— 它在计数之前就返回了。 - ⚠️
CloseNow()与Close()的差别不只是快慢:CloseNow会丢弃队列里 还没开始的任务,Close会跑完。源码里stopped标志必须在close(p.stop)之前置位,否则 select 随机拉到的那批任务照样会跑完 —— "立即丢弃剩余队列"就成了十次里错两三次的承诺。 - ⚠️
WorkerPool没有 lock-step 同步。Submit是 fire-and-forget, 包里没有"等所有任务跑完"的 API(只有Close会等)。要等结果得自己用sync.WaitGroup。