timer

Documentation

Overview

Package timer implements a hierarchical timer wheel for efficient timeout management in event-driven I/O engines.

Index

• Constants
• type Entry
• type TimeoutKind
• type Wheel
  • func New(onExpire func(fd int, kind TimeoutKind)) *Wheel
  • func (w *Wheel) Cancel(fd int)
  • func (w *Wheel) Len() int
  • func (w *Wheel) Schedule(fd int, timeout time.Duration, kind TimeoutKind)
  • func (w *Wheel) ScheduleAt(fd int, timeout time.Duration, kind TimeoutKind, nowNs int64)
  • func (w *Wheel) Tick() int

Constants

const (
	// WheelSize is the number of slots in the timer wheel (power of 2 for fast modulo).
	WheelSize = 8192
	// TickInterval is the granularity of the timer wheel.
	TickInterval = 100 * time.Millisecond
)

Types

type Entry

type Entry struct {
	FD       int
	Deadline int64 // unix nano
	Kind     TimeoutKind
	// contains filtered or unexported fields
}

Entry represents a scheduled timeout.

type TimeoutKind

type TimeoutKind uint8

TimeoutKind identifies the type of timeout.

const (
	ReadTimeout TimeoutKind = iota
	WriteTimeout
	IdleTimeout
)

Timeout kinds for the timer wheel.

type Wheel

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

Wheel is a hashed timer wheel with O(1) schedule and cancel.

func New

func New(onExpire func(fd int, kind TimeoutKind)) *Wheel

New creates a timer wheel that calls onExpire for each expired entry.

func (*Wheel) Cancel

func (w *Wheel) Cancel(fd int)

Cancel removes any pending timeout for the given FD.

func (*Wheel) Len

func (w *Wheel) Len() int

Len returns the number of tracked FDs (approximate).

func (*Wheel) Schedule

func (w *Wheel) Schedule(fd int, timeout time.Duration, kind TimeoutKind)

Schedule registers a timeout for the given FD. Any previous timeout for the same FD is logically cancelled (the old entry is ignored on expiry).

func (*Wheel) ScheduleAt

func (w *Wheel) ScheduleAt(fd int, timeout time.Duration, kind TimeoutKind, nowNs int64)

ScheduleAt is like Schedule but accepts a pre-computed now timestamp (UnixNano) to avoid redundant time.Now() calls when scheduling multiple timeouts in the same request processing cycle.

func (*Wheel) Tick

func (w *Wheel) Tick() int

Tick advances the wheel and fires expired entries. Returns the number of entries that expired. Call this from the event loop after processing I/O events.