Expose advance mechanism to timers (#3)

Author: efritz

README.md

@@ -36,7 +36,7 @@ clock.Advance(time.Day)
 clock.Now() // returns Feb 13, 1989
 ```
 
-The `Advance` method will also trigger a value on the channels created by the `After` and `Ticker` functions.
+The `Advance` method will also trigger a value on the channels created by the `After` and `Ticker` functions, if enough virtual time has elapsed for the events to fire.
 
 ```go
 clock := glock.NewMockClockAt(time.Unix(603288000, 0))
@@ -51,15 +51,60 @@ clock.Advance(time.Second * 30) // Fires c1
 
 ```go
 clock := glock.NewMockClock()
+
 ticker := clock.NewTicker(time.Minute)
+defer ticker.Stop()
+
+go func() {
+    for range ticker.Chan() {
+        // ...
+    }
+}()
 
-ch := ticker.Chan()
 clock.Advance(time.Second * 30)
 clock.Advance(time.Second * 30) // Fires ch
 clock.Advance(time.Second * 30)
 clock.Advance(time.Second * 30) // Fires ch
 ```
 
+The `Advance` method will send a value to any current listener registered to a channel on the clock. Timing these calls in relation with the clock consumer is not always an easy task. A variation of the advance method, `BlockingAdvance` can be used in its place when you want to first ensure that there is a listener on a channel returned by `After`.
+
+
+```go
+clock := glock.NewMockClock()
+
+go func() {
+    <-clock.After(time.Second * 30)
+}()
+
+clock.BlockingAdvance(time.Second * 30) // blocks until the concurrent call to After
+clock.BlockingAdvance(time.Second * 30) // blocks indefinitely as there are no listeners
+```
+
+Ticker instances themselves have the same time advancing mechanisms. Using `Advance` on a ticker (or using `Advance` on the clock from which a ticker was created) will cause the ticker to fire _once_ and then forward itself to the current time. This mimics the behavior of the Go runtime clock (see the test functions `^TestTickerOffset`).
+
+Where the `Advance` method sends the ticker's time to the consumer in a background goroutine, the `BlockingAdvance` variant will send the value in the caller's goroutine.
+
+```go
+ticker := clock.NewMockTicker(time.Second * 30)
+defer ticker.Stop()
+
+go func() {
+    <-ticker.Chan()
+    <-ticker.Chan()
+    <-ticker.Chan()
+}()
+
+ticker.BlockingAdvance(time.Second * 15)
+ticker.BlockingAdvance(time.Second * 15) // Fires ch
+ticker.BlockingAdvance(time.Second * 15)
+ticker.BlockingAdvance(time.Second * 15) // Fires ch
+ticker.BlockingAdvance(time.Second * 60) // Fires ch _once_
+
+ticker.Advance(time.Second * 30)         // does not block; sent asynchronously
+ticker.BlockingAdvance(time.Second * 30) // blocks indefinitely as there are no listeners
+```
+
 ## Context Utilities
 
 If you'd like to use a `context.Context` as a way to make a glock `Clock` available, this

advanceable.go

@@ -0,0 +1,80 @@
+package glock
+
+import (
+	"sync"
+	"time"
+)
+
+type Advanceable interface {
+	Advance(duration time.Duration)
+	BlockingAdvance(duration time.Duration)
+	SetCurrent(now time.Time)
+}
+
+// advanceable is the base type for mock clocks and tickers. This struct is
+// written to be used as as a mixin, where the containing struct can mutate
+// its internals (assuming correct coordination is used).
+//
+// An "advanceable" struct has a current time set of subscribers that may
+// change over time. The current time can be moved explicitly by the user.
+type advanceable struct {
+	now         time.Time
+	subscribers []subscriber
+	m           *sync.Mutex
+	cond        *sync.Cond
+}
+
+type subscriber interface {
+	// signal performs some behavior if the given current time is after a
+	// deadline registered previously. This method should not block. If the
+	// subscriber is still interested in being updated with the current
+	// time, it should return true; the clock or timer instance will drop
+	// a reference to this subscriber otherwise.
+	signal(now time.Time) (requeue bool)
+}
+
+// newAdvanceableAt returns a new advanceable struct with the given current time.
+func newAdvanceableAt(now time.Time) *advanceable {
+	m := &sync.Mutex{}
+
+	return &advanceable{
+		now:  now,
+		m:    m,
+		cond: sync.NewCond(m),
+	}
+}
+
+// Advance will advance the clock's internal time by the given duration.
+func (a *advanceable) Advance(duration time.Duration) {
+	a.m.Lock()
+	a.setCurrent(a.now.Add(duration))
+	a.m.Unlock()
+}
+
+// SetCurrent sets the clock's internal time to the given time.
+func (a *advanceable) SetCurrent(now time.Time) {
+	a.m.Lock()
+	a.setCurrent(now)
+	a.m.Unlock()
+}
+
+// setCurrent sets the new current time and invokes and filters the list of
+// subscribers.
+func (a *advanceable) setCurrent(now time.Time) {
+	filtered := a.subscribers[:0]
+	for _, e := range a.subscribers {
+		if e.signal(now) {
+			filtered = append(filtered, e)
+		}
+	}
+
+	a.now = now
+	a.subscribers = filtered
+	a.cond.Broadcast()
+}
+
+// register marks a subscriber to be updated when the current time changes.
+func (a *advanceable) register(subscriber subscriber) {
+	a.subscribers = append(a.subscribers, subscriber)
+	a.cond.Broadcast()
+}