timingwheel

README

timingwheel

Golang implementation of Hierarchical Timing Wheels.

Installation

$ go get -u github.com/alkaid/timingwheel

Design

timingwheel is ported from Kafka's purgatory, which is designed based on Hierarchical Timing Wheels.

中文博客：层级时间轮的 Golang 实现。

Documentation

For usage and examples see the Godoc.

Benchmark

$ go test -bench=. -benchmem
goos: darwin
goarch: amd64
pkg: github.com/RussellLuo/timingwheel
BenchmarkTimingWheel_StartStop/N-1m-8            5000000               329 ns/op              83 B/op          2 allocs/op
BenchmarkTimingWheel_StartStop/N-5m-8            5000000               363 ns/op              95 B/op          2 allocs/op
BenchmarkTimingWheel_StartStop/N-10m-8           5000000               440 ns/op              37 B/op          1 allocs/op
BenchmarkStandardTimer_StartStop/N-1m-8         10000000               199 ns/op              64 B/op          1 allocs/op
BenchmarkStandardTimer_StartStop/N-5m-8          2000000               644 ns/op              64 B/op          1 allocs/op
BenchmarkStandardTimer_StartStop/N-10m-8          500000              2434 ns/op              64 B/op          1 allocs/op
PASS
ok      github.com/RussellLuo/timingwheel       116.977s

License

MIT

Documentation

Overview

Example (ScheduleTimer)

package main

import (
	"fmt"
	"time"

	"github.com/alkaid/timingwheel"
)

type EveryScheduler struct {
	Interval time.Duration
}

func (s *EveryScheduler) Next(prev time.Time) time.Time {
	return prev.Add(s.Interval)
}

func main() {
	tw := timingwheel.NewTimingWheel(time.Millisecond, 20)
	tw.Start()
	defer tw.Stop()

	exitC := make(chan time.Time)
	t := tw.ScheduleFunc(&EveryScheduler{time.Second}, func() {
		fmt.Println("The timer fires")
		exitC <- time.Now().UTC()
	})

	<-exitC
	<-exitC

	// We need to stop the timer since it will be restarted again and again.
	for !t.Stop() {
	}

}

Output:

The timer fires
The timer fires

Example (StartTimer)

package main

import (
	"fmt"
	"time"

	"github.com/alkaid/timingwheel"
)

func main() {
	tw := timingwheel.NewTimingWheel(time.Millisecond, 20)
	tw.Start()
	defer tw.Stop()

	exitC := make(chan time.Time, 1)
	tw.AfterFunc(time.Second, func() {
		fmt.Println("The timer fires")
		exitC <- time.Now().UTC()
	})

	<-exitC

}

Output:

The timer fires

Example (StopTimer)

package main

import (
	"fmt"
	"time"

	"github.com/alkaid/timingwheel"
)

func main() {
	tw := timingwheel.NewTimingWheel(time.Millisecond, 20)
	tw.Start()
	defer tw.Stop()

	t := tw.AfterFunc(time.Second, func() {
		fmt.Println("The timer fires")
	})

	<-time.After(900 * time.Millisecond)
	// Stop the timer before it fires
	t.Stop()

}

Index

• Constants
• type Option
  • func WithGoID(goID int) Option
  • func WithPool(pool *ants.PoolWithID) Option
• type Options
• type Scheduler
• type Timer
  • func NewTimer(expiration int64, task func(), opts ...Option) *Timer
  • func (t *Timer) Stop() bool
• type TimingWheel
  • func NewTimingWheel(tick time.Duration, wheelSize int64) *TimingWheel
  • func (tw *TimingWheel) AfterFunc(d time.Duration, f func(), opts ...Option) *Timer
  • func (tw *TimingWheel) Cron(interval time.Duration, fn func(), opt ...Option) *Timer
  • func (tw *TimingWheel) CronWithCount(interval time.Duration, count int, fn func(), opt ...Option) *Timer
  • func (tw *TimingWheel) ScheduleFunc(s Scheduler, f func(), opts ...Option) (t *Timer)
  • func (tw *TimingWheel) Start()
  • func (tw *TimingWheel) Stop()

