README
¶
go-limiter
A Go library for limiting execution. It provides interfaces for various limiter styles, along with implementations of those interfaces.
Limiter styles include:
- Limit concurrency via token pool
- Limit concurrency via wrapped invocation
- Enforce maximum action rate
- Throttle rate on error count
Roadmap
January 2019:
- Add backoff limiter which has a maximum delay and always reduces delay upon success
- Add capacity limiter which reduces capacity on error and restores capacity on success
Online GoDoc
Documentation
¶
Overview ¶
Package limiter provides interfaces for various execution-limiting needs, along with implementations of those interfaces.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AdjustableTokenChanLimiter ¶
type AdjustableTokenChanLimiter struct {
TokenChanLimiter
// contains filtered or unexported fields
}
AdjustableTokenChanLimiter extends TokenChanLimiter with methods enabling the addition and removal of tokens, and satisfies the TokenLimiter and InvocationLimiter interfaces.
func NewAdjustableCpuTokenChanLimiter ¶
func NewAdjustableCpuTokenChanLimiter(initialTokens uint) (tl *AdjustableTokenChanLimiter)
func NewAdjustableTokenChanLimiter ¶
func NewAdjustableTokenChanLimiter(initialTokens uint, maxTokens uint) (tl *AdjustableTokenChanLimiter)
func (*AdjustableTokenChanLimiter) AddTokens ¶
func (l *AdjustableTokenChanLimiter) AddTokens(count uint) (err error)
AddTokens creates the specified number of new tokens and adds them to the limiter's supply channel.
If the maximum number of tokens are reached, an error will be returned.
func (*AdjustableTokenChanLimiter) GetTokenCount ¶
func (l *AdjustableTokenChanLimiter) GetTokenCount() uint
GetTokenCount returns the current token count.
func (*AdjustableTokenChanLimiter) RemoveTokens ¶
func (l *AdjustableTokenChanLimiter) RemoveTokens(count uint) (err error)
RemoveTokens removes up to the specified number of tokens from the limiter's supply channel.
If the number of tokens reaches 0, no action will be taken and no error will be returned. Passing math.MaxUint64 instead of a known token count will safely remove all tokens.
type BurstRateLimiter ¶
type BurstRateLimiter struct {
// contains filtered or unexported fields
}
BurstRateLimiter enforces a rate limit within an interval and satisfies the RateLimiter and InvocationLimiter interfaces.
func NewBurstRateLimiter ¶
func NewBurstRateLimiter(maxRate Rate) (l *BurstRateLimiter)
NewBurstRateLimiter instantiates a BurstRateLimiter with the provided rate threshold and a wait-backoff function with full jitter appropriate for high-frequency use (more than 200 actions per second).
func (*BurstRateLimiter) CheckWait ¶
func (l *BurstRateLimiter) CheckWait()
CheckWait should be called at the beginning of the caller's action. It blocks if the limiter needs to restrict execution, otherwise it returns immediately. Restriction is typically based on consumption of a fixed rate budget, but may also be controlled by other factors.
If calls to this method are uniform, the allowed rate will roughly match the rate threshold. Non-uniform use may result in a rate during the end of an interval and the beginning of the subsequent interval which together exceed the specified threshold.
func (*BurstRateLimiter) Invoke ¶
func (l *BurstRateLimiter) Invoke(f func() error) (err error)
Invoke enforces the limiter's limits around the invocation of the passed function. The error returned by the function invocation is returned to the caller without modification, and its existence may be used by the limiter to delay the current return or subsequent invocations.
func (*BurstRateLimiter) SetMaxRate ¶
func (l *BurstRateLimiter) SetMaxRate(rate Rate)
SetRateLimit sets a new rate threshold for this limiter.
It does not make any adjustment based on the previous threshold, so the rate allowed immediately before and after this change may together exceed the specified threshold.
type FailBackOffLimiter ¶
type FailBackOffLimiter struct {
// contains filtered or unexported fields
}
FailBackOffLimiter delays execution of subsequent invocations when the caller reports failure conditions, and satisfies the FailLimiter and InvocationLimiter interfaces.
func NewFailBackOffLimiter ¶
func NewFailBackOffLimiter(backOffFunc func(uint) uint) (l *FailBackOffLimiter)
NewFailBackOffLimiter instantiates a new FailBackOffLimiter with the provided backoff function.
This package provides backoff function builders in go-limiter/backoff.
func (*FailBackOffLimiter) CheckWait ¶
func (l *FailBackOffLimiter) CheckWait()
CheckWait should be called at the beginning of the caller's action.
It blocks if the limiter needs to restrict execution, otherwise it returns immediately. Restriction is typically based on the last received status, but may also be controlled by other factors.
func (*FailBackOffLimiter) Invoke ¶
func (l *FailBackOffLimiter) Invoke(f func() error) (err error)
Invoke enforces the limiter's limits around the invocation of the passed function.
The error returned by the function invocation is returned to the caller without modification, and its existence may be used by the limiter to delay the current return or subsequent invocations.
func (*FailBackOffLimiter) Report ¶
func (l *FailBackOffLimiter) Report(success bool)
Report should be called at the end of the caller's action, providing the limiter with the success/fail status of the action.
Failure statuses should be expected to incur rate throttling on subsequent calls to CheckWait.
type FailLimiter ¶
type FailLimiter interface {
CheckWait()
Report(success bool)
}
FailLimiter is the interface that wraps the CheckWait and Report methods, representing the use of a delay mechanism to enforce a rate limit and a feedback method to control it.
CheckWait should be called at the beginning of the caller's action. It blocks if the limiter needs to restrict execution, otherwise it returns immediately. Restriction is typically based on the last received status, but may also be controlled by other factors.
Report should be called at the end of the caller's action, providing the limiter with the success/fail status of the action. Failure statuses should be expected to incur rate throttling on subsequent calls to CheckWait.
type FailRateLimiter ¶
type FailRateLimiter struct {
// contains filtered or unexported fields
}
FailRateLimiter combines a FailLimiter and a RateLimiter to act as a single FailLimiter.
func NewFailRateLimiter ¶
func NewFailRateLimiter(maxRate Rate, backOff func(uint) uint) (l *FailRateLimiter)
NewFailRateLimiter instantiates a new FailRateLimiter with the provided maximum rate and backoff function.
func NewHalfJitterFailRateLimiter ¶
func NewHalfJitterFailRateLimiter(maxRate Rate, maxBackOff uint) (l *FailRateLimiter)
NewHalfJitterFailRateLimiter instantiates a new FailRateLimiter with the provided maximum rate, and provdes a half-jitter backoff function with the provided maximum delay.
func (*FailRateLimiter) CheckWait ¶
func (l *FailRateLimiter) CheckWait()
func (*FailRateLimiter) Invoke ¶
func (l *FailRateLimiter) Invoke(f func() error) (err error)
Invoke enforces this limiter's limits before the invocation of the provided function and uses the function's return value to adjust the backoff rate for subsequent invocations.
func (*FailRateLimiter) Report ¶
func (l *FailRateLimiter) Report(success bool)
Report should be called at the end of the caller's action, providing the limiter with the success/fail status of the action.
Failure statuses should be expected to incur rate throttling on subsequent calls to CheckWait.
func (*FailRateLimiter) SetBackOffFunc ¶
func (l *FailRateLimiter) SetBackOffFunc(f func(uint) uint)
SetBackOffFunc sets a new backoff function for this limiter.
func (*FailRateLimiter) SetMaxRate ¶
func (l *FailRateLimiter) SetMaxRate(rate Rate)
SetRateLimit sets the maximum rate for this limiter.
type FixedIntervalLimiter ¶
type FixedIntervalLimiter struct {
// contains filtered or unexported fields
}
func NewFixedIntervalLimiter ¶
func NewFixedIntervalLimiter(interval time.Duration) *FixedIntervalLimiter
func (*FixedIntervalLimiter) CheckWait ¶
func (l *FixedIntervalLimiter) CheckWait()
type IntervalLimiter ¶
type IntervalLimiter struct {
// contains filtered or unexported fields
}
func NewIntervalLimiter ¶
func NewIntervalLimiter(interval time.Duration) *IntervalLimiter
func (*IntervalLimiter) CheckWait ¶
func (l *IntervalLimiter) CheckWait()
func (*IntervalLimiter) SetInterval ¶
func (l *IntervalLimiter) SetInterval(d time.Duration)
func (*IntervalLimiter) SetRecheck ¶
func (l *IntervalLimiter) SetRecheck(d time.Duration)
type InvocationLimiter ¶
InvocationLimiter is the interface that wraps the Invoke method.
Invoke enforces the limiter's limits around the invocation of the passed function. The error returned by the function invocation is returned to the caller without modification, and its existence may be used by the limiter to delay the current return or subsequent invocations.
type RateLimiter ¶
type RateLimiter interface {
CheckWait()
}
RateLimiter is the interface that wraps the CheckWait method, representing the use of a delay mechanism to enforce a rate limit.
CheckWait should be called at the beginning of the caller's action. It blocks if the limiter needs to restrict execution, otherwise it returns immediately. Restriction is typically based on consumption of a fixed rate budget, but may also be controlled by other factors.
type TokenAndFailLimiter ¶
type TokenAndFailLimiter interface {
AcquireToken() (token *[16]byte)
ReleaseTokenAndReport(token *[16]byte, success bool)
Report(success bool)
}
TokenAndFailLimiter is the interface that simplifies the combination of a TokenLimiter and a FailLimiter, wrapping a ReleaseTokenAndReport method instead of ReleaseToken.
AcquireToken blocks until a token can be acquired from the limiter's supply, and also blocks if the limiter needs to restrict execution. The token must be held for the duration of the action which needs to be limited, and then it must be passed to the ReleaseTokenAndReport method without modification.
ReleaseTokenAndReport should be called at the end of the caller's action, notifying the limiter that the provided token (pointer and value) can be used by another goroutine and providing the limiter with the success/fail status of the action. The caller must not modify the value of the token at any time, but if the token implementation is known by the caller then unmarshaling of its value is not discouraged.
Report can be called outside the context of a rate-limited action to notify the limiter that an error has occurred and that the allowed execution rate should be throttled.
type TokenChanLimiter ¶
type TokenChanLimiter struct {
// contains filtered or unexported fields
}
TokenChanLimiter enforces a concurrency limit using tokens and satisfies the TokenLimiter and InvocationLimiter interfaces.
func NewTokenChanLimiter ¶
func NewTokenChanLimiter(initialTokens uint) (l *TokenChanLimiter)
NewTokenChanLimiter instantiates a new TokenChanLimiter with the provided number of tokens.
func (*TokenChanLimiter) AcquireToken ¶
func (l *TokenChanLimiter) AcquireToken() (token *[16]byte)
AcquireToken blocks until a token can be acquired from the limiter's supply. The token must be held for the duration of the activity which needs to be limited, and then it must be passed to the ReleaseToken method without modification.
func (*TokenChanLimiter) Invoke ¶
func (l *TokenChanLimiter) Invoke(f func() error) (err error)
Invoke enforces the limiter's limits around the invocation of the passed function. The error returned by the function invocation is returned to the caller without modification, and its existence may be used by the limiter to delay the current return or subsequent invocations.
func (*TokenChanLimiter) ReleaseToken ¶
func (l *TokenChanLimiter) ReleaseToken(token *[16]byte)
ReleaseToken notifies the limiter that the provided token (pointer and value) can be used by another goroutine. The caller must not modify the value of the token at any time, but if the token implementation is known by the caller then unmarshaling of its value is not discouraged.
type TokenFailLimiter ¶
type TokenFailLimiter struct {
// contains filtered or unexported fields
}
TokenFailLimiter combines a TokenLimiter and a FailLimiter to satisfy the TokenAndFailLimiter interface.
func NewTokenFailLimiter ¶
func NewTokenFailLimiter(tl TokenLimiter, fl FailLimiter) (l *TokenFailLimiter)
NewTokenFailLimiter instantiates a new TokenFailLimiter with the provided TokenLimiter and FailLimiter.
func (*TokenFailLimiter) AcquireToken ¶
func (l *TokenFailLimiter) AcquireToken() (token *[16]byte)
AcquireToken blocks until a token can be acquired from the limiter's supply, and also blocks if the limiter needs to restrict execution. The token must be held for the duration of the action which needs to be limited, and then it must be passed to the ReleaseTokenAndReport method without modification.
func (*TokenFailLimiter) Invoke ¶
func (l *TokenFailLimiter) Invoke(f func() error) (err error)
Invoke enforces the limiter's limits before the invocation of the passed function. The error returned by the function invocation is returned to the caller without modification, and its existence may be used by the limiter to delay the current return or subsequent invocations.
func (*TokenFailLimiter) ReleaseTokenAndReport ¶
func (l *TokenFailLimiter) ReleaseTokenAndReport(token *[16]byte, success bool)
ReleaseTokenAndReport should be called at the end of the caller's action, notifying the limiter that the provided token (pointer and value) can be used by another goroutine and providing the limiter with the success/fail status of the action. The caller must not modify the value of the token at any time, but if the token implementation is known by the caller then unmarshaling of its value is not discouraged.
func (*TokenFailLimiter) Report ¶
func (l *TokenFailLimiter) Report(success bool)
Report can be called outside the context of a rate-limited action to notify the limiter that an error has occurred and that the allowed execution rate should be throttled.
type TokenLimiter ¶
TokenLimiter is the interface that wraps the AcquireToken and ReleaseToken methods, representing the use of a token mechanism to enforce concurrency limits.
AcquireToken blocks until a token can be acquired from the limiter's supply. The token must be held for the duration of the activity which needs to be limited, and then it must be passed to the ReleaseToken method without modification.
ReleaseToken notifies the limiter that the provided token (pointer and value) can be used by another goroutine. The caller must not modify the value of the token at any time, but if the token implementation is known by the caller then unmarshaling of its value is not discouraged.
The token type is a pointer to a 16-byte array (128 bits) to give limiter implementations many options with a fixed type, like 128-bit binary time.Time or UUID values.
- time.Time objects can be converted to/from []byte using the Time::MarshalBinary() and Time::UnmarshalBinary(data []byte) methods.
- Hexadecimal string UUIDs can be converted to/from []byte using the "encoding/hex" package.
- Numeric values can be converted to/from []byte using the "encoding/binary" package.
Source Files