voyeur package

utils/voyeur/value.go

+// Copyright 2012, 2013 Canonical Ltd.
+// Licensed under the AGPLv3, see LICENCE file for details.
+
+// Package voyeur implements a concurrency-safe value that can be watched for
+// changes.
+package voyeur
+
+import (
+        "sync"
+)
+
+// Value represents a shared value that can be watched for changes. Methods on
+// a Value may be called concurrently.
+type Value struct {
+        val     interface{}
+        version int
+        mu      sync.RWMutex
+        wait    sync.Cond
+        closed  bool
+}
+
+// NewValue creates a new Value holding the given initial value. If initial is
+// nil, any watchers will wait until a value is set.
+func NewValue(initial interface{}) *Value {
+        v := new(Value)
+        v.wait.L = v.mu.RLocker()
+        if initial != nil {
+                v.val = initial
+                v.version++
+        }
+        return v
+}
+
+// Set sets the shared value to val.
+func (v *Value) Set(val interface{}) {
+        v.mu.Lock()
+        v.val = val
+        v.version++
+        v.wait.Broadcast()
+        v.mu.Unlock()
+}
+
+// Close closes the Value, unblocking any outstanding watchers.  Close always
+// returns nil.
+func (v *Value) Close() error {
+        v.mu.Lock()
+        v.closed = true
+        v.mu.Unlock()
+        v.wait.Broadcast()
+        return nil
+}
+
+// Get returns the current value. If the Value has been closed, ok will be
+// false.
+func (v *Value) Get() (val interface{}, ok bool) {
+        v.mu.RLock()
+        defer v.mu.RUnlock()
+        if v.closed {
+                return nil, false

[rog, 2014/02/07 15:15:17]

i wonder if this should return v.val anyway.

i can think of arguments both ways.

anyway, if we don't change it to return v.val, the docs should say that the
returned value is nil if it's closed.

[natefinch, 2014/02/07 20:05:20]

Probably no big deal to return val regardless, fixed.

+        }
+        return v.val, true
+}
+
+// Watch returns a Watcher that can be used to watch for changes to the value.
+func (v *Value) Watch() *Watcher {
+        return &Watcher{value: v}
+}
+
+// Watcher represents a single watcher of a shared value.
+type Watcher struct {
+        value   *Value
+        version int
+        current interface{}
+        closed  bool
+}
+
+// Next blocks until there is a new value to be retrieved from the value that is
+// being watched. It also unblocks when the value or the Watcher itself is closed.
+// Next reports whether the value or the Watcher itself has been closed.

[rog, 2014/02/07 15:15:17]

The final sentence isn't quite accurate (it would seem to imply that it returns
true when closed).

Perhaps:

// Next returns false if the value or the Watcher itself have
// been closed.

(I can't think of a nice way of using the "reports whether" idiom)

[natefinch, 2014/02/07 20:05:20]

Good point, you're right about it implying it returns true.  Fixed.

+func (w *Watcher) Next() bool {
+        w.value.mu.RLock()
+        defer w.value.mu.RUnlock()
+
+        // We should never go around this loop more than twice.
+        for {
+                if w.version != w.value.version {
+                        w.version = w.value.version
+                        w.current = w.value.val
+                        return true
+                }
+                if w.value.closed || w.closed {
+                        return false
+                }
+
+                // wait is magic sauce that releases the lock until triggered
+                // and then reacquires the lock, thus avoiding a deadlock.

[rog, 2014/02/07 15:15:17]

// Note that Wait releases the lock, waits for a
// condition change, and then reacquires the lock.

?

This is standard idiomatic behaviour if you're familiar
with the sync primitives. It's not really "magic sauce" :-)

[natefinch, 2014/02/07 20:05:20]

Well, yes, perhaps magic sauce is not a good comment.  However, mentioning that
it actually doesn't cause a deadlock, even though it looks like it should is
probably a good thing (not everyone is as conversant with the sync package as
you :)

Fixed.

+                w.value.wait.Wait()
+        }
+}
+
+// Close closes the Watcher without closing the underlying
+// value. It may be called concurrently with Next.
+func (w *Watcher) Close() {
+        w.value.mu.Lock()
+        w.closed = true
+        w.value.mu.Unlock()
+        w.value.wait.Broadcast()
+}
+
+// Value returns the last value that was retrieved from the watched Value.

[rog, 2014/02/07 15:15:17]

s/./by Next./

?

[natefinch, 2014/02/07 20:05:20]

Done.

+func (w *Watcher) Value() interface{} {
+        return w.current
+}