testing: add an example showcasing B.RunParallel with B.ReportMetric

[mvdan]

I had a parallel benchmark in the form of:

var totalFoo int64
b.RunParallel(func(pb *testing.PB) {
	for pb.Next() {
		// benchmark...
		totalFoo += someFoo()
	}
})
b.ReportMetric(float64(totalAmount)/float64(b.N), "foo/op")

I was taking a second look at the benchmark because dividing by b.N seemed fishy. This is a parallel benchmark, where I iterate via pb.Next and not b.N, so can I rely on b.N being an accurate detail of how many iterations were run across all goroutines?

The docs seem to imply so:

RunParallel runs a benchmark in parallel. It creates multiple goroutines and distributes b.N iterations among them.

ReportMetric adds "n unit" to the reported benchmark results. If the metric is per-iteration, the caller should divide by b.N

Still, I had to re-read the docs multiple times to convince myself. I think it would be nice to add an example on ReportMetric for parallel benchmarks, such as func ExampleB_ReportMetric_parallel, to help clarify the interaction between the two and how they are meant to be used.

And there's another reason why an example would be good: since RunParallel hides the goroutine spawning from the user, it's relatively easy to introduce data races by mistake, like I did above! totalFoo += someFoo() would need to be something like atomic.AddInt64(&totalFoo, someFoo()). The example could also show that.

Marking as a good candidate for first time contributors. Happy to review it too.

cc @mpvl per https://dev.golang.org/owners

[mvdan]

It might also be a good idea for RunParallel to call out that using b.N for the loop is ill advised, but it can still be used as the total number of iterations that are to be run - either during initial setup work or while collecting metrics at the end.

[gopherbot]

Change https://go.dev/cl/415035 mentions this issue: testing: give an example for ReportMetrics in a parallel benchmark

[gopherbot]

Change https://go.dev/cl/437815 mentions this issue: testing: add an example showcasing B.RunParallel with B.ReportMetric