runtime: expand GOMAXPROCS documentation

Expand the GOMAXPROCS documentation to include details of how defaults
are selected, as this is something that inquisitive minds will want to
know. I've added an additional warning that these details may changed.

While we are here, add a bit more structure to make it easier to find
the relevant parts of the documentation.

For #73193.

Change-Id: I6a6a636cae93237e3e3174822490d51805e70990
Reviewed-on: https://go-review.googlesource.com/c/go/+/685318
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Auto-Submit: Sean Liao <sean@liao.dev>
Reviewed-by: Sean Liao <sean@liao.dev>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Carlos Amedee <carlos@golang.org>

src/runtime/debug.go

@@ -13,13 +13,23 @@ import (
 // simultaneously and returns the previous setting. If n < 1, it does not change
 // the current setting.
 //
+// # Default
+//
 // If the GOMAXPROCS environment variable is set to a positive whole number,
 // GOMAXPROCS defaults to that value.
 //
-// Otherwise, the Go runtime selects an appropriate default value based on the
-// number of logical CPUs on the machine, the process’s CPU affinity mask, and,
-// on Linux, the process’s average CPU throughput limit based on cgroup CPU
-// quota, if any.
+// Otherwise, the Go runtime selects an appropriate default value from a combination of
+//  - the number of logical CPUs on the machine,
+//  - the process’s CPU affinity mask,
+//  - and, on Linux, the process’s average CPU throughput limit based on cgroup CPU
+//    quota, if any.
+//
+// If GODEBUG=containermaxprocs=0 is set and GOMAXPROCS is not set by the
+// environment variable, then GOMAXPROCS instead defaults to the value of
+// [runtime.NumCPU]. Note that GODEBUG=containermaxprocs=0 is [default] for
+// language version 1.24 and below.
+//
+// # Updates
 //
 // The Go runtime periodically updates the default value based on changes to
 // the total logical CPU count, the CPU affinity mask, or cgroup quota. Setting
@@ -27,11 +37,36 @@ import (
 // GOMAXPROCS disables automatic updates. The default value and automatic
 // updates can be restored by calling [SetDefaultGOMAXPROCS].
 //
-// If GODEBUG=containermaxprocs=0 is set, GOMAXPROCS defaults to the value of
-// [runtime.NumCPU]. If GODEBUG=updatemaxprocs=0 is set, the Go runtime does
-// not perform automatic GOMAXPROCS updating.
+// If GODEBUG=updatemaxprocs=0 is set, the Go runtime does not perform
+// automatic GOMAXPROCS updating. Note that GODEBUG=updatemaxprocs=0 is
+// [default] for language version 1.24 and below.
 //
-// The default GOMAXPROCS behavior may change as the scheduler improves.
+// # Compatibility
+//
+// Note that the default GOMAXPROCS behavior may change as the scheduler
+// improves, especially the implementation detail below.
+//
+// # Implementation details
+//
+// When computing default GOMAXPROCS via cgroups, the Go runtime computes the
+// "average CPU throughput limit" as the cgroup CPU quota / period. In cgroup
+// v2, these values come from the cpu.max file. In cgroup v1, they come from
+// cpu.cfs_quota_us and cpu.cfs_period_us, respectively. In container runtimes
+// that allow configuring CPU limits, this value usually corresponds to the
+// "CPU limit" option, not "CPU request".
+//
+// The Go runtime typically selects the default GOMAXPROCS as the minimum of
+// the logical CPU count, the CPU affinity mask count, or the cgroup CPU
+// throughput limit. However, it will never set GOMAXPROCS less than 2 unless
+// the logical CPU count or CPU affinity mask count are below 2.
+//
+// If the cgroup CPU throughput limit is not a whole number, the Go runtime
+// rounds up to the next whole number.
+//
+// GOMAXPROCS updates are performed up to once per second, or less if the
+// application is idle.
+//
+// [default]: https://go.dev/doc/godebug#default
 func GOMAXPROCS(n int) int {
 	if GOARCH == "wasm" && n > 1 {
 		n = 1 // WebAssembly has no threads yet, so only one CPU is possible.