| 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 |
Members