Documentation
¶
Overview ¶
Package window 提供滑动窗口统计容器(移植 go-zero collection.RollingWindow)。
RollingWindow 把时间轴切成 size 个 interval 宽的桶:Add 写入当前桶, 跨桶时惰性重置过期桶(无后台 goroutine);Reduce 遍历有效桶执行聚合, 可选 IgnoreCurrentBucket 跳过尚未写满的当前桶。桶类型可定制 (实现 BucketInterface 即可),默认桶 Bucket 提供 Sum/Count 聚合。
算法、惰性重置与时间对齐语义与上游 go-zero 保持一致;差异点:
- 时间源可注入:WithWindowClock(缺省 time.Now),测试注入假时钟即可 完全确定地驱动窗口推进;
- 选项类型按本仓硬规则命名 WindowOption(上游为 RollingWindowOption)。
用法:
r := window.NewRollingWindow[int64](func() *window.Bucket[int64] {
return new(window.Bucket[int64])
}, 10, time.Second) // 10 个桶,每桶 1s
r.Add(1)
var sum int64
r.Reduce(func(b *window.Bucket[int64]) { sum += b.Sum })
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BucketInterface ¶
type BucketInterface[T Numerical] interface { Add(v T) Reset() }
BucketInterface 定义桶的读写能力:Add 累加一个值,Reset 清零。 自定义桶实现该接口后即可作为 RollingWindow 的桶类型。
type Numerical ¶
type Numerical interface {
~int | ~int8 | ~int16 | ~int32 | ~int64 |
~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 |
~float32 | ~float64
}
Numerical 限定桶内数值类型(整数与浮点,含基于它们的自定义类型)。 与 go-zero mathx.Numerical 同形;本仓零第三方/矩阵内依赖,就地定义。
type RollingWindow ¶
type RollingWindow[T Numerical, B BucketInterface[T]] struct { // contains filtered or unexported fields }
RollingWindow 是按时间 interval 分桶的滑动窗口统计容器。 Add 写入当前桶;跨桶时惰性重置过期桶(无后台 goroutine); Reduce 遍历有效桶执行聚合。并发安全;零值不可用,须经 NewRollingWindow 构造。
func NewRollingWindow ¶
func NewRollingWindow[T Numerical, B BucketInterface[T]](newBucket func() B, size int, interval time.Duration, opts ...WindowOption[T, B]) *RollingWindow[T, B]
NewRollingWindow 返回带 size 个桶、单桶时间宽度 interval 的滑动窗口, newBucket 为桶工厂,opts 定制窗口行为。size < 1 或 interval <= 0 时 panic (interval 非法首拍 Add/Reduce 即 span() 整型除零 panic,提前到构造期暴露, 对齐 breaker WithBreakerWindow 的护栏口径,#158)。
func (*RollingWindow[T, B]) Add ¶
func (rw *RollingWindow[T, B]) Add(v T)
Add 把值累加进当前桶;跨桶时惰性重置过期桶并把时间对齐到 interval 边界。
func (*RollingWindow[T, B]) Reduce ¶
func (rw *RollingWindow[T, B]) Reduce(fn func(b B))
Reduce 对所有有效桶执行 fn 聚合; 构造时若启用 IgnoreCurrentBucket 则跳过当前桶(数据尚未完整)。
⚠️ fn 的回调约束(#335,此前零声明):fn 收到的是**活的桶指针**,且回调 执行期间本窗口以**读锁**被持有——
- fn 必须只读:写桶字段(如 b.Sum += x)与并发 Reduce/Add 构成 data race;
- fn **不得回调本窗口的任何方法**:Add/Reset 要写锁,与本 goroutine 持有的读锁互等 ⇒ 永久死锁(Go RWMutex 不可重入,且被阻塞的写锁还会 挡住后续读锁);Reduce 重入同理。
- fn 必须轻量:回调在锁内执行,长操作会放大 Add 的写锁等待。
包内消费方(shedding 的 maxPass/minRt、breaker 的 history)均为只读聚合。 需要写桶或长操作的下游,先自行快照(如 Reduce 里把桶值拷进局部结构) 再出锁处理。
type WindowOption ¶
type WindowOption[T Numerical, B BucketInterface[T]] func(rollingWindow *RollingWindow[T, B])
WindowOption 用于定制 RollingWindow(函数选项模式; 按本仓命名硬规则为 XxxOption,禁止裸 Option)。
func IgnoreCurrentBucket ¶
func IgnoreCurrentBucket[T Numerical, B BucketInterface[T]]() WindowOption[T, B]
IgnoreCurrentBucket 让 Reduce 跳过当前桶(数据尚未完整)。
func WithWindowClock ¶
func WithWindowClock[T Numerical, B BucketInterface[T]](clock func() time.Time) WindowOption[T, B]
WithWindowClock 注入自定义时间源(缺省 time.Now)。 测试注入假时钟即可完全确定地驱动窗口推进,不依赖真实 sleep。