hostpool

README

go-hostpool

A Go package to intelligently and flexibly pool among multiple hosts from your Go application. Host selection can operate in round robin or epsilon greedy mode, and unresponsive hosts are avoided. Usage example:

hp := hostpool.NewEpsilonGreedy([]string{"a", "b"}, 0, &hostpool.LinearEpsilonValueCalculator{})
hostResponse := hp.Get()
hostname := hostResponse.Host()
err := _ // (make a request with hostname)
hostResponse.Mark(err)

View more detailed documentation on godoc.org

Documentation

Overview

A Go package to intelligently and flexibly pool among multiple hosts from your Go application. Host selection can operate in round robin or epsilon greedy mode, and unresponsive hosts are avoided. A good overview of Epsilon Greedy is here http://stevehanov.ca/blog/index.php?id=132

Index

• func Version() string
• type EpsilonValueCalculator
• type HostPool
  • func New(hosts []string) HostPool
  • func NewEpsilonGreedy(hosts []string, decayDuration time.Duration, calc EpsilonValueCalculator) HostPool
• type HostPoolResponse
• type LinearEpsilonValueCalculator
  • func (c *LinearEpsilonValueCalculator) CalcValueFromAvgResponseTime(v float64) float64
• type LogEpsilonValueCalculator
  • func (c *LogEpsilonValueCalculator) CalcValueFromAvgResponseTime(v float64) float64
• type PolynomialEpsilonValueCalculator
  • func (c *PolynomialEpsilonValueCalculator) CalcValueFromAvgResponseTime(v float64) float64

Functions

func Version

func Version() string

Returns current version

Types

type EpsilonValueCalculator

type EpsilonValueCalculator interface {
	CalcValueFromAvgResponseTime(float64) float64
}

Structs implementing this interface are used to convert the average response time for a host into a score that can be used to weight hosts in the epsilon greedy hostpool. Lower response times should yield higher scores (we want to select the faster hosts more often) The default LinearEpsilonValueCalculator just uses the reciprocal of the response time. In practice, any decreasing function from the positive reals to the positive reals should work.

type HostPool

type HostPool interface {
	Get() HostPoolResponse

	ResetAll()
	// ReturnUnhealthy when called with true will prevent an unhealthy node from
	// being returned and will instead return a nil HostPoolResponse. If using
	// this feature then you should check the result of Get for nil
	ReturnUnhealthy(v bool)
	Hosts() []string
	SetHosts([]string)

	// Close the hostpool and release all resources.
	Close()
	// contains filtered or unexported methods
}

This is the main HostPool interface. Structs implementing this interface allow you to Get a HostPoolResponse (which includes a hostname to use), get the list of all Hosts, and use ResetAll to reset state.

func New

func New(hosts []string) HostPool

Construct a basic HostPool using the hostnames provided

func NewEpsilonGreedy

func NewEpsilonGreedy(hosts []string, decayDuration time.Duration, calc EpsilonValueCalculator) HostPool

Construct an Epsilon Greedy HostPool

Epsilon Greedy is an algorithm that allows HostPool not only to track failure state, but also to learn about "better" options in terms of speed, and to pick from available hosts based on how well they perform. This gives a weighted request rate to better performing hosts, while still distributing requests to all hosts (proportionate to their performance). The interface is the same as the standard HostPool, but be sure to mark the HostResponse immediately after executing the request to the host, as that will stop the implicitly running request timer.

A good overview of Epsilon Greedy is here http://stevehanov.ca/blog/index.php?id=132

To compute the weighting scores, we perform a weighted average of recent response times, over the course of `decayDuration`. decayDuration may be set to 0 to use the default value of 5 minutes We then use the supplied EpsilonValueCalculator to calculate a score from that weighted average response time.

type HostPoolResponse

type HostPoolResponse interface {
	Host() string
	Mark(error)
	// contains filtered or unexported methods
}

This interface represents the response from HostPool. You can retrieve the hostname by calling Host(), and after making a request to the host you should call Mark with any error encountered, which will inform the HostPool issuing the HostPoolResponse of what happened to the request and allow it to update.

type LinearEpsilonValueCalculator

type LinearEpsilonValueCalculator struct{}

func (*LinearEpsilonValueCalculator) CalcValueFromAvgResponseTime

func (c *LinearEpsilonValueCalculator) CalcValueFromAvgResponseTime(v float64) float64

type LogEpsilonValueCalculator

type LogEpsilonValueCalculator struct{ LinearEpsilonValueCalculator }

func (*LogEpsilonValueCalculator) CalcValueFromAvgResponseTime

func (c *LogEpsilonValueCalculator) CalcValueFromAvgResponseTime(v float64) float64

type PolynomialEpsilonValueCalculator

type PolynomialEpsilonValueCalculator struct {
	LinearEpsilonValueCalculator
	Exp float64 // the exponent to which we will raise the value to reweight
}

func (*PolynomialEpsilonValueCalculator) CalcValueFromAvgResponseTime

func (c *PolynomialEpsilonValueCalculator) CalcValueFromAvgResponseTime(v float64) float64