Documentation
¶
Overview ¶
The key observation and some code (shr) is borrowed from golang.org/x/time/rate/rate.go
Index ¶
- Constants
- type BurstLimiter
- func (lim *BurstLimiter) Allow() bool
- func (lim *BurstLimiter) AllowN(n int) bool
- func (lim *BurstLimiter) Burst() int
- func (lim *BurstLimiter) GetToken()
- func (lim *BurstLimiter) GetTokenN(n int)
- func (lim *BurstLimiter) PutToken()
- func (lim *BurstLimiter) PutTokenN(n int)
- func (lim *BurstLimiter) Reserve(ctx context.Context) *Reservation
- func (lim *BurstLimiter) ReserveN(ctx context.Context, n int) *Reservation
- func (lim *BurstLimiter) Wait(ctx context.Context) (err error)
- func (lim *BurstLimiter) WaitN(ctx context.Context, n int) (err error)
- type Reservation
Constants ¶
const InfDuration = time.Duration(1<<63 - 1)
InfDuration is the duration returned by Delay when a Reservation is not OK.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BurstLimiter ¶
type BurstLimiter struct {
// contains filtered or unexported fields
}
A BurstLimiter controls how frequently events are allowed to happen. It implements a "token bucket" of size b, initially full and refilled at rate r tokens per second. Informally, in any large enough time interval, the BurstLimiter limits the rate to r tokens per second, with a maximum burst size of b events. As a special case, if r == Inf (the infinite rate), b is ignored. See https://en.wikipedia.org/wiki/Token_bucket for more about token buckets.
The zero value is a valid BurstLimiter, but it will reject all events. Use NewBurstLimiter to create non-zero Limiters.
BurstLimiter has three main methods, Allow, Reserve, and Wait. Most callers should use Wait.
Each of the three methods consumes a single token. They differ in their behavior when no token is available. If no token is available, Allow returns false. If no token is available, Reserve returns a reservation for a future token and the amount of time the caller must wait before using it. If no token is available, Wait blocks until one can be obtained or its associated context.Context is canceled.
The methods AllowN, ReserveN, and WaitN consume n tokens.
func NewBurstLimiter ¶
func NewBurstLimiter(b int) *BurstLimiter
NewBurstLimiter returns a new BurstLimiter that allows events up to rate r and permits bursts of at most b tokens.
func (*BurstLimiter) Allow ¶
func (lim *BurstLimiter) Allow() bool
Allow is shorthand for AllowN(time.Now(), 1).
func (*BurstLimiter) AllowN ¶
func (lim *BurstLimiter) AllowN(n int) bool
AllowN reports whether n events may happen at time now. Use this method if you intend to drop / skip events that exceed the rate limit. Otherwise use Reserve or Wait.
func (*BurstLimiter) Burst ¶
func (lim *BurstLimiter) Burst() int
Burst returns the maximum burst size. Burst is the maximum number of tokens that can be consumed in a single call to Allow, Reserve, or Wait, so higher Burst values allow more events to happen at once. A zero Burst allows no events, unless limit == Inf.
func (*BurstLimiter) GetToken ¶
func (lim *BurstLimiter) GetToken()
GetToken is shorthand for GetTokenN(ctx, 1).
func (*BurstLimiter) GetTokenN ¶
func (lim *BurstLimiter) GetTokenN(n int)
func (*BurstLimiter) PutToken ¶
func (lim *BurstLimiter) PutToken()
PutToken is shorthand for PutTokenN(ctx, 1).
func (*BurstLimiter) PutTokenN ¶
func (lim *BurstLimiter) PutTokenN(n int)
func (*BurstLimiter) Reserve ¶
func (lim *BurstLimiter) Reserve(ctx context.Context) *Reservation
Reserve is shorthand for ReserveN(1).
func (*BurstLimiter) ReserveN ¶
func (lim *BurstLimiter) ReserveN(ctx context.Context, n int) *Reservation
ReserveN returns a Reservation that indicates how long the caller must wait before n events happen. The BurstLimiter takes this Reservation into account when allowing future events. ReserveN returns false if n exceeds the BurstLimiter's burst size. Usage example:
r := lim.ReserveN(context.Background(), 1)
if !r.OK() {
// Not allowed to act! Did you remember to set lim.burst to be > 0 ?
return
}
time.Sleep(r.Delay())
Act()
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 (*BurstLimiter) Wait ¶
func (lim *BurstLimiter) Wait(ctx context.Context) (err error)
Wait is shorthand for WaitN(ctx, 1).
func (*BurstLimiter) WaitN ¶
func (lim *BurstLimiter) WaitN(ctx context.Context, n int) (err error)
WaitN blocks until lim permits n events to happen. It returns an error if n exceeds the BurstLimiter's burst size, the Context is canceled, or the expected wait time exceeds the Context's Deadline. The burst limit is ignored if the rate limit is Inf.
type Reservation ¶
type Reservation struct {
// contains filtered or unexported fields
}
A Reservation holds information about events that are permitted by a BurstLimiter to happen after a delay. A Reservation may be canceled, which may enable the BurstLimiter to permit additional events.
func (*Reservation) Cancel ¶
func (r *Reservation) Cancel()
Cancel 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 (*Reservation) OK ¶
func (r *Reservation) OK() bool
OK returns whether the limiter can provide the requested number of tokens within the maximum wait time. If OK is false, Delay returns InfDuration, and Cancel does nothing.
Source Files