relativetime

Documentation

Overview

Package relativetime provides a clock that can be set to track a reference clock with a specified offset and scaling factor, and may start, stop, or adjust tracking parameters while running. It uses a generic interface so that it may be used with clocks using various implementations of time or duration values.

Index

• type Clock
  • func NewClock[T Time[T, D], D Duration, RT RTimer[D]](ref RClock[T, D, RT], at T, scale float64) (c *Clock[T, D, RT])
  • func (c *Clock[T, D, RT]) Active() (active bool)
  • func (c *Clock[T, D, RT]) After(d D) <-chan T
  • func (c *Clock[T, D, RT]) AfterFunc(d D, f func()) *Timer[T, D]
  • func (c *Clock[T, D, RT]) NewTicker(d D) *Ticker[T, D]
  • func (c *Clock[T, D, RT]) NewTimer(d D) *Timer[T, D]
  • func (c *Clock[T, D, RT]) NextAt() (when T)
  • func (c *Clock[T, D, RT]) Now() (now T)
  • func (c *Clock[T, D, RT]) Scale() (scale float64)
  • func (c *Clock[T, D, RT]) Seconds(n float64) D
  • func (c *Clock[T, D, RT]) Set(now T)
  • func (c *Clock[T, D, RT]) SetScale(scale float64)
  • func (c *Clock[T, D, RT]) Since(t T) D
  • func (c *Clock[T, D, RT]) Sleep(d D)
  • func (c *Clock[T, D, RT]) Start()
  • func (c *Clock[T, D, RT]) Step(dt D)
  • func (c *Clock[T, D, RT]) Stop()
  • func (c *Clock[T, D, RT]) Tick(d D) <-chan T
  • func (c *Clock[T, D, RT]) Until(t T) D
• type Duration
• type RClock
• type RTimer
• type Ticker
  • func (t *Ticker[T, D]) C() <-chan T
  • func (t *Ticker[T, D]) Reset(d D)
  • func (t *Ticker[T, D]) Stop()
• type Time
• type Timer
  • func (t *Timer[T, D]) C() <-chan T
  • func (t *Timer[T, D]) Reset(d D) (active bool)
  • func (t *Timer[T, D]) Stop() (active bool)

Types

type Clock

type Clock[T Time[T, D], D Duration, RT RTimer[D]] struct {
	// contains filtered or unexported fields
}

Clock is a clock that tracks a reference clock with a configurable scaling factor.

NOTE: composition with the reference clock would be such a nice feature here, to inherit all the methods of the reference clock. Maybe in a future version of Go... See github.com/noodlebox/clock/mocktime package for an example of using embedding with instantiated generic types for a drop in replacement for a reference clock.

func NewClock

func NewClock[T Time[T, D], D Duration, RT RTimer[D]](ref RClock[T, D, RT], at T, scale float64) (c *Clock[T, D, RT])

NewClock returns a new Clock set to at synchronized to the current time on ref with a scale factor of scale.

func (*Clock[T, D, RT]) Active

func (c *Clock[T, D, RT]) Active() (active bool)

Active returns true if currently tracking the reference clock.

func (*Clock[T, D, RT]) After

func (c *Clock[T, D, RT]) After(d D) <-chan T

After waits for the duration to elapse and then sends the current time on the returned channel. It is equivalent to clock.NewTimer(d).C(). The underlying Timer is not recovered by the garbage collector until the timer fires. If efficiency is a concern, use clock.NewTimer instead and call Timer.Stop if the timer is no longer needed.

func (*Clock[T, D, RT]) AfterFunc

func (c *Clock[T, D, RT]) AfterFunc(d D, f func()) *Timer[T, D]

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 (*Clock[T, D, RT]) NewTicker

func (c *Clock[T, D, RT]) NewTicker(d D) *Ticker[T, D]

NewTicker returns a new Ticker containing a channel that will send the current time on the channel after each tick. The period of the ticks is specified by the duration argument. The ticker will adjust the time interval or drop ticks to make up for slow receivers. The duration d must be greater than zero; if not, NewTicker will panic. Stop the ticker to release associated resources.

func (*Clock[T, D, RT]) NewTimer

func (c *Clock[T, D, RT]) NewTimer(d D) *Timer[T, D]

NewTimer creates a new Timer that will send the current time on its channel after at least duration d.

func (*Clock[T, D, RT]) NextAt

func (c *Clock[T, D, RT]) NextAt() (when T)

NextAt returns the time at which the next scheduled timer should trigger. If no timers are scheduled, returns a zero value.

func (*Clock[T, D, RT]) Now

func (c *Clock[T, D, RT]) Now() (now T)

Now returns the current time.

func (*Clock[T, D, RT]) Scale

func (c *Clock[T, D, RT]) Scale() (scale float64)

