timerqueue

README

timerqueue

The timerqueue package implements a priority queue for objects scheduled to perform actions at clock times.

Example: Scheduling timers

The following code declares an object implementing the Timer interface, creates a timerqueue, and adds three events to the timerqueue.

type event int

func (e event) OnTimer(t time.Time) {
    fmt.Printf("event.OnTimer %d fired at %v\n", int(e), t)
}

queue := timerqueue.New()
queue.Schedule(event(1), time.Date(2015, 1, 1, 0, 0, 0, 0, time.UTC))
queue.Schedule(event(2), time.Date(2015, 1, 3, 0, 0, 0, 0, time.UTC))
queue.Schedule(event(3), time.Date(2015, 1, 2, 0, 0, 0, 0, time.UTC))

Example: Peeking at the next timer to be scheduled

Using the queue initialized in the first example, the following code examines the head of the timerqueue and outputs the id and time of the event found there.

e, t := queue.PeekFirst()
if e != nil {
    fmt.Printf("Event %d will be first to fire at %v.\n", int(e.(event)), t)
    fmt.Printf("%d events remain in the timerqueue.", queue.Len())
}

Output:

Event 1 will be first to fire at 2015-01-01 00:00:00 +0000 UTC.
3 events remain in the timerqueue.

Example: Popping the next timer to be scheduled

Using the queue initialized in the first example, this code removes the next timer to be executed until the queue is empty.

for queue.Len() > 0 {
    e, t := queue.PopFirst()
    fmt.Printf("Event %d fires at %v.\n", int(e.(event)), t)
}

Output:

Event 1 fires at 2015-01-01 00:00:00 +0000 UTC.
Event 3 fires at 2015-01-02 00:00:00 +0000 UTC.
Event 2 fires at 2015-01-03 00:00:00 +0000 UTC.

Example: Issuing OnTimer callbacks with Advance

The final example shows how to dispatch OnTimer callbacks to timers using the timerqueue's Advance method.

Advance calls the OnTimer method for each timer scheduled before the requested time. Timers are removed from the timerqueue in order of their scheduling.

// Call the OnTimer method for each event scheduled before
// January 10, 2015. Pop the called timer from the queue.
queue.Advance(time.Date(2015, 1, 10, 0, 0, 0, 0, time.UTC))

Output:

event.OnTimer 1 fired at 2015-01-01 00:00:00 +0000 UTC.
event.OnTimer 3 fired at 2015-01-02 00:00:00 +0000 UTC.
event.OnTimer 2 fired at 2015-01-03 00:00:00 +0000 UTC.

Documentation

Overview

Package timerqueue implements a priority queue for objects scheduled at a particular time.

Index

• type Queue
  • func New() *Queue
  • func (q *Queue) Advance(tm time.Time)
  • func (q *Queue) Clear()
  • func (q *Queue) GetTime(t Timer) (tm time.Time, err error)
  • func (q *Queue) IsScheduled(t Timer) bool
  • func (q *Queue) Len() int
  • func (q *Queue) PeekFirst() (t Timer, tm time.Time)
  • func (q *Queue) PopFirst() (t Timer, tm time.Time)
  • func (q *Queue) Schedule(t Timer, tm time.Time)
  • func (q *Queue) Unschedule(t Timer)
• type Timer

Examples

• Queue

Types

type Queue

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

Queue is a time-sorted collection of Timer objects.

Example

Schedule several events with a timerqueue, and dispatch them by calling Advance.

package main

import (
	"fmt"
	"time"

	"github.com/beevik/timerqueue"
)

type event int

func (e event) OnTimer(t time.Time) {
	fmt.Printf("  Event %d executed at %v\n", int(e), t)
}

// Schedule several events with a timerqueue, and dispatch
// them by calling Advance.
func main() {
	queue := timerqueue.New()

	// Schedule an event each day from Jan 1 to Jan 7, 2015.
	tm := time.Date(2015, 1, 1, 0, 0, 0, 0, time.UTC)
	for i := 1; i <= 7; i++ {
		queue.Schedule(event(i), tm)
		tm = tm.Add(24 * time.Hour)
	}

	fmt.Println("Advancing to Jan 4...")
	queue.Advance(time.Date(2015, 1, 4, 0, 0, 0, 0, time.UTC))

	fmt.Println("Advancing to Jan 10...")
	queue.Advance(time.Date(2015, 1, 10, 0, 0, 0, 0, time.UTC))

}

Output:

Advancing to Jan 4...
  Event 1 executed at 2015-01-01 00:00:00 +0000 UTC
  Event 2 executed at 2015-01-02 00:00:00 +0000 UTC
  Event 3 executed at 2015-01-03 00:00:00 +0000 UTC
  Event 4 executed at 2015-01-04 00:00:00 +0000 UTC
Advancing to Jan 10...
  Event 5 executed at 2015-01-05 00:00:00 +0000 UTC
  Event 6 executed at 2015-01-06 00:00:00 +0000 UTC
  Event 7 executed at 2015-01-07 00:00:00 +0000 UTC

func New

func New() *Queue

New creates a new timer priority queue.

func (*Queue) Advance

func (q *Queue) Advance(tm time.Time)

Advance executes OnTimer callbacks for all timers scheduled to be run before the time 'tm'. Executed timers are removed from the timer queue.

func (*Queue) Clear

func (q *Queue) Clear()

Clear unschedules all currently scheduled timers.

func (*Queue) GetTime

func (q *Queue) GetTime(t Timer) (tm time.Time, err error)

GetTime returns the time at which the timer is scheduled. If the timer isn't currently scheduled, an error is returned.

func (*Queue) IsScheduled

func (q *Queue) IsScheduled(t Timer) bool

IsScheduled returns true if the timer is currently scheduled.

func (*Queue) Len

func (q *Queue) Len() int

Len returns the current number of timer objects in the queue.

func (*Queue) PeekFirst

func (q *Queue) PeekFirst() (t Timer, tm time.Time)

PeekFirst returns the next timer to be scheduled and the time at which it is scheduled to run. It does not modify the contents of the timer queue.

func (*Queue) PopFirst

func (q *Queue) PopFirst() (t Timer, tm time.Time)

PopFirst removes and returns the next timer to be scheduled and the time at which it is scheduled to run.

func (*Queue) Schedule

func (q *Queue) Schedule(t Timer, tm time.Time)

Schedule schedules a timer for exectuion at time tm. If the timer was already scheduled, it is rescheduled.

func (*Queue) Unschedule

func (q *Queue) Unschedule(t Timer)

Unschedule unschedules a timer's execution.

type Timer

type Timer interface {
	OnTimer(t time.Time)
}

Timer is an interface that types implement to schedule and receive OnTimer callbacks.