--amend

Author: bobhansen

consistenthash/consistenthash.go

@@ -26,20 +26,69 @@ import (
 
 type Hash func(data []byte) uint32
 
+const defaultHashExpansion = 6
+
 type Map struct {
+	// Inputs
+
+	// hash is the hash function that will be applied to both added
+	// keys and fetched keys
 	hash                 Hash
+
+	// replicas is the number of virtual nodes that will be inserted
+	// into the consistent hash ring for each key added
 	replicas             int
+
+	// prefixTableExpansion is the multiple of virtual nodes that
+	// will be inserted into the internal hash table for O(1) lookups.
 	prefixTableExpansion int
 
+
+
+	// Internal data
+
+	// keys is the hash of the virtual nodes, sorted by hash value
 	keys    []int // Sorted
+
+	// hashMap maps the hashed keys back to the input strings.
+	// Note that all virtual nodes will map back to the same input
+	// string
 	hashMap map[int]string
 
-	prefixBits  uint32
+	// prefixShift is the number of bits an input hash should
+	// be right-shifted to act as a lookup in the prefixTable
 	prefixShift uint32
+
+	// prefixTable is a map of the most significant bits of
+	// a hash value to output all hashes with that prefix
+	// map to.  If the result is ambiguous (i.e. there is a
+	// hash range split within this prefix) the value will
+	// be blank and we should fall back to a binary search
+	// through keys to find the exact output
 	prefixTable []string
 }
 
-func New(replicas int, tableExpansion int, fn Hash) *Map {
+// New returns a blank consistent hash ring that will return
+// the key whos hash comes next after the hash of the input to
+// Get().
+// Increasing the number of replicas will improve the smoothness
+// of the hash ring and reduce the data moved when adding/removing
+// nodes, at the cost of more memory.
+func New(replicas int, fn Hash) *Map {
+	return NewConsistentHash(replicas, defaultHashExpansion, fn)
+}
+
+
+// NewConsistentHash returns a blank consistent hash ring that will return
+// the key whos hash comes next after the hash of the input to
+// Get().
+// Increasing the number of replicas will improve the smoothness
+// of the hash ring and reduce the data moved when adding/removing
+// nodes.
+// Increasing the tableExpansion will allocate more entries in the
+// internal hash table, reducing the frequency of lg(n) binary
+// searches during Get() calls.
+func NewConsistentHash(replicas int, tableExpansion int, fn Hash) *Map {
 	m := &Map{
 		replicas:             replicas,
 		hash:                 fn,
@@ -69,10 +118,10 @@ func (m *Map) Add(keys ...string) {
 	sort.Ints(m.keys)
 
 	// Find minimum number of bits to hold |keys| * prefixTableExpansion
-	m.prefixBits = uint32(bits.Len32(uint32(len(m.keys) * m.prefixTableExpansion)))
-	m.prefixShift = 32 - m.prefixBits
+	prefixBits := uint32(bits.Len32(uint32(len(m.keys) * m.prefixTableExpansion)))
+	m.prefixShift = 32 - prefixBits
 
-	prefixTableSize := 1 << m.prefixBits
+	prefixTableSize := 1 << prefixBits
 	m.prefixTable = make([]string, prefixTableSize)
 
 	previousKeyPrefix := -1 // Effectively -Inf

http.go

@@ -34,8 +34,6 @@ const defaultBasePath = "/_groupcache/"
 
 const defaultReplicas = 50
 
-const defaultHashExpansion = 6
-
 // HTTPPool implements PeerPicker for a pool of HTTP peers.
 type HTTPPool struct {
 	// Context optionally specifies a context for the server to use when it
@@ -108,7 +106,7 @@ func NewHTTPPoolOpts(self string, o *HTTPPoolOptions) *HTTPPool {
 	if p.opts.Replicas == 0 {
 		p.opts.Replicas = defaultReplicas
 	}
-	p.peers = consistenthash.New(p.opts.Replicas, defaultHashExpansion, p.opts.HashFn)
+	p.peers = consistenthash.New(p.opts.Replicas, p.opts.HashFn)
 
 	RegisterPeerPicker(func() PeerPicker { return p })
 	return p
@@ -120,7 +118,7 @@ func NewHTTPPoolOpts(self string, o *HTTPPoolOptions) *HTTPPool {
 func (p *HTTPPool) Set(peers ...string) {
 	p.mu.Lock()
 	defer p.mu.Unlock()
-	p.peers = consistenthash.New(p.opts.Replicas, defaultHashExpansion, p.opts.HashFn)
+	p.peers = consistenthash.New(p.opts.Replicas, p.opts.HashFn)
 	p.peers.Add(peers...)
 	p.httpGetters = make(map[string]*httpGetter, len(peers))
 	for _, peer := range peers {