Documentation

Overview

    Package admit contains utilities for admission control.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    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.

                        Source Files