go-throttle

Package throttle provides functionality to limit the frequency with which code is called

Throttling is of the Trigger() method and depends on the parameters passed (period, trailing).

The period parameter defines how often the throttled code can run. A period of one second means that the throttled code will run at most once per second.

The trailing parameter defines what hapens if Trigger() is called after the throttled code has been started, but before the period is finished. If trailing is false then these triggers are ignored. If trailing is true then the throttled code is executed one more time at the beginning of the next period.

Example with period = time.Second and trailing = false:

Whole seconds after first trigger...|0|0|0|0|1|1|1|1|
Trigger() gets called...............|X| |X| | |X| | |
Throttled code gets called..........|X| | | | |X| | |

Note that the second Trigger() had no effect. The third Trigger() caused immediate execution of the throttled code.

Example with period = time.Second and trailing = true:

Whole seconds after first trigger...|0|0|0|0|1|1|1|1|
Trigger() gets called...............|X| |X| | |X| | |
Throttled code gets called..........|X| | | |X| | | |

Note that the second Trigger() causes the throttled code to get called once the first period is over. The third Trigger() will do the same.

Usage

Throttling execution of a function:

throttle := throttle.ThrottleFunc(period, false, func() {
  fmt.Println("fun, throttled.")
})

go func() {
  for i := 0; i < 5; i++ {
    throttle.Trigger()
    time.Sleep(period / 6)
  }
}()

time.Sleep(2 * period)
throttle.Stop()

// Output: fun, throttled.

Throttling arbitrary code:

package cache

import (
	"time"
	"github.com/boz/go-throttle"
)

type CacheRebuilder struct {
	throttle throttle.Throttle
}

// Create a cache rebuilder which will rebuild the cache at most once every 5 minutes, regardless
// of how often a rebuild is requested.
func NewRebuilder() *CacheRebuilder {
	cr := &CacheRebuilder{NewThrottle(5*time.Minute, true)}

	go func() {
		for cr.throttle.Next() {
			cr.doRebuild()
		}
	}()

	return cr
}

func (cr *CacheRebuilder) Stop() {
	cr.throttle.Stop()
}

func (cr *CacheRebuilder) Rebuild() {
	cr.throttle.Trigger()
}

func (cr *CacheRebuilder) doRebuild() {
	// actually rebuild the cache.
}