time: document proper usage of Timer.Stop

[anacrolix]

After calling Timer.Stop(), and then clearing the channel, the channel can later be filled anyway. Presumably the task to send to the Timer channel has been put on a run queue, and isn't remove when Stop is called. Here's a test that demonstrates it:

func TestTimerFiresAfterStop(t *testing.T) {
    fail := make(chan struct{})
    done := make(chan struct{})
    defer close(done)
    for range iter.N(1000) {
        tr := time.NewTimer(0)
        tr.Stop()
        // There may or may not be a value in the channel now. But definitely
        // one should not be added after we receive it.
        select {
        case <-tr.C:
        default:
        }
        // Now set the timer to trigger in hour. It definitely shouldn't be
        // receivable now for an hour.
        tr.Reset(time.Hour)
        go func() {
            select {
            case <-tr.C:
                // As soon as the channel receives, notify failure.
                fail <- struct{}{}
            case <-done:
            }
        }()
    }
    select {
    case <-fail:
        t.FailNow()
    case <-time.After(time.Second):
    }
}

Increase the value in iter.N if it doesn't trigger on your system initially. Note that it isn't even necessary to call Reset() to trigger this. You can remove that line. You can Stop() a timer, and then still receive a value from it, some time after you drain it.

[ulikunitz]

The go routine should get the timer as argument, because otherwise there will be a race. But even with that fixed the channel fires every few test runs.

[bradfitz]

Aside: you do realize the iter package was a joke, right?

I'd change your example to use for i := 0; i < 1000; i++.

@ulikunitz, I think the code looks fine. The goroutine closure captures the new tr variable each iteration.

[cespare]

This bit of code:

tr := time.NewTimer(0)
tr.Stop()
// There may or may not be a value in the channel now. But definitely
// one should not be added after we receive it.
select {
        case <-tr.C:
        default:
}

does not guarantee that there isn't an in-flight value on tr.C, because Stop may not have stopped the timer before it fired, yet that doesn't mean that the channel was ready to receive when the select ran. So it's a race.

See extensive previous discussion on #11513 and https://groups.google.com/forum/#!topic/golang-dev/c9UUfASVPoU.

In the latter thread, @rsc suggests doing

if !timer.Stop() {
  <-timer.C
}

I also previously filed #12721 to ask for an easier way to create a new, stopped timer.

[bradfitz]

Indeed, looks like a dup of #12721.

But let's keep this bug open as a documentation fix issue for Timer.Stop. An example might help too.

[anacrolix]

Yes, it is a race.

if !timer.Stop() {
  <-timer.C
}

Is not sufficient, as there's no way to tell if the fired event has already been received. Which in my use case it often has. This is necessary, as linked in the thread: http://play.golang.org/p/Ys9qqanqmU

[ulikunitz]

The race appears to be in the function timerproc() in runtime/time.go. The mutex timers.lock is unlocked for calling the runtime timer function, which sends the time into the channel. Therefore timer.Stop can return before the time value is written to the channel.

Calling the runtime timer function with the mutex locked, ensures that timer.Stop cannot return before the channel is written too. I tested all.bash and also checked the test function from @anacrolix. I think this can be justified because there is no way for a user to set the runtime timer function. I even checked whether I can compile the time package outside of GOROOT; it didn't work.

On the other hand I can't see how

if !tr.Stop() {
    <-tr.C
}

should fail. At least on Linux AMD64 I was not able to trigger the modified test to fail, even after creating 1 million goroutines.

It appears there are two ways to address this issue:

A) Amend the documentation of time.Stop(), or
B) calling the runtime timer function with the timers.lock hold.

I prefer B because it fixes the Test above.

@bradfitz You are right, there is no race in the test code.

[rsc]

I still don't think there's a race here. This is a documentation issue. See
https://groups.google.com/d/msg/golang-dev/c9UUfASVPoU/tlbK2BpFEwAJ for how to use Stop correctly.

See also #11513.

[rsc]

I should add: There is an argument for making

tr := time.NewTimer(0)
tr.Stop()
// There may or may not be a value in the channel now. But definitely
// one should not be added after we receive it.
select {
        case <-tr.C:
        default:
}

work, but it doesn't today, and we're certainly not going to do that for Go 1.7. Maybe early in Go 1.8 if someone wants to file a different bug.

[gopherbot]

CL https://golang.org/cl/23575 mentions this issue.