fake clock: expose the number of waiters

By using `Waiters()`, tests can wait until the expected number of waiters
are present before manipulating the clock's time, ensuring that the
goroutine under test has reached a stable state regarding its timers.

Change-Id: I64d7b89f5e178a72898885642818215e8ad73a9d

Author: aojea

clock/testing/fake_clock.go

@@ -221,14 +221,27 @@ func (f *FakeClock) setTimeLocked(t time.Time) {
 	f.waiters = newWaiters
 }
 
-// HasWaiters returns true if After or AfterFunc has been called on f but not yet satisfied (so you can
+// HasWaiters returns true if Waiters() returns non-0 (so you can
 // write race-free tests).
 func (f *FakeClock) HasWaiters() bool {
 	f.lock.RLock()
 	defer f.lock.RUnlock()
 	return len(f.waiters) > 0
 }
 
+// Waiters returns the number of "waiters" on the clock (so you can write race-free
+// tests). A waiter exists for:
+//   - every call to After that has not yet signaled its channel.
+//   - every call to AfterFunc that has not yet called its callback.
+//   - every timer created with NewTimer which is currently ticking.
+//   - every ticker created with NewTicker which is currently ticking.
+//   - every ticker created with Tick.
+func (f *FakeClock) Waiters() int {
+	f.lock.RLock()
+	defer f.lock.RUnlock()
+	return len(f.waiters)
+}
+
 // Sleep is akin to time.Sleep
 func (f *FakeClock) Sleep(d time.Duration) {
 	f.Step(d)

clock/testing/fake_clock_test.go

@@ -444,3 +444,71 @@ func assertReadTime(t testing.TB, c <-chan time.Time) time.Time {
 	}
 	panic("unreachable")
 }
+
+func TestFakeClockWaiters(t *testing.T) {
+	startTime := time.Now()
+	tc := NewFakeClock(startTime)
+
+	// Initial state
+	if count := tc.Waiters(); count != 0 {
+		t.Errorf("Expected 0 waiters initially, got %d", count)
+	}
+
+	// Add a Timer
+	timer1 := tc.NewTimer(1 * time.Second)
+	if count := tc.Waiters(); count != 1 {
+		t.Errorf("Expected 1 waiter after NewTimer, got %d", count)
+	}
+
+	// Add an After
+	_ = tc.After(2 * time.Second)
+	if count := tc.Waiters(); count != 2 {
+		t.Errorf("Expected 2 waiters after After, got %d", count)
+	}
+
+	// Add a Ticker
+	ticker := tc.NewTicker(3 * time.Second)
+	if count := tc.Waiters(); count != 3 {
+		t.Errorf("Expected 3 waiters after NewTicker, got %d", count)
+	}
+
+	// Step past the first timer
+	tc.Step(1 * time.Second)
+	<-timer1.C() // Drain channel
+	if count := tc.Waiters(); count != 2 {
+		t.Errorf("Expected 2 waiters after first timer fired, got %d", count)
+	}
+
+	// Step past the After
+	tc.Step(1 * time.Second)
+	// Note: After channel is implicitly drained by setTimeLocked
+	if count := tc.Waiters(); count != 1 {
+		t.Errorf("Expected 1 waiter after After fired, got %d", count)
+	}
+
+	// Step past the Ticker (it should re-arm)
+	tc.Step(1 * time.Second)
+	<-ticker.C() // Drain channel
+	if count := tc.Waiters(); count != 1 {
+		t.Errorf("Expected 1 waiter after Ticker fired (should re-arm), got %d", count)
+	}
+
+	// Stop the ticker (Note: fakeTicker.Stop is currently a no-op, so this won't change the count)
+	// If fakeTicker.Stop were implemented to remove the waiter, the expected count would be 0.
+	ticker.Stop()
+	if count := tc.Waiters(); count != 1 {
+		t.Errorf("Expected 1 waiter after stopping ticker (no-op), got %d", count)
+	}
+
+	// Add another timer and stop it
+	timer2 := tc.NewTimer(5 * time.Second)
+	if count := tc.Waiters(); count != 2 {
+		t.Errorf("Expected 2 waiters after adding second timer, got %d", count)
+	}
+	if stopped := timer2.Stop(); !stopped {
+		t.Errorf("Expected timer2.Stop() to return true")
+	}
+	if count := tc.Waiters(); count != 1 {
+		t.Errorf("Expected 1 waiter after stopping second timer, got %d", count)
+	}
+}