admit

Documentation

Overview

Package admit contains utilities for admission control.

Index

• Variables
• func Do(ctx context.Context, policy Policy, tokens int, do func() error) error
• func EnableVarExport(policy Policy, name string)
• func Retry(ctx context.Context, policy RetryPolicy, tokens int, do func() error) error
• type Policy
  • func Controller(start, limit int) Policy
• type RetryPolicy
  • func ControllerWithRetry(start, limit int, retryPolicy retry.Policy) RetryPolicy

Variables

var ErrOverCapacity = errors.New("over capacity")

ErrOverCapacity should be thrown by the "do" func passed to admit.Do or admit.Retry for it to be considered an over capacity error.

Functions

func Do

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

Do calls the provided function after being admitted by the admission controller. If the function returns ErrOverCapacity, it is then reported as a capacity request to the underlying policy. If policy is nil, then this will simply call the do() func.

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, do func() error) error

Retry calls the provided function with the combined retry and admission policies. If policy is nil, then this will simply call the do() func.

Types

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 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 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.