Timing Wheel

https://pkg.go.dev/github.com/RussellLuo/timingwheel
Admin
Timing Wheel is a Go implementation of Hierarchical Timing Wheels for efficient scheduling and...
Tokens:2,617
Snippets:30
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install timingwheel package

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Use the go get command to add the package to your project.

```bash
$ go get -u github.com/RussellLuo/timingwheel
```

--------------------------------

### Installation

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Instructions on how to install the timingwheel Go package.

```APIDOC
## Installation

```bash
$ go get -u github.com/RussellLuo/timingwheel
```
```

--------------------------------

### Example outputs

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Expected output for the provided package examples.

```text
Output:
The timer fires
The timer fires
```

```text
Output:
The timer fires
```

```text
Output:
```

--------------------------------

### Examples

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Code examples demonstrating the usage of the timingwheel package.

```APIDOC
## Examples

### ScheduleTimer Example
```go
// Output:
// The timer fires
// The timer fires
```

### StartTimer Example
```go
// Output:
// The timer fires
```

### StopTimer Example
```go
// Output:
// (No output, indicating the timer was stopped before firing)
```
```

--------------------------------

### Start the TimingWheel

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Initializes and starts the timing wheel operation.

```go
func (tw *TimingWheel) Start()
```

--------------------------------

### Start

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Starts the timing wheel, enabling scheduled tasks to run.

```APIDOC
## Start

### Description
Start starts the current timing wheel.

### Method
func (*TimingWheel) Start()

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Timing Wheel API

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

This section covers the core functionalities of the TimingWheel, including creating, starting, stopping, and scheduling timers.

```APIDOC
## TimingWheel API

### Description
Provides functionalities for creating and managing a hierarchical timing wheel for scheduling tasks.

### Methods

#### NewTimingWheel
```go
func NewTimingWheel(tick time.Duration, wheelSize int64) *TimingWheel
```
Creates a new TimingWheel instance.

- **tick** (time.Duration) - The duration of each tick in the timing wheel.
- **wheelSize** (int64) - The size of the timing wheel.

#### Start
```go
func (tw *TimingWheel) Start()
```
Starts the timing wheel, enabling it to process scheduled timers.

#### Stop
```go
func (tw *TimingWheel) Stop()
```
Stops the timing wheel, preventing further processing of timers.

#### AfterFunc
```go
func (tw *TimingWheel) AfterFunc(d time.Duration, f func()) *Timer
```
Schedules a function `f` to be executed after a duration `d`.

- **d** (time.Duration) - The delay before the function is executed.
- **f** (func()) - The function to execute.

Returns a `*Timer` that can be used to cancel the execution.

#### ScheduleFunc
```go
func (tw *TimingWheel) ScheduleFunc(s Scheduler, f func()) (t *Timer)
```
Schedules a function `f` based on a `Scheduler`.

- **s** (Scheduler) - An object that determines the next execution time.
- **f** (func()) - The function to execute.

Returns a `*Timer` that can be used to cancel the execution.
```

--------------------------------

### Poll Expired Elements from DelayQueue

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel/delayqueue

Continuously waits for elements to expire and sends them to the channel C. This function runs in an infinite loop and requires an exit channel and a function to get the current time.

```go
func (dq *DelayQueue) Poll(exitC chan struct{}, nowF func() int64)
```

--------------------------------

### Run benchmarks

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Execute the package benchmarks to measure performance.

```bash
$ 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
```

--------------------------------

### Create a new TimingWheel

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Initializes a TimingWheel with a specific tick duration and wheel size.

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

--------------------------------

### Create New DelayQueue Instance

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel/delayqueue

Creates a new instance of DelayQueue with a specified size. This function initializes the delay queue.

```go
func New(size int) *DelayQueue
```

--------------------------------

### TimingWheel structure

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

The main structure for the Hierarchical Timing Wheels implementation.

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

--------------------------------

### Schedule a function with TimingWheel

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Schedules a function to run based on a provided scheduler. Returns a Timer that can be used to cancel the execution.

```go
func (tw *TimingWheel) ScheduleFunc(s Scheduler, f func()) (t *Timer)
```

--------------------------------

### DelayQueue Initialization and Operations

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel/delayqueue

Methods for creating a new DelayQueue, adding elements, and polling for expired items.

```APIDOC
## func New(size int) *DelayQueue

