timing

Documentation

Overview

Package timing provides a testable interface for timing and scheduling.

This makes it simple to update a module at a fixed interval or at a fixed point in time.

Typically, modules will make a scheduler:

mod.sch = timing.NewScheduler()

and use the scheduling calls to control the update timing:

mod.sch.Every(time.Second)

The Stream() goroutine will then loop over the ticker, and update the module with fresh information:

    for range mod.sch.C {
	  // update code.
    }

This will automatically suspend processing when the bar is hidden.

Modules should also use timing.Now() instead of time.Now() to control time during tests, as well as correctly track the machine's time zone.

Index

• func AdvanceBy(duration time.Duration) time.Time
• func AdvanceTo(newTime time.Time) time.Time
• func ExitTestMode()
• func NextTick() time.Time
• func Now() time.Time
• func Pause()
• func Resume()
• func TestMode()
• type Scheduler
  • func NewRealtimeScheduler() (*Scheduler, error)
  • func NewScheduler() *Scheduler
  • func (s *Scheduler) After(delay time.Duration) *Scheduler
  • func (s *Scheduler) At(when time.Time) *Scheduler
  • func (s *Scheduler) Close()
  • func (s *Scheduler) Every(interval time.Duration) *Scheduler
  • func (s *Scheduler) EveryAlign(interval time.Duration, offset time.Duration) *Scheduler
  • func (s *Scheduler) Stop()
  • func (s *Scheduler) Tick() bool

Functions

func AdvanceBy

func AdvanceBy(duration time.Duration) time.Time

AdvanceBy increments the test time by the given duration, and triggers any schedulers that were scheduled in the meantime.

func AdvanceTo

func AdvanceTo(newTime time.Time) time.Time

AdvanceTo increments the test time to the given time, and triggers any schedulers that were scheduled in the meantime.

func ExitTestMode

func ExitTestMode()

ExitTestMode exits test mode for all schedulers. Any schedulers created after this call will be real.

func NextTick

func NextTick() time.Time

NextTick triggers the next scheduler and returns the trigger time. It also advances test time to match.

func Now

func Now() time.Time

Now returns the current time, in the machine's local time zone.

IMPORTANT: This function differs from time.Now() in that the time zone can change between invocations. Use timing.Now().Local() to get a consistent zone, however note that the zone will be the machine's zone at the start of the bar and may be out of date.

func Pause

func Pause()

Pause timing.

func Resume

func Resume()

Resume timing.

func TestMode

func TestMode()

TestMode sets test mode for all schedulers. In test mode schedulers do not fire automatically, and time does not pass at all, until NextTick() or Advance* is called.

Types

type Scheduler

type Scheduler struct {
	// A channel that receives an empty struct for each tick of the scheduler.
	C <-chan struct{}
	// contains filtered or unexported fields
}

Scheduler represents a trigger that can be repeating or one-off, and is intrinsically tied to the running bar. This means that if the trigger condition occurs while the bar is paused, it will not fire until the bar is next resumed, making it ideal for scheduling work that should only be performed while the bar is active.

func NewRealtimeScheduler

func NewRealtimeScheduler() (*Scheduler, error)

NewRealtimeScheduler creates a scheduler backed by system real-time clock.

It properly handles system suspend (sleep mode) and time adjustments. For periodic timers, it triggers immediately whenever time changes discontinuously. For one-shot timers (At and After), it will fire immediately if the time is skipped over the set trigger time, and will properly wait for it otherwise.

This scheduler is only properly supported on Linux. On other systems, plain scheduler based on "time" package is returned.

In order to clean up resources associated with it, remember to call Stop().

func NewScheduler

func NewScheduler() *Scheduler

NewScheduler creates a new scheduler.

The scheduler is backed by "time" package. Its "At" implementation is unreliable, as it's unable to take system suspend and time adjustments into account.

func (*Scheduler) After

func (s *Scheduler) After(delay time.Duration) *Scheduler

After sets the scheduler to trigger after a delay. This will replace any pending triggers.

func (*Scheduler) At

func (s *Scheduler) At(when time.Time) *Scheduler

At sets the scheduler to trigger a specific time. This will replace any pending triggers.

func (*Scheduler) Close

func (s *Scheduler) Close()

Close cleans up all resources allocated by the scheduler, if necessary.

func (*Scheduler) Every

func (s *Scheduler) Every(interval time.Duration) *Scheduler

Every sets the scheduler to trigger at an interval. This will replace any pending triggers.

func (*Scheduler) EveryAlign

func (s *Scheduler) EveryAlign(interval time.Duration, offset time.Duration) *Scheduler

EveryAlign sets the scheduler to trigger at an interval.

Offset specifies the scheduler alignment. For example, if interval=1min, and offset=11s, the timer will trigger every minute at exactly :11 seconds of the underlying clock. This makes most sense for schedulers based on the real time clock. Usually offset should be zero. A clock that displays the time with minute precision should probably update at :00 seconds, and interval=1min and offset=0 do exactly that.

This will replace any pending triggers.

func (*Scheduler) Stop

func (s *Scheduler) Stop()

Stop cancels all further triggers for the scheduler.

func (*Scheduler) Tick

func (s *Scheduler) Tick() bool

Tick waits until the next tick of the scheduler. Equivalent to <-scheduler.C, but returns true to allow for sch.Tick() { ... }