Scale returns the scaling factor for tracking the reference clock.

func (*Clock[T, D, RT]) Seconds

func (c *Clock[T, D, RT]) Seconds(n float64) D

Seconds returns a Duration value representing n Seconds. This is provided to allow a relative clock itself to satisfy the reference clock interface.

func (*Clock[T, D, RT]) Set

func (c *Clock[T, D, RT]) Set(now T)

Set sets the local sync point with the current reference time to now. If any timers are active, a value of now earlier than the previous setting may lead to undefined behavior.

func (*Clock[T, D, RT]) SetScale

func (c *Clock[T, D, RT]) SetScale(scale float64)

SetScale sets the scaling factor for tracking the reference clock.

func (*Clock[T, D, RT]) Since

func (c *Clock[T, D, RT]) Since(t T) D

Since returns the time elapsed since t. It is shorthand for clock.Now().Sub(t).

func (*Clock[T, D, RT]) Sleep

func (c *Clock[T, D, RT]) Sleep(d D)

Sleep pauses the current goroutine for at least the duration d. A negative or zero duration causes Sleep to return immediately.

func (*Clock[T, D, RT]) Start

func (c *Clock[T, D, RT]) Start()

Start begins tracking the reference clock, if not already running. It is fine to call Start() on a clock that is already running.

func (*Clock[T, D, RT]) Step

func (c *Clock[T, D, RT]) Step(dt D)

Step advances the local time forward by dt. If any timers are active, a negative value for dt may lead to undefined behavior.

func (*Clock[T, D, RT]) Stop

func (c *Clock[T, D, RT]) Stop()

Stop stops tracking the reference clock, if currently running. It is fine to call Stop() on a clock that is not running.

func (*Clock[T, D, RT]) Tick

func (c *Clock[T, D, RT]) Tick(d D) <-chan T

Tick is a convenience wrapper for NewTicker providing access to the ticking channel only. While Tick is useful for clients that have no need to shut down the Ticker, be aware that without a way to shut it down the underlying Ticker cannot be recovered by the garbage collector; it "leaks". Unlike NewTicker, Tick will return nil if d <= 0.

func (*Clock[T, D, RT]) Until

func (c *Clock[T, D, RT]) Until(t T) D

Until returns the duration until t. It is shorthand for t.Sub(clock.Now()).

type Duration

type Duration interface {
	Seconds() float64
}

Duration is an interface for the minimal API needed for a Duration implementation.

type RClock

type RClock[T Time[T, D], D Duration, TM RTimer[D]] interface {
	Now() T
	Seconds(float64) D
	AfterFunc(D, func()) TM
}

RClock is a generic interface for the minimal API needed to serve as a reference clock.

type RTimer

type RTimer[D Duration] interface {
	Reset(d D) bool
	Stop() bool
}

RTimer is a generic interface for the minimal API needed for a reference Timer implementation.

type Ticker

type Ticker[T Time[T, D], D Duration] struct {
	// contains filtered or unexported fields
}

A Ticker provides a channel that delivers “ticks” of a clock at intervals.

func (*Ticker[T, D]) C

func (t *Ticker[T, D]) C() <-chan T

C returns the channel on which the ticks are delivered.

func (*Ticker[T, D]) Reset

func (t *Ticker[T, D]) Reset(d D)

Reset stops a ticker and resets its period to the specified duration. The next tick will arrive after the new period elapses. The duration d must be greater than zero; if not, Reset will panic.

func (*Ticker[T, D]) Stop

func (t *Ticker[T, D]) Stop()

Stop turns off a ticker. After Stop, no more ticks will be sent. Stop does not close the channel, to prevent a concurrent goroutine reading from the channel from seeing an erroneous "tick".

type Time

type Time[T any, D Duration] interface {
	Add(D) T
	Sub(T) D
	After(T) bool
	Before(T) bool
	Equal(T) bool
	IsZero() bool
}

Time is a generic interface for the minimal API needed for a Time implementation.

type Timer

type Timer[T Time[T, D], D Duration] struct {
	// contains filtered or unexported fields
}

The Timer type represents a single event. When the Timer expires, the current time will be sent on the channel returned by C(), unless the Timer was created by AfterFunc. A Timer must be created with NewTimer or AfterFunc.

func (*Timer[T, D]) C

func (t *Timer[T, D]) C() <-chan T

C returns the channel on which the ticks are delivered.

func (*Timer[T, D]) Reset

func (t *Timer[T, D]) Reset(d D) (active bool)

Reset changes the timer to expire after duration d. It returns true if the timer had been active, false if the timer had expired or been stopped.

func (*Timer[T, D]) Stop

func (t *Timer[T, D]) Stop() (active 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. Stop does not close the channel, to prevent a read from the channel succeeding incorrectly.