time: Better docs for time.After

[cserban-plenty]

Go version

go1.23.1 darwin/arm64

Output of go env in your module/workspace:

Not Needed

What did you do?

package main

import (
	"fmt"
	"time"
)

func main() {
	wait := func() {
		ticker := time.NewTicker(time.Second)
		defer ticker.Stop()

		for {
			select {
			case <-ticker.C:
				fmt.Println("Tick")
			case <-time.After(time.Second * 5):
				fmt.Println("Done")
				return
			}
		}
	}

	wait()
}

What did you see happen?

time.After never gets triggered, for good reasons, it gets reset every iteration when selected. The docs could do better here.

What did you expect to see?

The example in docs looks like:

package main

import (
	"fmt"
	"time"
)

var c chan int

func handle(int) {}

func main() {
	select {
	case m := <-c:
		handle(m)
	case <-time.After(10 * time.Second):
		fmt.Println("timed out")
	}
}

And given that most of the time select is used inside a for loop, one could do so without thinking more about it, which can have side effects because in this case we'd create a new timer each iteration when the case is selected.

I know the docs at some point say that time.After is a shortcut to time.NewTimer(d).C but it also need a caution note that says it has to stay outside of a for loop.

[gabyhelp]

Related Issues

• time.After Sometimes Skips #34889 (closed)
• time: AfterFunc documentation unclear about misuse of Timer.C #60811 (closed)
• time: Timer.Reset documentation not accurate for AfterFunc timers #28100 (closed)

Related Documentation

• Package time > func After ¶

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[seankhliao]

it's quite a common pattern to use it in a for loop, and it's correct when the other select targets may be longer than the timeout. putting your per operation timeout outside the loop world be wrong if your operation takes any non trivial amount of time.

I don't see anything that should change here.