Examples

• Package (ScheduleTimer)
• Package (StartTimer)
• Package (StopTimer)

Constants

const (
	// LoopForever is a constant indicating that timer should loop forever
	LoopForever = -1
)

Types

type Option

type Option func(options *Options)

func WithGoID

func WithGoID(goID int) Option

WithGoID 指定任务执行的线程ID

@param goID
@return Option

func WithPool

func WithPool(pool *ants.PoolWithID) Option

WithPool 指定任务使用的线程池

@param pool
@return Option

type Options

type Options struct {
	Pool *ants.PoolWithID // 线程池
	GoID int              // 线程ID
}

type Scheduler

type Scheduler interface {
	// Next returns the next execution time after the given (previous) time.
	// It will return a zero time if no next time is scheduled.
	//
	// All times must be UTC.
	Next(time.Time) time.Time
}

Scheduler determines the execution plan of a task.

type Timer

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

Timer represents a single event. When the Timer expires, the given task will be executed.

func NewTimer

func NewTimer(expiration int64, task func(), opts ...Option) *Timer

func (*Timer) Stop

func (t *Timer) Stop() bool

Stop prevents the Timer from firing. It returns true if the call stops the timer, false if the timer has already expired or been stopped.

If the timer t has already expired and the t.task has been started in its own goroutine; Stop does not wait for t.task to complete before returning. If the caller needs to know whether t.task is completed, it must coordinate with t.task explicitly.

type TimingWheel

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

TimingWheel is an implementation of Hierarchical Timing Wheels.

func NewTimingWheel

func NewTimingWheel(tick time.Duration, wheelSize int64) *TimingWheel

NewTimingWheel creates an instance of TimingWheel with the given tick and wheelSize.

func (*TimingWheel) AfterFunc

func (tw *TimingWheel) AfterFunc(d time.Duration, f func(), opts ...Option) *Timer

AfterFunc waits for the duration to elapse and then calls f in its own goroutine. It returns a Timer that can be used to cancel the call using its Stop method.

func (*TimingWheel) Cron

func (tw *TimingWheel) Cron(interval time.Duration, fn func(), opt ...Option) *Timer

Cron 添加永远重复的任务

@receiver t
@param interval
@param fn
@return *timingwheel.Timer

func (*TimingWheel) CronWithCount

func (tw *TimingWheel) CronWithCount(interval time.Duration, count int, fn func(), opt ...Option) *Timer

CronWithCount 添加重复次数的任务

@receiver t
@param interval
@param count
@param fn
@return *timingwheel.Timer

func (*TimingWheel) ScheduleFunc

func (tw *TimingWheel) ScheduleFunc(s Scheduler, f func(), opts ...Option) (t *Timer)

ScheduleFunc calls f (in its own goroutine) according to the execution plan scheduled by s. It returns a Timer that can be used to cancel the call using its Stop method.

If the caller want to terminate the execution plan halfway, it must stop the timer and ensure that the timer is stopped actually, since in the current implementation, there is a gap between the expiring and the restarting of the timer. The wait time for ensuring is short since the gap is very small.

Internally, ScheduleFunc will ask the first execution time (by calling s.Next()) initially, and create a timer if the execution time is non-zero. Afterwards, it will ask the next execution time each time f is about to be executed, and f will be called at the next execution time if the time is non-zero.

func (*TimingWheel) Start

func (tw *TimingWheel) Start()

Start starts the current timing wheel.

func (*TimingWheel) Stop

func (tw *TimingWheel) Stop()

Stop stops the current timing wheel.

If there is any timer's task being running in its own goroutine, Stop does not wait for the task to complete before returning. If the caller needs to know whether the task is completed, it must coordinate with the task explicitly.