timer

README

@go/timer

Maintainer Statement: 本项目完全由 AI 维护。任何改动均遵循代码质量与性能的最佳实践。

🎯 设计哲学

@go/timer 是一个高性能的时间流管控引擎，专为构建健壮的微服务基础设施而设计。它不仅仅是计时器，更是一套处理并发、超时和重试的工具集。

📦 安装

go get apigo.cc/go/timer

💡 核心功能

1. 耗时打点追踪 (Tracker)

用于精准测量复杂业务流程中各环节的耗时。

tk := timer.Start()
// ... 业务步骤 1
tk.Record("step1")
// ... 业务步骤 2
tk.Record("step2")

fmt.Println(tk.Describe()) // [step1] 10ms; [step2] 20ms; Total: 30ms

2. 指数退避重试 (Retry)

提供优雅的重试管控，防止由于短时波动导致的系统雪崩。

err := timer.Retry(func() error {
    return fetchRemoteData()
}, timer.WithMaxRetries(3), timer.WithBackoff(100*time.Millisecond, 2.0))

3. 高性能时间轮 (Time Wheel)

在大规模定时任务场景下，相比原生 time.Timer 具有极低的 CPU 和内存开销。

tw := timer.NewTimeWheel(10*time.Millisecond, 100)
tw.Start()

tw.AfterFunc(5*time.Second, func() {
    // 异步执行
})

4. 防抖与节流 (Debouncer & Throttler)

控制高频事件的触发频率。

// 防抖：静止 1s 后执行
d := timer.NewDebouncer(1*time.Second, flush)
d.Trigger()

// 节流：每 2s 最多执行一次
t := timer.NewThrottler(2*time.Second, alert)
t.Trigger()

5. 上下文超时监控 (Timeout Executor)

结合打点追踪的超时执行器。

res, err := timer.RunTimeout(3*time.Second, func(tk *timer.Tracker) (any, error) {
    tk.Record("init")
    // ...
    return data, nil
})

🧪 验证状态

测试全部通过，性能达标。

详见：TEST.md

Documentation

Index

• Variables
• func Retry(fn func() error, opts ...RetryOption) error
• func RunTimeout[T any](timeout time.Duration, fn func(tk *Tracker) (T, error)) (T, error)
• type Debouncer
  • func NewDebouncer(interval time.Duration, callback func()) *Debouncer
  • func (d *Debouncer) Trigger()
• type Lap
• type RetryOption
  • func WithBackoff(d time.Duration, factor float64) RetryOption
  • func WithMaxRetries(n int) RetryOption
• type RetryOptions
• type Task
• type Throttler
  • func NewThrottler(interval time.Duration, callback func()) *Throttler
  • func (t *Throttler) Trigger()
• type TimeWheel
  • func NewTimeWheel(interval time.Duration, size int) *TimeWheel
  • func (tw *TimeWheel) AfterFunc(delay time.Duration, callback func()) *Task
  • func (tw *TimeWheel) Start()
  • func (tw *TimeWheel) Stop()
• type Tracker
  • func Start() *Tracker
  • func (t *Tracker) Describe() string
  • func (t *Tracker) Record(label string) time.Duration
  • func (t *Tracker) Stop() time.Duration
  • func (t *Tracker) Summarize() []Lap

Variables

var ErrTimeout = errors.New("execution timed out")

Functions

func Retry

func Retry(fn func() error, opts ...RetryOption) error

Retry 执行带退避机制的重试

func RunTimeout

func RunTimeout[T any](timeout time.Duration, fn func(tk *Tracker) (T, error)) (T, error)

RunTimeout 执行带超时控制的任务，并支持打点追踪

Types

type Debouncer

type Debouncer struct {
	// contains filtered or unexported fields
}

Debouncer 防抖器

func NewDebouncer

func NewDebouncer(interval time.Duration, callback func()) *Debouncer

NewDebouncer 创建一个防抖器

func (*Debouncer) Trigger

func (d *Debouncer) Trigger()

Trigger 触发事件

type Lap

type Lap struct {
	Label    string
	Duration time.Duration
	At       time.Time
}

type RetryOption

type RetryOption func(*RetryOptions)

RetryOption 重试选项函数

func WithBackoff

func WithBackoff(d time.Duration, factor float64) RetryOption

WithBackoff 设置初始等待时间和增长因子

func WithMaxRetries

func WithMaxRetries(n int) RetryOption

WithMaxRetries 设置最大重试次数

type RetryOptions

type RetryOptions struct {
	MaxRetries int
	Backoff    time.Duration
	Factor     float64
}

RetryOptions 重试配置

type Task

type Task struct {
	// contains filtered or unexported fields
}

type Throttler

type Throttler struct {
	// contains filtered or unexported fields
}

Throttler 节流器

func NewThrottler

func NewThrottler(interval time.Duration, callback func()) *Throttler

NewThrottler 创建一个节流器

func (*Throttler) Trigger

func (t *Throttler) Trigger()

Trigger 触发事件

type TimeWheel

type TimeWheel struct {
	// contains filtered or unexported fields
}

TimeWheel 时间轮

func NewTimeWheel

func NewTimeWheel(interval time.Duration, size int) *TimeWheel

NewTimeWheel 创建一个时间轮

func (*TimeWheel) AfterFunc

func (tw *TimeWheel) AfterFunc(delay time.Duration, callback func()) *Task

AfterFunc 在延迟后执行函数

func (*TimeWheel) Start

func (tw *TimeWheel) Start()

Start 启动时间轮

func (*TimeWheel) Stop

func (tw *TimeWheel) Stop()

Stop 停止时间轮

type Tracker

type Tracker struct {
	// contains filtered or unexported fields
}

Tracker 负责耗时打点追踪

func Start

func Start() *Tracker

Start 开始计时

func (*Tracker) Describe

func (t *Tracker) Describe() string

Describe 返回格式化后的统计字符串

func (*Tracker) Record

func (t *Tracker) Record(label string) time.Duration

Record 记录一段耗时 (Lap)，并返回段耗时

func (*Tracker) Stop

func (t *Tracker) Stop() time.Duration

Stop 结束计时，返回总持续时间

func (*Tracker) Summarize

func (t *Tracker) Summarize() []Lap

Summarize 返回所有记录段