Documentation
¶
Overview ¶
Package container 提供泛型容器微件:并发安全 Map(sync.Map 背书)、 SafeMap(RWMutex)、并发安全 Slice、Set、环形缓冲 Ring、阻塞队列 Queue、 「值+代次」原子发布单元 VersionedCell(#535,机制层——nil/深拷贝等值 策略归消费方包装层)。 全部零依赖(仅标准库)。
设计参考 go-kratos/kit container(maps/sets/slices)与 go-zero collection 的容器件,全面泛型化并按 Go 习惯收敛语义;v0.8.0 起收编原 collectionx 全部 API(Set/Ring/Queue/SafeMap 类型名与签名不变,仅换 import 路径):
- Set / Ring 为非并发安全(单 goroutine 或外部加锁使用);
- Queue / SafeMap / Map / Slice 内建并发安全;
- Ring 溢出覆盖最旧值(有界有损),Queue 无界无损;
- Map(sync.Map 背书)适合 key 集合稳定、读多写少的场景; 写冲突频繁或需要 GetOrSet 时用 SafeMap(RWMutex 背书)。
用法:
s := container.NewSet(1, 2, 3)
s.Add(4)
q := container.NewQueue[int]()
q.Put(1)
v, ok := q.Take() // 阻塞直至有元素或关闭
m := container.NewMap[string, *User]()
m.Store("u1", u)
sl := container.NewSlice[int]()
sl.Append(1, 2, 3)
cell := container.NewVersionedCell(&defaults)
cell.Publish(next) // 发布方:原子替换,代次 +1
v, gen := cell.Load() // 读侧:值与代次一致的一对
Index ¶
- type Map
- func (m *Map[K, V]) Clear()
- func (m *Map[K, V]) Delete(k K)
- func (m *Map[K, V]) Len() int
- func (m *Map[K, V]) Load(k K) (V, bool)
- func (m *Map[K, V]) LoadOrStore(k K, v V) (V, bool)
- func (m *Map[K, V]) Range(fn func(k K, v V) bool)
- func (m *Map[K, V]) Snapshot() map[K]V
- func (m *Map[K, V]) Store(k K, v V)
- type Queue
- type Ring
- type SafeMap
- func (sm *SafeMap[K, V]) Clear()
- func (sm *SafeMap[K, V]) Delete(k K)
- func (sm *SafeMap[K, V]) Get(k K) (V, bool)
- func (sm *SafeMap[K, V]) GetOrSet(k K, v V) (V, bool)
- func (sm *SafeMap[K, V]) Len() int
- func (sm *SafeMap[K, V]) Range(fn func(k K, v V) bool)
- func (sm *SafeMap[K, V]) Set(k K, v V)
- func (sm *SafeMap[K, V]) Snapshot() map[K]V
- type Set
- func (s Set[T]) Add(v T)
- func (s Set[T]) AddAll(items ...T)
- func (s Set[T]) Clone() Set[T]
- func (s Set[T]) Contains(v T) bool
- func (s Set[T]) Difference(other Set[T]) Set[T]
- func (s Set[T]) Intersect(other Set[T]) Set[T]
- func (s Set[T]) Items() []T
- func (s Set[T]) Len() int
- func (s Set[T]) Range(fn func(v T) bool)
- func (s Set[T]) Remove(v T)
- func (s Set[T]) Union(other Set[T]) Set[T]
- type Slice
- func (s *Slice[T]) Append(items ...T)
- func (s *Slice[T]) AppendIfAbsent(v T, eq func(a, b T) bool) bool
- func (s *Slice[T]) Clear()
- func (s *Slice[T]) Delete(i int) bool
- func (s *Slice[T]) Get(i int) (T, bool)
- func (s *Slice[T]) Len() int
- func (s *Slice[T]) Range(fn func(i int, v T) bool)
- func (s *Slice[T]) RemoveIf(pred func(v T) bool) int
- func (s *Slice[T]) Set(i int, v T) bool
- func (s *Slice[T]) Snapshot() []T
- type VersionedCell
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Map ¶
type Map[K comparable, V any] struct { // contains filtered or unexported fields }
Map 并发安全的泛型映射(sync.Map 背书,对标 go-kratos/kit container/maps)。 读多写少、key 集合趋于稳定时性能优于 SafeMap;写冲突频繁或需要 GetOrSet 语义时用 SafeMap。零值即可用(底层 sync.Map 的零值语义,#476——此前 「零值不可直接使用」与构造器返回零值自相矛盾),NewMap 仅是可读性糖。
func (*Map[K, V]) LoadOrStore ¶
LoadOrStore 原子地"不存在则写入":返回当前值与是否本已存在。
func (*Map[K, V]) Range ¶
Range 遍历快照;fn 返回 false 提前终止。遍历期间其他 goroutine 的写入 不阻塞,但可见性不保证(标准 sync.Map Range 语义)。
func (*Map[K, V]) Snapshot ¶ added in v0.47.0
func (m *Map[K, V]) Snapshot() map[K]V
Snapshot 返回全部键值的整体拷贝(plain map,调用方持有独立副本,可安全 修改/交给非并发安全代码)。副本与容器此后互不影响。
与 SafeMap.Snapshot 对偶(#393):「容器内容出口」的键值形态有单调用 原语,调用方不再手写「Range 构建副本」的样板循环——那段样板写错成边遍历 边写活体会绕开容器纪律。两个类型的 godoc 互链,出口原语对偶闭合。
sync.Map 的 Range 本身就是锁外遍历语义,收集不持有任何锁;遍历期间的 并发写入可见性不保证(同 Range 的标准 sync.Map 语义)。
返回值永不为 nil(容器为空时返回空 map),可直接交给序列化/调试转储。
type Queue ¶
type Queue[T any] struct { // contains filtered or unexported fields }
Queue 无界阻塞 FIFO 队列(并发安全):多生产者/多消费者, Take 阻塞直至有元素或队列关闭。Close 后 Put 直接 panic(与 向已关闭 channel 发送的语义一致)。
func (*Queue[T]) Close ¶
func (q *Queue[T]) Close()
Close 关闭队列:唤醒全部阻塞的 Take(取完余量后返回 false);幂等。 关闭后 Put 会 panic。
关闭后两个取出入口的口径([#258]):Take 继续排空余量,取空后返回 false;TryTake 一律立即返回 false,不再出队(关闭即不再有数据)。 两份文档此前的表述互相矛盾,这里统一写死。
func (*Queue[T]) TryTake ¶
TryTake 尝试出队,不阻塞;无元素或已关闭返回零值与 false。
关闭语义([#258]):**关闭即不再有数据**——已关闭时即使还有余量也返回 false,不再出队。此前实现无条件 popLocked,与本文档相反:调用方按 「关闭即空」写收尾逻辑,会在 Close 后多拿到一条元素(重复处理最后一条, 或 defer Close 之后仍把这条数据当有效值投递出去)。
与 Take 的分工是刻意的:Take 是阻塞消费者的排空语义——关闭后仍会取完 余量才返回 false(见 Close 文档),TestQueue_ConcurrentNoLoss 这类 「先 Close 再让消费者收尾」的用法依赖它;TryTake 是非阻塞轮询语义, 关闭位优先于余量。
type Ring ¶
type Ring[T any] struct { // contains filtered or unexported fields }
Ring 定长环形缓冲(非并发安全):生产快于消费最多保留最新 n 个元素, 超出后 Add 覆盖最旧值且保序 FIFO(有界有损,适合"只要最新 n 条"的场景, 如最近请求采样、滑动日志)。
逻辑序归基(pkg#354):read/write 是只增的逻辑序,32 位平台 int 在高频 写入下数小时即耗尽 int32、回绕成负数,负数取模得负下标直接 panic。Add 在 write 逼近字长上限前把两个计数器同时减去 read 的最大 n 整数倍基点 ——槽位映射(x%n)对减去 n 的整数倍不变,物理元素无需搬动;归基后 read 落回 [0, n)、write 落回不超过积压+n,32 位平台可长驻。
type SafeMap ¶
type SafeMap[K comparable, V any] struct { // contains filtered or unexported fields }
SafeMap 并发安全的泛型映射(RWMutex 保护),对标 go-zero collection/SafeMap 的泛型化替代。零值不可直接使用,须经 NewSafeMap 创建。
func (*SafeMap[K, V]) Range ¶
Range 遍历快照;fn 返回 false 提前终止。
**先在读锁内取快照,再在锁外遍历**(同 Slice.Range 的做法):
- 此前遍历期间**一直持着读锁** ⇒ 文档声称的「遍历期间其他 goroutine 的 写入不阻塞」并不成立(Set 要写锁,会被读锁挡住直到遍历结束);
- 更糟的是回调里写同一个 map 会**死锁**:RWMutex 不可重入,回调的 Set 要写锁、写锁要等读锁释放、读锁要等回调返回——互等。 (实测:回调里 sm.Set 同��个 map ⇒ 永久挂起。)
快照语义:遍历期间的并发写入不影响本次遍历(同 Slice.Range)。
func (*SafeMap[K, V]) Snapshot ¶ added in v0.38.0
func (sm *SafeMap[K, V]) Snapshot() map[K]V
Snapshot 返回全部键值的整体拷贝(plain map,调用方持有独立副本,可安全 修改/交给非并发安全代码)。副本与容器此后互不影响(#272)。
与 Slice.Snapshot 同纪律:**锁内整体拷贝、锁外交付**——拷贝在读锁内完成, 返回后调用方怎么改都不再经过容器的锁。API 对偶闭合后,「容器内容出口」 两个形态(有序 → []T,键值 → map[K]V)都有单调用原语;调用方不再手写 「Range 构建副本」的样板循环——那段样板写错成边遍历边写活体会绕开容器 纪律(Range 返回的是快照,正确但没有任何契约提示),Snapshot 把正确姿势 收成编译期可调用的单点。sync.Map 背书的 Map 有同名原语(#393 对偶闭合: 两个 Map 类型的内容出口形态一致)。
返回值永不为 nil(容器为空时返回空 map),可直接交给序列化/调试转储。
type Set ¶
type Set[T comparable] map[T]struct{}
Set 泛型集合(非并发安全:单 goroutine 使用,或由调用方加锁保护)。
**零值不可直接使用**(与同包其它容器口径一致):Set 是 map 类型,零值是 nil map,`Add` 会 panic("assignment to entry in nil map")。须经 NewSet 创建。
func (Set[T]) Clone ¶
Clone 拷贝出一个新集合:集合结构独立(增删互不影响),元素按值复制 ——元素本身是指针/含指针结构时不递归克隆,两集合共享底层对象(#492, 「深拷贝」措辞此前超出实现,按深拷贝假设使用会发生跨集合共享写)。
func (Set[T]) Difference ¶
Difference 差集:返回存在于 s 但不存在于 other 的新集合。
type Slice ¶
type Slice[T any] struct { // contains filtered or unexported fields }
Slice 并发安全的泛型切片(RWMutex 保护,对标 go-kratos/kit container/slices)。 零值即可用(nil 切片 append 语义,#476——此前「零值不可直接使用」与 构造器返回零值自相矛盾),NewSlice 仅是可读性糖。
func (*Slice[T]) AppendIfAbsent ¶ added in v0.34.0
AppendIfAbsent 原子地「查重 + 追加」(#178):已存在等值元素时返回 false 且 不改动切片;不存在时**在同一把写锁内**追加并返回 true。有序注册表场景 (先注册先命中、查重 fail-fast)对应 SafeMap.GetOrSet 的「一次性原子」承诺—— 先 Range/Snapshot 查重再 Append 是两步,重复注册的 fail-fast 窗口里会插进 两个同名条目。
eq 为 nil 时按 == 比较(interface 相等:动态类型与值都相等;元素动态类型 不可比较时 panic,与 map 访问不可比较键同一运行时契约)。需要深比较 (指针指向内容、切片逐元素)或自定义等价关系(host 别名大小写归一等) 时传入 eq。遍历按注册顺序进行,命中第一个等值元素即停。
func (*Slice[T]) RemoveIf ¶ added in v0.37.0
RemoveIf 原子删除所有命中谓词的元素,返回删除个数(#199—— AppendIfAbsent 的删除侧对偶:有序注册表的「按名注销/按前缀删」主路径)。
「先 Snapshot/Range 找下标、再 Delete(i)」的两步组合在并发写入下不安全: Range 在快照副本上遍历(它正确的并发语义),副本下标与活体切片在并发 Append/Delete 下会错位 ⇒ Delete(i) 删的是**另一个元素**。本方法把遍历 与删除收进**同一把写锁**(与 AppendIfAbsent 同纪律)。
谓词在锁内调用——必须轻量且**不得回调本切片的任何方法**(死锁边界; 同族先例:sync.Map 的 Range 也在锁语义内回调)。pred 为 nil 时 no-op 返回 0。返回删除**个数**而非被删元素副本(要副本先 Snapshot 自查—— 返回副本列表会助长「谓词内副作用」的用法)。
type VersionedCell ¶ added in v0.54.0
type VersionedCell[T any] struct { // contains filtered or unexported fields }
VersionedCell 泛型「值+代次」原子发布单元(#535):值与代次绑在**同一个 原子单元**里发布(单 atomic.Pointer),读侧一次 Load 拿到一致的一对—— 不存在「新值配旧代次」的自相矛盾窗口(拆成两个原子变量的实现,读者会在 跨字段的交错窗口同时看到新旧两半,症状是「发布过了但读到旧值」, core#79 实测 20 万次 Update 观察到 345 次)。
它是 core 侧两份同构手写的下沉机制件(core/config.Snapshot 与 core/governance.Store 各持一份同款 cell+CAS 发布,两者注释自认同构): 本类型只提供**原子机制**——值与代次的成对发布、CAS 推进代次、一致读; 各消费方的**值语义策略**由各自包装层实现,不在本层解读:
- 「读侧永不返 nil」(Snapshot 的契约):包装层在构造期注入默认值, 本层零值 cell 的 Load 返回零值与代次 0,是否视为非法由包装层判定;
- 「nil→空配置 / 发布前深拷贝 / nil 发布被忽略」(Store 的口径): 包装层在调用 Publish 之前自行变换入参——本层对指针类型的 nil **原样 发布**(推进代次),不做任何解读。
用法:
c := container.NewVersionedCell(&defaults)
c.Publish(next) // 发布方:原子替换,代次 +1
v, gen := c.Load() // 读侧:一致的一对
if c.Version() > seen { // 「换过没有」:单调代次,不吃 ABA
seen = gen
}
发布出去的值视为**不可变**:Load 返回的是发布值的原样读出(指针类型是 零拷贝引用),发布方 Publish 之后不得再就地修改它——否则读取方看到撕裂 状态(数据竞争)。要改先拷一份再发布。
func NewVersionedCell ¶ added in v0.54.0
func NewVersionedCell[T any](initial T) *VersionedCell[T]
NewVersionedCell 用初始值构造,代次 0;此后每次 Publish +1。想知道 「外界发布过没有」,看 Version() > 0。
func (*VersionedCell[T]) Load ¶ added in v0.54.0
func (c *VersionedCell[T]) Load() (T, uint64)
Load 返回**一致的一对**:当前值与它的代次。
需要「拿到值的同时知道它是第几代」(典型:据此决定派生状态要不要重建) 时必须用它,而不是 Version() 单独调用——两次调用之间可能插进一次发布, 拿到的值与代次就会来自不同代。
零值 cell(未发布过)返回零值与代次 0;「零值是否合法」由包装层解读 (见类型文档)。
func (*VersionedCell[T]) Publish ¶ added in v0.54.0
func (c *VersionedCell[T]) Publish(v T)
Publish 原子发布新值,每次成功调用恰好推进一代。
并发安全:多个发布者同时调用,各自重试(CAS 循环,从**观察到的**上一代 推导下一代)——代次唯一、单调、不回卷,不会重复也不会丢失。这是两侧 来源(Snapshot.Publish / Store.Update)的共同行为,故本层采用重试语义而 非「冲突即失败」。
值策略归包装层:指针类型的 nil 会**原样发布**并推进代次(「nil 忽略」 「nil→空配置」等口径由消费方在调用本方法之前自行判定)。
func (*VersionedCell[T]) String ¶ added in v0.54.0
func (c *VersionedCell[T]) String() string
String 便于在日志里打印当前代次(不含值——值里常有密钥,而 fmt 的 %v 会把它们一并打出来)。
func (*VersionedCell[T]) Version ¶ added in v0.54.0
func (c *VersionedCell[T]) Version() uint64
Version 返回当前代次:构造值 0,此后每次 Publish +1。零值 cell 返回 0。
它是发布单元的投影(与值同一次原子替换),并发发布下依然单调、唯一、 不回卷;用来回答「换过没有」而不是「值是不是同一个」(指针比对会被 ABA 与「相同内容重新发布」骗过)。