admit

Documentation

Overview

Package admit contains utilities for admission control.

Index

• func Do(ctx context.Context, policy Policy, tokens int, f func() (bool, error)) error
• func EnableVarExport(policy Policy, name string)
• func Retry(ctx context.Context, policy RetryPolicy, tokens int, ...) error
• type CapacityStatus
• type Policy
  • func AIMD(min int, decfactor float32) Policy
  • func Controller(start, limit int) Policy
• type RetryPolicy
  • func AIMDWithRetry(min int, decfactor float32, retryPolicy retry.Policy) RetryPolicy
  • func ControllerWithRetry(start, limit int, retryPolicy retry.Policy) RetryPolicy

Functions

func Do

func Do(ctx context.Context, policy Policy, tokens int, f func() (bool, error)) error

Do calls f after being admitted by the controller. f's bool return value is passed on to the underlying policy upon Release, and the error is simply returned back to the caller as a convenience. If policy is nil, then this will simply call f.

func EnableVarExport

func EnableVarExport(policy Policy, name string)

EnableVarExport enables the export of relevant vars useful for debugging/monitoring.

func Retry

func Retry(ctx context.Context, policy RetryPolicy, tokens int, f func() (CapacityStatus, error)) error

Retry calls f after being admitted by the Policy (implied by the given RetryPolicy). If f returns Within, true is passed to the underlying policy upon Release and false otherwise. If f returns OverNeedRetry, f will be retried as per the RetryPolicy (and the error returned by f is ignored), and if f can no longer be retried, the error returned by retry.Policy will be returned.

Types

type CapacityStatus

type CapacityStatus int

CapacityStatus is the feedback provided by the user to Retry about the underlying resource being managed by Policy.

const (
	// Within means that the underlying resource is within capacity.
	Within CapacityStatus = iota
	// OverNoRetry means that the underlying resource is over capacity but no retry is needed.
	// This is useful in situations where a request using the resource succeeded, but there are
	// signs of congestion (for example, in the form of high latency).
	OverNoRetry
	// OverNeedRetry means that the underlying resource is over capacity and a retry is needed.
	// This is useful in situations where requests failed due to the underlying resource hitting capacity limits.
	OverNeedRetry
)

type Policy

type Policy interface {
	// Acquire acquires a number of tokens from the admission controller.
	// Returns on success, or if the context was canceled.
	// Acquire can also return with an error if the number of requested tokens
	// exceeds the upper limit of available tokens.
	Acquire(ctx context.Context, need int) error

	// Release a number of tokens to the admission controller,
	// reporting whether the request was within the capacity limits.
	Release(tokens int, ok bool)
}

Policy implements the low level details of an admission control policy. Users typically use a utility function such as admit.Do or admit.Retry.

func AIMD

func AIMD(min int, decfactor float32) Policy

AIMD returns a Policy which uses the Additive increase/multiplicative decrease algorithm for computing the amount of the concurrency to allow. AIMD is not fair: tokens are not granted in FIFO order; rather, waiters are picked randomly to be granted new tokens.

func Controller

func Controller(start, limit int) Policy

Controller returns a Policy which starts with a concurrency limit of 'start' and can grow upto a maximum of 'limit' as long as errors aren't observed. A controller is not fair: tokens are not granted in FIFO order; rather, waiters are picked randomly to be granted new tokens.

type RetryPolicy

type RetryPolicy interface {
	Policy
	retry.Policy
}

RetryPolicy combines an admission controller with a retry policy.

func AIMDWithRetry

func AIMDWithRetry(min int, decfactor float32, retryPolicy retry.Policy) RetryPolicy

AIMDWithRetry returns a RetryPolicy which uses the Additive increase/multiplicative decrease algorithm for computing the amount of the concurrency to allow. AIMDWithRetry is not fair: tokens are not granted in FIFO order; rather, waiters are picked randomly to be granted new tokens.

func ControllerWithRetry

func ControllerWithRetry(start, limit int, retryPolicy retry.Policy) RetryPolicy

ControllerWithRetry returns a RetryPolicy which starts with a concurrency limit of 'start' and can grow upto a maximum of 'limit' if no errors are seen. A controller is not fair: tokens are not granted in FIFO order; rather, waiters are picked randomly to be granted new tokens.