1 // Copyright 2011 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 package util 6 7 import "time" 8 9 // A Throttle permits throttling of a goroutine by 10 // calling the Throttle method repeatedly. 11 type Throttle struct { 12 f float64 // f = (1-r)/r for 0 < r < 1 13 dt time.Duration // minimum run time slice; >= 0 14 tr time.Duration // accumulated time running 15 ts time.Duration // accumulated time stopped 16 tt time.Time // earliest throttle time (= time Throttle returned + tm) 17 } 18 19 // NewThrottle creates a new Throttle with a throttle value r and 20 // a minimum allocated run time slice of dt: 21 // 22 // r == 0: "empty" throttle; the goroutine is always sleeping 23 // r == 1: full throttle; the goroutine is never sleeping 24 // 25 // A value of r == 0.6 throttles a goroutine such that it runs 26 // approx. 60% of the time, and sleeps approx. 40% of the time. 27 // Values of r < 0 or r > 1 are clamped down to values between 0 and 1. 28 // Values of dt < 0 are set to 0. 29 func NewThrottle(r float64, dt time.Duration) *Throttle { 30 var f float64 31 switch { 32 case r <= 0: 33 f = -1 // indicates always sleep 34 case r >= 1: 35 f = 0 // assume r == 1 (never sleep) 36 default: 37 // 0 < r < 1 38 f = (1 - r) / r 39 } 40 if dt < 0 { 41 dt = 0 42 } 43 return &Throttle{f: f, dt: dt, tt: time.Now().Add(dt)} 44 } 45 46 // Throttle calls time.Sleep such that over time the ratio tr/ts between 47 // accumulated run (tr) and sleep times (ts) approximates the value 1/(1-r) 48 // where r is the throttle value. Throttle returns immediately (w/o sleeping) 49 // if less than tm ns have passed since the last call to Throttle. 50 func (p *Throttle) Throttle() { 51 if p.f < 0 { 52 select {} // always sleep 53 } 54 55 t0 := time.Now() 56 if t0.Before(p.tt) { 57 return // keep running (minimum time slice not exhausted yet) 58 } 59 60 // accumulate running time 61 p.tr += t0.Sub(p.tt) + p.dt 62 63 // compute sleep time 64 // Over time we want: 65 // 66 // tr/ts = r/(1-r) 67 // 68 // Thus: 69 // 70 // ts = tr*f with f = (1-r)/r 71 // 72 // After some incremental run time δr added to the total run time 73 // tr, the incremental sleep-time δs to get to the same ratio again 74 // after waking up from time.Sleep is: 75 if δs := time.Duration(float64(p.tr)*p.f) - p.ts; δs > 0 { 76 time.Sleep(δs) 77 } 78 79 // accumulate (actual) sleep time 80 t1 := time.Now() 81 p.ts += t1.Sub(t0) 82 83 // set earliest next throttle time 84 p.tt = t1.Add(p.dt) 85 } 86