time: clarify Timer.Reset behavior on AfterFunc Timers

Fixes #28100

Change-Id: I37d4d7badf455e4ecf982d4fc7cb070052de2e45
Reviewed-on: https://go-review.googlesource.com/c/go/+/285632
Trust: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

1 files changed, 12 insertions, 1 deletions

diff --git a/src/time/sleep.go b/src/time/sleep.go
index 90d8a18a68..4f45799414 100644
--- a/src/time/sleep.go
+++ b/src/time/sleep.go
@@ -101,7 +101,9 @@ func NewTimer(d Duration) *Timer {
 // It returns true if the timer had been active, false if the timer had
 // expired or been stopped.
 //
-// Reset should be invoked only on stopped or expired timers with drained channels.
+// For a Timer created with NewTimer, Reset should be invoked only on
+// stopped or expired timers with drained channels.
+//
 // If a program has already received a value from t.C, the timer is known
 // to have expired and the channel drained, so t.Reset can be used directly.
 // If a program has not yet received a value from t.C, however,
@@ -120,6 +122,15 @@ func NewTimer(d Duration) *Timer {
 // is a race condition between draining the channel and the new timer expiring.
 // Reset should always be invoked on stopped or expired channels, as described above.
 // The return value exists to preserve compatibility with existing programs.
+//
+// For a Timer created with AfterFunc(d, f), Reset either reschedules
+// when f will run, in which case Reset returns true, or schedules f
+// to run again, in which case it returns false.
+// When Reset returns false, Reset neither waits for the prior f to
+// complete before returning nor does it guarantee that the subsequent
+// goroutine running f does not run concurrently with the prior
+// one. If the caller needs to know whether the prior execution of
+// f is completed, it must coordinate with f explicitly.
 func (t *Timer) Reset(d Duration) bool {
 	if t.r.f == nil {
 		panic("time: Reset called on uninitialized Timer")