From: Allen Li <ayatane@google.com>
Date: Thu, 11 Jul 2019 00:57:57 +0000 (+0000)
Subject: time: clarify when draining a Timer's channel is needed
X-Git-Tag: go1.13rc1~78
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=ba3149612f62c011765876d7a437095fa50e0771;p=gostls13.git

time: clarify when draining a Timer's channel is needed

Updates #27169

Change-Id: I22a6194c06529ba70b1ec648e3188c191224e321
GitHub-Last-Rev: 457b2a61a8ee4a745371c87756e5b6f38058af28
GitHub-Pull-Request: golang/go#32996
Reviewed-on: https://go-review.googlesource.com/c/go/+/185245
Reviewed-by: Rob Pike <r@golang.org>
---

diff --git a/src/time/sleep.go b/src/time/sleep.go
index 10edf6fe0e..2cc908da55 100644
--- a/src/time/sleep.go
+++ b/src/time/sleep.go
@@ -54,8 +54,8 @@ type Timer struct {
 // Stop does not close the channel, to prevent a read from the channel succeeding
 // incorrectly.
 //
-// To prevent a timer created with NewTimer from firing after a call to Stop,
-// check the return value and drain the channel.
+// To ensure the channel is empty after a call to Stop, check the
+// return value and drain the channel.
 // For example, assuming the program has not received from t.C already:
 //
 // 	if !t.Stop() {
@@ -97,10 +97,9 @@ func NewTimer(d Duration) *Timer {
 // It returns true if the timer had been active, false if the timer had
 // expired or been stopped.
 //
-// Resetting a timer must take care not to race with the send into t.C
-// that happens when the current timer expires.
+// 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 t.Reset can be used directly.
+// 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,
 // the timer must be stopped and—if Stop reports that the timer expired
 // before being stopped—the channel explicitly drained: