limiter

Documentation

Overview

Package limiter implements a concurrency limiter with support for contexts.

Index

• Variables
• type BatchApi
• type BatchLimiter
  • func NewBatchLimiter(api BatchApi, limiter *rate.Limiter) *BatchLimiter
  • func (l *BatchLimiter) Do(ctx context.Context, id ID) (interface{}, error)
• type ID
• type Limiter
  • func New() *Limiter
  • func (l *Limiter) Acquire(ctx context.Context, need int) error
  • func (l *Limiter) Release(n int)
• type LimiterIfc
• type Result
  • func (r *Result) Set(v interface{}, err error)

Variables

var ErrNoResult = fmt.Errorf("no result")

Types

type BatchApi

type BatchApi interface {
	// MaxPerBatch is the max number of ids to call per `Do` (zero implies no limit).
	MaxPerBatch() int

	// Do the batch call with the given map of IDs to Results.
	// The implementation must call Result.Set to provide the Value or Err (as applicable) for the every ID.
	// At the end of this call, if Result.Set was not called on the result of a particular ID,
	// the corresponding ID's `Do` call will get ErrNoResult.
	Do(map[ID]*Result)
}

BatchApi needs to be implemented in order to use BatchLimiter.

type BatchLimiter

type BatchLimiter struct {
	// contains filtered or unexported fields
}

BatchLimiter provides the ability to batch calls and apply a rate limit (on the batches). Users have to provide an implementation of BatchApi and a rate.Limiter. Thereafter callers can concurrently Do calls for each individual ID and the BatchLimiter will batch calls (whenever appropriate) while respecting the rate limit. Individual requests are serviced in the order of submission.

func NewBatchLimiter

func NewBatchLimiter(api BatchApi, limiter *rate.Limiter) *BatchLimiter

NewBatchLimiter returns a new BatchLimiter which will call the given batch API as per the limits set by the given rate limiter.

func (*BatchLimiter) Do

func (l *BatchLimiter) Do(ctx context.Context, id ID) (interface{}, error)

Do submits the given ID to the batch limiter and returns the result or an error. If the returned error is ErrNoResult, it indicates that the batch call did not produce any result for the given ID. Callers may then apply their own retry strategy if necessary. Do merges duplicate calls if the IDs are of a comparable type (and if the result is still pending) However, de-duplication is not guaranteed. Callers can avoid de-duplication by using a pointer type instead.

type ID

type ID interface{}

ID is the identifier of each call.

type Limiter

type Limiter struct {
	// contains filtered or unexported fields
}

A Limiter enforces concurrency limits among a set of goroutines. It maintains a bucket of tokens; a number of tokens (e.g., representing the cost of an operation) must be acquired by a goroutine before proceeding. A limiter is not fair: tokens are not granted in FIFO order; rather, waiters are picked randomly to be granted new tokens.

A nil limiter issues an infinite number of tokens.

func New

func New() *Limiter

New creates a new limiter with 0 tokens.

func (*Limiter) Acquire

func (l *Limiter) Acquire(ctx context.Context, need int) error

Acquire blocks until the goroutine is granted the desired number of tokens, or until the context is done.

func (*Limiter) Release

func (l *Limiter) Release(n int)

Release adds a number of tokens back into the limiter.

type LimiterIfc

type LimiterIfc interface {
	Release(n int)
	Acquire(ctx context.Context, need int) error
}

type Result

type Result struct {
	// contains filtered or unexported fields
}

Result is the result of an API call for a given id.

func (*Result) Set

func (r *Result) Set(v interface{}, err error)

Set sets the result of a given id with the given value v and error err.