From fd4b1c847163d801231d1d52e28d723ff23a0458 Mon Sep 17 00:00:00 2001
From: ale <ale@incal.net>
Date: Wed, 29 Jul 2015 07:31:58 +0100
Subject: [PATCH] more documentation
---
coordination/masterelection/masterelection.go | 8 +++++++-
coordination/presence/presence.go | 10 +++++++++-
coordination/watcher/cache.go | 8 ++++++++
coordination/watcher/watcher.go | 10 ++++++++++
vagrant-test/run-tests | 16 ++++++++++++++++
5 files changed, 50 insertions(+), 2 deletions(-)
create mode 100755 vagrant-test/run-tests
diff --git a/coordination/masterelection/masterelection.go b/coordination/masterelection/masterelection.go
index 56784397..3b2786e2 100644
--- a/coordination/masterelection/masterelection.go
+++ b/coordination/masterelection/masterelection.go
@@ -1,3 +1,5 @@
+// Package masterelection lets you run a simple master-election
+// protocol on top of etcd.
package masterelection
import (
@@ -16,6 +18,9 @@ const (
RoleMaster
)
+// How long to sleep on etcd Create() errors.
+var errorDelay = 200 * time.Millisecond
+
// Role of a participant in the master election protocol.
type Role int
@@ -213,6 +218,7 @@ func (m *MasterElection) runSlave(index uint64, stop chan bool) {
// Run the master election protocol, until the stop channel is closed.
func (m *MasterElection) Run(stop chan bool) {
+ // If an update channel is set, close it on exit.
if m.stateCh != nil {
defer close(m.stateCh)
}
@@ -242,7 +248,7 @@ func (m *MasterElection) Run(stop chan bool) {
} else {
// An error of some other sort! Retry.
m.Log.Printf("unexpected error: %v", err)
+ time.Sleep(errorDelay)
}
-
}
}
diff --git a/coordination/presence/presence.go b/coordination/presence/presence.go
index 41c95864..5f619291 100644
--- a/coordination/presence/presence.go
+++ b/coordination/presence/presence.go
@@ -1,3 +1,8 @@
+// Package presence allows individual nodes in a cluster to let their
+// presence known to other peers through a central registry (a
+// directory on etcd). Nodes can store a small amount of information
+// along with their state.
+//
package presence
import (
@@ -23,6 +28,8 @@ type Client struct {
path string
}
+// NewClient returns a simple client that can look up the registry and
+// return a list of active nodes.
func NewClient(client EtcdClient, path string) *Client {
return &Client{
client: client,
@@ -58,7 +65,8 @@ type Presence struct {
}
// New returns a new Presence worker that establishes node presence at
-// the specified path.
+// the specified path. It will create a new unique file below that
+// directory, and remove it when Stop() is called (or the TTL expires).
func New(client EtcdClient, path string, stateFn StateFn, ttl uint64) *Presence {
return &Presence{
Client: NewClient(client, path),
diff --git a/coordination/watcher/cache.go b/coordination/watcher/cache.go
index 9372281d..d826239f 100644
--- a/coordination/watcher/cache.go
+++ b/coordination/watcher/cache.go
@@ -12,6 +12,10 @@ type hasClose interface {
Close() error
}
+// Cache for data that is expensive to decode. Keeps the (decoded)
+// contents of the remote etcd directory in memory. Uses a DecodeFn to
+// parse the encoded data stored in etcd only when it is actually
+// modified.
type Cache struct {
w *Watcher
decodeFn DecodeFn
@@ -25,6 +29,7 @@ func defaultDecodeFn(value string) interface{} {
return value
}
+// NewCache returns a new Cache mirroring 'path'.
func NewCache(client EtcdClient, path string, decodeFn DecodeFn) *Cache {
if decodeFn == nil {
decodeFn = defaultDecodeFn
@@ -44,6 +49,7 @@ func NewCache(client EtcdClient, path string, decodeFn DecodeFn) *Cache {
return c
}
+// Close the Cache and release associated resources.
func (c *Cache) Close() {
c.w.Stop()
}
@@ -90,6 +96,7 @@ func (c *Cache) handleResponse(resp *etcd.Response) {
c.lock.Unlock()
}
+// Get a value from the cache.
func (c *Cache) Get(key string) (interface{}, bool) {
c.lock.RLock()
value, ok := c.data[key]
@@ -97,6 +104,7 @@ func (c *Cache) Get(key string) (interface{}, bool) {
return value, ok
}
+// Get a value and the associated etcd index.
func (c *Cache) GetWithIndex(key string) (interface{}, uint64, bool) {
c.lock.RLock()
index := c.index
diff --git a/coordination/watcher/watcher.go b/coordination/watcher/watcher.go
index 430c0bed..3770edc9 100644
--- a/coordination/watcher/watcher.go
+++ b/coordination/watcher/watcher.go
@@ -1,3 +1,13 @@
+// Package watcher monitors a path on etcd for changes, and sends them
+// on a channel. It can thus build a local in-memory cache of the
+// contents of the etcd directory, which is convenient for small
+// datasets that don't change often (configuration data, for
+// instance).
+//
+// The package includes both a simple cache implementation (Cache),
+// and a background worker to synchronize arbitrary objects
+// implementing the Syncable interface (Syncer).
+//
package watcher
import (
diff --git a/vagrant-test/run-tests b/vagrant-test/run-tests
new file mode 100755
index 00000000..9a78ee81
--- /dev/null
+++ b/vagrant-test/run-tests
@@ -0,0 +1,16 @@
+#!/bin/sh
+#
+# Test that the running autoradio cluster on Vagrant is performing
+# as expected.
+#
+
+expected_dns="192.168.50.2 192.168.50.3 192.168.50.4"
+dns=$(dig +short stream.autora.dio @192.168.50.3 | sort | tr '\n' ' ' | sed -e 's/ $//')
+if [ "$dns" != "$expected_dns" ]; then
+ echo "DNS query for stream.autora.dio did not return expected results: ${expected_dns}" >&2
+ exit 1
+fi
+
+echo "Vagrant autoradio cluster looks ok." >&2
+
+exit 0
--
GitLab