testing: improve b.Loop example

The current b.Loop example doesn't focus on the basic usage of b.Loop.
Replace this with a new example that uses (slightly) more realistic
things to demonstrate the most salient points of b.Loop.

We also move the example into an example file so that we can write a
real Benchmark function and a real function to be benchmarks, which
makes this much closer to what a user would actually write.

Updates #61515.

Change-Id: I4d830b3bfe3eb3cd8cdecef469fea0541baebb43
Reviewed-on: https://go-review.googlesource.com/c/go/+/635896
Auto-Submit: Austin Clements <austin@google.com>
Reviewed-by: Junyang Shao <shaojunyang@google.com>
Reviewed-by: Cherry Mui <cherryyz@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

1 files changed, 48 insertions, 0 deletions

diff --git a/src/testing/example_loop_test.go b/src/testing/example_loop_test.go
new file mode 100644
index 0000000000..eff8bab352
--- /dev/null
+++ b/src/testing/example_loop_test.go
@@ -0,0 +1,48 @@
+// Copyright 2024 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package testing_test
+
+import (
+	"math/rand/v2"
+	"testing"
+)
+
+// ExBenchmark shows how to use b.Loop in a benchmark.
+//
+// (If this were a real benchmark, not an example, this would be named
+// BenchmarkSomething.)
+func ExBenchmark(b *testing.B) {
+	// Generate a large random slice to use as an input.
+	// Since this is done before the first call to b.Loop(),
+	// it doesn't count toward the benchmark time.
+	input := make([]int, 128<<10)
+	for i := range input {
+		input[i] = rand.Int()
+	}
+
+	// Perform the benchmark.
+	for b.Loop() {
+		// Normally, the compiler would be allowed to optimize away the call
+		// to sum because it has no side effects and the result isn't used.
+		// However, inside a b.Loop loop, the compiler ensures function calls
+		// aren't optimized away.
+		sum(input)
+	}
+
+	// Outside the loop, the timer is stopped, so we could perform
+	// cleanup if necessary without affecting the result.
+}
+
+func sum(data []int) int {
+	total := 0
+	for _, value := range data {
+		total += value
+	}
+	return total
+}
+
+func ExampleB_Loop() {
+	testing.Benchmark(ExBenchmark)
+}