### Description
Creates an instance of DelayQueue with the specified size.

### Parameters
- **size** (int) - Required - The size of the queue.

## func (*DelayQueue) Offer(elem interface{}, expiration int64)

### Description
Inserts an element into the queue with a specific expiration time.

### Parameters
- **elem** (interface{}) - Required - The element to be added.
- **expiration** (int64) - Required - The expiration timestamp.

## func (*DelayQueue) Poll(exitC chan struct{}, nowF func() int64)

### Description
Starts an infinite loop that waits for elements to expire and sends them to the channel C.

### Parameters
- **exitC** (chan struct{}) - Required - Channel to signal exit.
- **nowF** (func() int64) - Required - Function to retrieve the current time.
```

--------------------------------

### Schedule a function with AfterFunc

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Executes a function after a specified duration, returning a Timer for potential cancellation.

```go
func (tw *TimingWheel) AfterFunc(d time.Duration, f func()) *Timer
```

--------------------------------

### Define Scheduler interface

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

The Scheduler interface defines how tasks are scheduled for execution.

```go
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
}
```

--------------------------------

### Offer Element to DelayQueue

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel/delayqueue

Inserts an element into the DelayQueue with a specified expiration time. The element will only be available after its expiration.

```go
func (dq *DelayQueue) Offer(elem interface{}, expiration int64)
```

--------------------------------

### Timer structure

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Timer represents a single event that executes a task upon expiration.

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

--------------------------------

### ScheduleFunc

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Schedules a function to be called according to a given scheduler. Returns a timer for cancellation.

```APIDOC
## ScheduleFunc

### Description
ScheduleFunc calls a given function `f` 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 wants 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.

### Method
func (*TimingWheel) ScheduleFunc(s Scheduler, f func()) (t *Timer)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **t** (*Timer) - A timer that can be used to cancel the scheduled function call.

#### Response Example
None
```

--------------------------------

### Timer API

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Details on the Timer type, which represents a scheduled event and provides methods to manage its lifecycle.

```APIDOC
## Timer API

### Description
Represents a single event that will be executed at a scheduled time. Provides functionality to cancel the event before it fires.

### Methods

#### Stop
```go
func (t *Timer) Stop() bool
```
Prevents the Timer from firing. Returns `true` if the call stops the timer, `false` if the timer has already expired or been stopped.

Note: If the timer has already expired and its task has started, `Stop` does not wait for the task to complete.
```

--------------------------------

### Scheduler Interface

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Defines the Scheduler interface, which is used to determine the next execution time for scheduled tasks.

```APIDOC
## Scheduler Interface

### Description
Defines the contract for objects that determine the execution plan of a task.

### Methods

#### Next
```go
func (s Scheduler) Next(time.Time) time.Time
```
Returns the next execution time after the given previous time. Returns a zero time if no next time is scheduled.

- **previousTime** (time.Time) - The previous execution time.

All times must be UTC.
```

--------------------------------

### Stop the TimingWheel

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Stops the timing wheel. Note that it does not wait for currently running tasks to complete.

```go
func (tw *TimingWheel) Stop()
```

--------------------------------

### Stop

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Stops the timing wheel. Does not wait for running tasks to complete.

```APIDOC
## Stop

### Description
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.

### Method
func (*TimingWheel) Stop()

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Define DelayQueue Type

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel/delayqueue

Defines the DelayQueue struct, which is an unbounded blocking queue for delayed elements. Elements can only be taken when their delay has expired.

```go
type DelayQueue struct {
	C chan interface{}
	// contains filtered or unexported fields
}
```

--------------------------------

### Stop a Timer

Source: https://pkg.go.dev/github.com/RussellLuo/timingwheel

Stops the timer and returns true if successful, or false if already expired or stopped.

```go
func (t *Timer) Stop() bool
```
Tokens:
Raw