dooooooocs

README.md

@@ -1,4 +1,15 @@
 go-hostpool
 ===========
 
-Intelligently and flexibly pool among multiple hosts from your Go application
+Intelligently and flexibly pool among multiple hosts from your Go application.
+Usage example:
+
+```go
+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

epsilon_greedy.go

@@ -28,23 +28,20 @@ type epsilonGreedyHostPool struct {
 	timer
 }
 
-// Epsilon Greedy is an algorithim that allows HostPool not only to track failure state, 
+// 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 a percentage of 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)
-// 
-// After enabling Epsilon Greedy, hosts must be marked for sucess along with a time value representing 
-// how fast (or slow) that host was. 
-// 
-// host := pool.Get()
-// start := time.Now()
-// ..... do work with host
-// duration = time.Now().Sub(start)
-// pool.MarkSuccessWithTime(host, duration)
+// 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
+// A good overview of Epsilon Greedy is here http://stevehanov.ca/blog/index.php?id=132
 //
-// decayDuration may be set to 0 to use the default value of 5 minutes
+// 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.
 func NewEpsilonGreedy(hosts []string, decayDuration time.Duration, calc EpsilonValueCalculator) HostPool {
 
 	if decayDuration <= 0 {

hostpool.go

@@ -8,6 +8,10 @@ import (
 
 // --- Response interfaces and structs ----
 
+// 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)
@@ -22,6 +26,9 @@ type standardHostPoolResponse struct {
 
 // --- HostPool structs and interfaces ----
 
+// 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
 	// keep the marks separate so we can override independently
@@ -49,6 +56,7 @@ const minEpsilon = 0.01   // explore one percent of the time
 const initialEpsilon = 0.3
 const defaultDecayDuration = time.Duration(5) * time.Minute
 
+// Construct a basic HostPool using the hostnames provided
 func New(hosts []string) HostPool {
 	p := &standardHostPool{
 		hosts:             make(map[string]*hostEntry, len(hosts)),
@@ -91,7 +99,7 @@ func doMark(err error, r HostPoolResponse) {
 	}
 }
 
-// return an upstream entry from the HostPool
+// return an entry from the HostPool
 func (p *standardHostPool) Get() HostPoolResponse {
 	p.Lock()
 	defer p.Unlock()