time: clarify Ticker documentation

[pjebs]

The documentation for Stop() states:

Stop turns off a ticker. After Stop, no more ticks will be sent. Stop does not close the channel, to prevent a read from the channel succeeding incorrectly.

Can the documentation clarify what "to prevent a read from the channel succeeding incorrectly."means.

Should we close the channel ourself if we want to help the garbage collector?

[ianlancetaylor]

Closing channels has no affect on the garbage collector, which doesn't care whether the channel is closed or not.

What the doc means is that if Stop closes the channel, then any read from the channel will complete, returning the zero value. If there is some goroutine sitting in a select statement reading from the ticker, that case will become ready to be chosen. That may cause the goroutine to take an unexpected action, as though a tick occurred, although it did not.

[conspicuousClockwork]

@ianlancetaylor how does this sound?

Stop turns off a ticker. After Stop, no more ticks will be sent. Stop does not close the channel, in order to prevent potential side effects, such as the channel succeeding incorrectly.

[ianlancetaylor]

@conspicuousClockwork Thanks. You need to say a read from the channel, as channels by themselves do not succeed or fail. And with that change it's not clear to me that your text is much of an improvement. If we want to say anything at all here, perhaps it should be along the lines of "in case another goroutine is concurrently reading from the channel, so that the read does not succeed incorrectly."

[conspicuousClockwork]

@ianlancetaylor Whoops, I must have erased part of it when I was thinking about how the text could be adjusted. I was trying to make as few additions as I could to clarify/phrase it in a different way but your suggestion seems better.

Stop turns off a ticker. After Stop, no more ticks will be sent. Stop does not close the channel; this is in order to prevent potential side effects, such as a goroutine concurrently reading from the channel and succeeding incorrectly.

How is that?

[ianlancetaylor]

Seems OK to me. Perhaps "the read succeeding incorrectly." Want to send a pull request?

[conspicuousClockwork]

Yup, I'll go ahead and open that.

[gopherbot]

Change https://golang.org/cl/122715 mentions this issue: time/tick: add clarification to Stop() documentation