healthpool

Documentation

Overview

Package healthpool provides a generic way to keep track of the health infos for a set of keys.

Usage

This package is used to implement health pools for specific purposes. They can be found in the subpackages. Client packages should use these implementations, unless they implement their own specific health pool.

Pool

The pool keeps a map of all registered keys to their health info. It is used to choose the best info based on the fail count and the initialized selection algorithm. The behavior of the pool can be modified at initialization with the provided PoolOptions.

The pool periodically reduces the fail count for every info that has not failed for a specified amount of time. The fail count is divided by two every expire interval starting from that point.

Info

The info keeps track of the failures for a given key. The client should call the Fail method to increase the fail count.

Index

• Constants
• type Algorithm
• type ExpireOptions
• type Info
  • func NewInfo() Info
• type InfoSet
  • func (s InfoSet) List() []Info
• type Pool
  • func NewPool(infos map[Info]struct{}, opts PoolOptions) (*Pool, error)
  • func (p *Pool) Choose() (Info, error)
  • func (p *Pool) Close()
  • func (p *Pool) Infos() []Info
  • func (p *Pool) Update(infos map[Info]struct{}) error
• type PoolOptions

Constants

const (
	// DefaultExpireStart is the the default for ExpireStart.
	DefaultExpireStart = 5 * time.Minute
	// DefaultExpireInterval is the default for ExpireInterval.
	DefaultExpireInterval = 10 * time.Second
)

const ErrPoolClosed common.ErrMsg = "Pool closed"

ErrPoolClosed is the error returned when operations on a closed pool are executed.

const MaxFailCount = math.MaxUint16

MaxFailCount is the maximum fail count for a health info.

Types

type Algorithm

type Algorithm string

Algorithm is the choosing algorithm of the pool.

const (
	// MinFailCount selects a pool entry with the minimum fail count.
	MinFailCount Algorithm = "MinFailCount"
)

type ExpireOptions

type ExpireOptions struct {
	// Start is the time without failures for an info after which
	// exponential fail expiration starts. In case of the zero value, the
	// DefaultExpireStart is used.
	Start time.Duration
	// Interval is the time between exponential fail expirations.
	// In case of the zero value, the DefaultExpireInterval is used.
	Interval time.Duration
}

ExpireOptions define the expiration behavior.

type Info

type Info interface {
	// Fail increases the fail count.
	Fail()
	// FailCount returns the fail count.
	FailCount() int
	// ResetCount resets the fail count to zero.
	ResetCount()
	// contains filtered or unexported methods
}

Info keeps track of the fails for a key. Implementations that want to use healthpool should embed this interface and initialize it with the constructor NewInfo. See healthpool/svcinstance for an example.

func NewInfo

func NewInfo() Info

NewInfo creates a new health info.

type InfoSet

type InfoSet map[Info]struct{}

InfoSet is a set of infos.

func (InfoSet) List

func (s InfoSet) List() []Info

List transforms the info set to a list.

type Pool

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

Pool holds entries and their health. It allows to choose entries based on their health.

func NewPool

func NewPool(infos map[Info]struct{}, opts PoolOptions) (*Pool, error)

NewPool creates a health pool that contains all entries provided in infos.

func (*Pool) Choose

func (p *Pool) Choose() (Info, error)

Choose chooses info based on the configured algorithm. If the pool is closed, an error is returned.

func (*Pool) Close

func (p *Pool) Close()

Close closes the pool and stops the periodic fail expiration. After closing the pool, Update and Choose will return errors. The pool is safe to being closed multiple times.

func (*Pool) Infos

func (p *Pool) Infos() []Info

Infos returns a list of all infos in the pool.

func (*Pool) Update

func (p *Pool) Update(infos map[Info]struct{}) error

Update updates the info entries in the pool. Entries in the pool that are not in infos are removed. Entries in infos that are not in the pool are added. However, if Options.AllowEmpty is not set, and the Update causes an empty pool, the entries are not replaced and an error is returned. If the pool is closed, an error is returned.

type PoolOptions

type PoolOptions struct {
	// Algorithm is the choosing algorithm. In case of the empty string,
	// MinFailCount is used.
	Algorithm Algorithm
	// AllowEmpty indicates that the pool is allowed to be empty.
	AllowEmpty bool
	// Expire contains the expiration options.
	Expire ExpireOptions
}

PoolOptions define the behavior of the pool.