hostpool - ActiveState ActiveGo 1.8
...

Package hostpool

import "github.com/hailocab/go-hostpool"
Overview
Index
Examples

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

func Version

func Version() string

Returns current version

type EpsilonValueCalculator

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 EpsilonValueCalculator interface {
    CalcValueFromAvgResponseTime(float64) float64
}

type HostPool

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.

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
}

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.

Example

Code:

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

type HostPoolResponse

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 HostPoolResponse interface {
    Host() string
    Mark(error)
    // contains filtered or unexported methods
}

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