barista.run: barista.run/timing Index | Files | Directories

package timing

import "barista.run/timing"

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

Package Files

misc.go scheduler.go testmode.go time_scheduler.go timerfd_scheduler.go timing.go

func AdvanceBy Uses

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 Uses

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 Uses

func ExitTestMode()

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

func NextTick Uses

func NextTick() time.Time

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

func Now Uses

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 Uses

func Pause()

Pause timing.

func Resume Uses

func Resume()

Resume timing.

func TestMode Uses

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.

type Scheduler Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (s *Scheduler) Close()

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

func (*Scheduler) Every Uses

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 Uses

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 Uses

func (s *Scheduler) Stop()

Stop cancels all further triggers for the scheduler.

func (*Scheduler) Tick Uses

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() { ... }

Directories

PathSynopsis
internal/timerfd

Package timing imports 11 packages (graph) and is imported by 29 packages. Updated 2020-11-23. Refresh now. Tools for package owners.