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

    Constants

    This section is empty.

    Variables

    This section is empty.

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

                                        GOOS=linux, GOARCH=amd64

                                        Directories

                                        Path Synopsis
                                        internal