time: Timer.Reset documentation not accurate for AfterFunc timers

[bradfitz]

https://golang.org/pkg/time/#Timer.Reset says:

Resetting a timer must take care not to race with the send into t.C that happens when the current timer expires. 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. 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:

And proceeds to give an example of proper usage of Reset.

But a Timer created by AfterFunc never sends on the channel.

We should probably say something about AfterFunc in the Timer.Reset docs.

/cc @dmitshur @ianlancetaylor

[bradfitz]

The code makes it pretty clear a value is never sent on a channel, but here's a playground example:

https://play.golang.org/p/2OSQiHS4Zt5

Code:

func NewTimer(d Duration) *Timer {
        c := make(chan Time, 1)
        t := &Timer{    
                C: c,
                r: runtimeTimer{
                        when: when(d),
                        f:    sendTime,  // <<<<<<<<<<<<<<<<<<
                        arg:  c,
                },                      
        }                       
        startTimer(&t.r)
        return t        
}                       

vs

func AfterFunc(d Duration, f func()) *Timer {
        t := &Timer{
                r: runtimeTimer{
                        when: when(d),
                        f:    goFunc, // <<<<<<<<<<<<<<<<<<
                        arg:  f,
                },
        }       
        startTimer(&t.r)
        return t
}               

[bradfitz]

Context: review comments on https://go-review.googlesource.com/c/go/+/137335

[dmitshur]

We should probably say something about AfterFunc in the Timer.Reset docs.

Agreed.

My parsing of the Reset documentation was that the f parameter to AfterFunc being executed is equivalent to a value being received from t.C, and I figured that t.C gets received internally by AfterFunc to call f (or an equivalent mechanism).

However, it'd be great to be explicit and more accurate.

[ianlancetaylor]

If Reset returns true, the function passed to AfterFunc will not be called. If Reset returns false, the function has already been called in a separate goroutine.

[mlowicki]

What about changing:

Reset should be invoked only on stopped or expired timers with drained channels.

to:

For a timer created with NewTimer, Reset should be invoked only on stopped or expired timers with drained channels.

?