rate: add TokenAt and Tokens methods to Limiter.
Rename "now" to "t" in rate functions.
Improve comments in package rate and its test.
Fixes golang/go#50035
Change-Id: Icd84ce85d31ee8298b0814492f0856e1953923c8
Reviewed-on: https://go-review.googlesource.com/c/time/+/423042
Run-TryBot: Sameer Ajmani <sameer@golang.org>
Reviewed-by: Russ Cox <rsc@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
diff --git a/rate/rate.go b/rate/rate.go
index 79a6bb6..8f7c29f 100644
--- a/rate/rate.go
+++ b/rate/rate.go
@@ -80,6 +80,19 @@
return lim.burst
}
+// TokensAt returns the number of tokens available at time t.
+func (lim *Limiter) TokensAt(t time.Time) float64 {
+ lim.mu.Lock()
+ _, _, tokens := lim.advance(t) // does not mutute lim
+ lim.mu.Unlock()
+ return tokens
+}
+
+// Tokens returns the number of tokens available now.
+func (lim *Limiter) Tokens() float64 {
+ return lim.TokensAt(time.Now())
+}
+
// NewLimiter returns a new Limiter that allows events up to rate r and permits
// bursts of at most b tokens.
func NewLimiter(r Limit, b int) *Limiter {
@@ -89,16 +102,16 @@
}
}
-// Allow is shorthand for AllowN(time.Now(), 1).
+// Allow reports whether an event may happen now.
func (lim *Limiter) Allow() bool {
return lim.AllowN(time.Now(), 1)
}
-// AllowN reports whether n events may happen at time now.
+// AllowN reports whether n events may happen at time t.
// Use this method if you intend to drop / skip events that exceed the rate limit.
// Otherwise use Reserve or Wait.
-func (lim *Limiter) AllowN(now time.Time, n int) bool {
- return lim.reserveN(now, n, 0).ok
+func (lim *Limiter) AllowN(t time.Time, n int) bool {
+ return lim.reserveN(t, n, 0).ok
}
// A Reservation holds information about events that are permitted by a Limiter to happen after a delay.
@@ -131,11 +144,11 @@
// before taking the reserved action. Zero duration means act immediately.
// InfDuration means the limiter cannot grant the tokens requested in this
// Reservation within the maximum wait time.
-func (r *Reservation) DelayFrom(now time.Time) time.Duration {
+func (r *Reservation) DelayFrom(t time.Time) time.Duration {
if !r.ok {
return InfDuration
}
- delay := r.timeToAct.Sub(now)
+ delay := r.timeToAct.Sub(t)
if delay < 0 {
return 0
}
@@ -150,7 +163,7 @@
// CancelAt indicates that the reservation holder will not perform the reserved action
// and reverses the effects of this Reservation on the rate limit as much as possible,
// considering that other reservations may have already been made.
-func (r *Reservation) CancelAt(now time.Time) {
+func (r *Reservation) CancelAt(t time.Time) {
if !r.ok {
return
}
@@ -158,7 +171,7 @@
r.lim.mu.Lock()
defer r.lim.mu.Unlock()
- if r.lim.limit == Inf || r.tokens == 0 || r.timeToAct.Before(now) {
+ if r.lim.limit == Inf || r.tokens == 0 || r.timeToAct.Before(t) {
return
}
@@ -170,18 +183,18 @@
return
}
// advance time to now
- now, _, tokens := r.lim.advance(now)
+ t, _, tokens := r.lim.advance(t)
// calculate new number of tokens
tokens += restoreTokens
if burst := float64(r.lim.burst); tokens > burst {
tokens = burst
}
// update state
- r.lim.last = now
+ r.lim.last = t
r.lim.tokens = tokens
if r.timeToAct == r.lim.lastEvent {
prevEvent := r.timeToAct.Add(r.limit.durationFromTokens(float64(-r.tokens)))
- if !prevEvent.Before(now) {
+ if !prevEvent.Before(t) {
r.lim.lastEvent = prevEvent
}
}
@@ -208,8 +221,8 @@
// Use this method if you wish to wait and slow down in accordance with the rate limit without dropping events.
// If you need to respect a deadline or cancel the delay, use Wait instead.
// To drop or skip events exceeding rate limit, use Allow instead.
-func (lim *Limiter) ReserveN(now time.Time, n int) *Reservation {
- r := lim.reserveN(now, n, InfDuration)
+func (lim *Limiter) ReserveN(t time.Time, n int) *Reservation {
+ r := lim.reserveN(t, n, InfDuration)
return &r
}
@@ -234,7 +247,7 @@
}
// wait is the internal implementation of WaitN.
-func (lim *Limiter) wait(ctx context.Context, n int, now time.Time, newTimer func(d time.Duration) (<-chan time.Time, func() bool, func())) error {
+func (lim *Limiter) wait(ctx context.Context, n int, t time.Time, newTimer func(d time.Duration) (<-chan time.Time, func() bool, func())) error {
lim.mu.Lock()
burst := lim.burst
limit := lim.limit
@@ -252,15 +265,15 @@
// Determine wait limit
waitLimit := InfDuration
if deadline, ok := ctx.Deadline(); ok {
- waitLimit = deadline.Sub(now)
+ waitLimit = deadline.Sub(t)
}
// Reserve
- r := lim.reserveN(now, n, waitLimit)
+ r := lim.reserveN(t, n, waitLimit)
if !r.ok {
return fmt.Errorf("rate: Wait(n=%d) would exceed context deadline", n)
}
// Wait if necessary
- delay := r.DelayFrom(now)
+ delay := r.DelayFrom(t)
if delay == 0 {
return nil
}
@@ -287,13 +300,13 @@
// SetLimitAt sets a new Limit for the limiter. The new Limit, and Burst, may be violated
// or underutilized by those which reserved (using Reserve or Wait) but did not yet act
// before SetLimitAt was called.
-func (lim *Limiter) SetLimitAt(now time.Time, newLimit Limit) {
+func (lim *Limiter) SetLimitAt(t time.Time, newLimit Limit) {
lim.mu.Lock()
defer lim.mu.Unlock()
- now, _, tokens := lim.advance(now)
+ t, _, tokens := lim.advance(t)
- lim.last = now
+ lim.last = t
lim.tokens = tokens
lim.limit = newLimit
}
@@ -304,13 +317,13 @@
}
// SetBurstAt sets a new burst size for the limiter.
-func (lim *Limiter) SetBurstAt(now time.Time, newBurst int) {
+func (lim *Limiter) SetBurstAt(t time.Time, newBurst int) {
lim.mu.Lock()
defer lim.mu.Unlock()
- now, _, tokens := lim.advance(now)
+ t, _, tokens := lim.advance(t)
- lim.last = now
+ lim.last = t
lim.tokens = tokens
lim.burst = newBurst
}
@@ -318,7 +331,7 @@
// reserveN is a helper method for AllowN, ReserveN, and WaitN.
// maxFutureReserve specifies the maximum reservation wait duration allowed.
// reserveN returns Reservation, not *Reservation, to avoid allocation in AllowN and WaitN.
-func (lim *Limiter) reserveN(now time.Time, n int, maxFutureReserve time.Duration) Reservation {
+func (lim *Limiter) reserveN(t time.Time, n int, maxFutureReserve time.Duration) Reservation {
lim.mu.Lock()
defer lim.mu.Unlock()
@@ -327,7 +340,7 @@
ok: true,
lim: lim,
tokens: n,
- timeToAct: now,
+ timeToAct: t,
}
} else if lim.limit == 0 {
var ok bool
@@ -339,11 +352,11 @@
ok: ok,
lim: lim,
tokens: lim.burst,
- timeToAct: now,
+ timeToAct: t,
}
}
- now, last, tokens := lim.advance(now)
+ t, last, tokens := lim.advance(t)
// Calculate the remaining number of tokens resulting from the request.
tokens -= float64(n)
@@ -365,12 +378,12 @@
}
if ok {
r.tokens = n
- r.timeToAct = now.Add(waitDuration)
+ r.timeToAct = t.Add(waitDuration)
}
// Update state
if ok {
- lim.last = now
+ lim.last = t
lim.tokens = tokens
lim.lastEvent = r.timeToAct
} else {
@@ -383,20 +396,20 @@
// advance calculates and returns an updated state for lim resulting from the passage of time.
// lim is not changed.
// advance requires that lim.mu is held.
-func (lim *Limiter) advance(now time.Time) (newNow time.Time, newLast time.Time, newTokens float64) {
+func (lim *Limiter) advance(t time.Time) (newT time.Time, newLast time.Time, newTokens float64) {
last := lim.last
- if now.Before(last) {
- last = now
+ if t.Before(last) {
+ last = t
}
// Calculate the new number of tokens, due to time that passed.
- elapsed := now.Sub(last)
+ elapsed := t.Sub(last)
delta := lim.limit.tokensFromDuration(elapsed)
tokens := lim.tokens + delta
if burst := float64(lim.burst); tokens > burst {
tokens = burst
}
- return now, last, tokens
+ return t, last, tokens
}
// durationFromTokens is a unit conversion function from the number of tokens to the duration
diff --git a/rate/rate_test.go b/rate/rate_test.go
index 7bdd74a..d0d9149 100644
--- a/rate/rate_test.go
+++ b/rate/rate_test.go
@@ -68,14 +68,19 @@
)
type allow struct {
- t time.Time
- n int
- ok bool
+ t time.Time
+ toks float64
+ n int
+ ok bool
}
func run(t *testing.T, lim *Limiter, allows []allow) {
t.Helper()
for i, allow := range allows {
+ if toks := lim.TokensAt(allow.t); toks != allow.toks {
+ t.Errorf("step %d: lim.TokensAt(%v) = %v want %v",
+ i, allow.t, toks, allow.toks)
+ }
ok := lim.AllowN(allow.t, allow.n)
if ok != allow.ok {
t.Errorf("step %d: lim.AllowN(%v, %v) = %v want %v",
@@ -86,49 +91,49 @@
func TestLimiterBurst1(t *testing.T) {
run(t, NewLimiter(10, 1), []allow{
- {t0, 1, true},
- {t0, 1, false},
- {t0, 1, false},
- {t1, 1, true},
- {t1, 1, false},
- {t1, 1, false},
- {t2, 2, false}, // burst size is 1, so n=2 always fails
- {t2, 1, true},
- {t2, 1, false},
+ {t0, 1, 1, true},
+ {t0, 0, 1, false},
+ {t0, 0, 1, false},
+ {t1, 1, 1, true},
+ {t1, 0, 1, false},
+ {t1, 0, 1, false},
+ {t2, 1, 2, false}, // burst size is 1, so n=2 always fails
+ {t2, 1, 1, true},
+ {t2, 0, 1, false},
})
}
func TestLimiterBurst3(t *testing.T) {
run(t, NewLimiter(10, 3), []allow{
- {t0, 2, true},
- {t0, 2, false},
- {t0, 1, true},
- {t0, 1, false},
- {t1, 4, false},
- {t2, 1, true},
- {t3, 1, true},
- {t4, 1, true},
- {t4, 1, true},
- {t4, 1, false},
- {t4, 1, false},
- {t9, 3, true},
- {t9, 0, true},
+ {t0, 3, 2, true},
+ {t0, 1, 2, false},
+ {t0, 1, 1, true},
+ {t0, 0, 1, false},
+ {t1, 1, 4, false},
+ {t2, 2, 1, true},
+ {t3, 2, 1, true},
+ {t4, 2, 1, true},
+ {t4, 1, 1, true},
+ {t4, 0, 1, false},
+ {t4, 0, 1, false},
+ {t9, 3, 3, true},
+ {t9, 0, 0, true},
})
}
func TestLimiterJumpBackwards(t *testing.T) {
run(t, NewLimiter(10, 3), []allow{
- {t1, 1, true}, // start at t1
- {t0, 1, true}, // jump back to t0, two tokens remain
- {t0, 1, true},
- {t0, 1, false},
- {t0, 1, false},
- {t1, 1, true}, // got a token
- {t1, 1, false},
- {t1, 1, false},
- {t2, 1, true}, // got another token
- {t2, 1, false},
- {t2, 1, false},
+ {t1, 3, 1, true}, // start at t1
+ {t0, 2, 1, true}, // jump back to t0, two tokens remain
+ {t0, 1, 1, true},
+ {t0, 0, 1, false},
+ {t0, 0, 1, false},
+ {t1, 1, 1, true}, // got a token
+ {t1, 0, 1, false},
+ {t1, 0, 1, false},
+ {t2, 1, 1, true}, // got another token
+ {t2, 0, 1, false},
+ {t2, 0, 1, false},
})
}
@@ -299,6 +304,7 @@
}
}
+// A request provides the arguments to lim.reserveN(t, n) and the expected results (act, ok).
type request struct {
t time.Time
n int
@@ -324,6 +330,9 @@
return runReserveMax(t, lim, req, InfDuration)
}
+// runReserveMax attempts to reserve req.n tokens at time req.t, limiting the delay until action to
+// maxReserve. It checks whether the response matches req.act and req.ok. If not, it reports a test
+// error including the difference from expected durations in multiples of d (global constant).
func runReserveMax(t *testing.T, lim *Limiter, req request, maxReserve time.Duration) *Reservation {
t.Helper()
r := lim.reserveN(req.t, req.n, maxReserve)
@@ -347,10 +356,10 @@
runReserve(t, lim, request{t0, 3, t1, false}) // should return false because n > Burst
runReserve(t, lim, request{t0, 2, t0, true})
- run(t, lim, []allow{{t1, 2, false}}) // not enough tokens - don't allow
+ run(t, lim, []allow{{t1, 1, 2, false}}) // not enough tokens - don't allow
runReserve(t, lim, request{t1, 2, t2, true})
- run(t, lim, []allow{{t1, 1, false}}) // negative tokens - don't allow
- run(t, lim, []allow{{t3, 1, true}})
+ run(t, lim, []allow{{t1, -1, 1, false}}) // negative tokens - don't allow
+ run(t, lim, []allow{{t3, 1, 1, true}})
}
func TestCancelInvalid(t *testing.T) {
