base: github.com/grailbio/base/admit Index | Files

package admit

import "github.com/grailbio/base/admit"

Package admit contains utilities for admission control.

Index

Package Files

admit.go

func Do Uses

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 Uses

func EnableVarExport(policy Policy, name string)

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

func Retry Uses

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.

type CapacityStatus Uses

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 Uses

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 Uses

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 Uses

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 Uses

type RetryPolicy interface {
    Policy
    retry.Policy
}

RetryPolicy combines an admission controller with a retry policy.

func AIMDWithRetry Uses

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 Uses

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.

Package admit imports 6 packages (graph) and is imported by 2 packages. Updated 2019-12-24. Refresh now. Tools for package owners.