runtime: clarify g object vs stack memory lifetime in HACKING.md

The documentation states that g objects are "never freed" but does not
clarify that goroutine stack memory is managed separately. This can be
confusing as it might imply that all goroutine memory (including stacks)
is retained indefinitely.

Add a paragraph in the Stacks section clarifying that:
- Stack memory may be freed when a goroutine exits
- Stacks at the starting size are retained for reuse
- Grown stacks are freed and reallocated when needed
- The g object itself is never freed, only its stack memory

Fixes #65843

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Change-Id: Icb3afbb5392401d695ab129c341ce10106e5a4f0
Reviewed-on: https://go-review.googlesource.com/c/go/+/741505
Reviewed-by: Michael Knyszek <mknyszek@google.com>
Auto-Submit: Keith Randall <khr@golang.org>
Reviewed-by: Keith Randall <khr@golang.org>
Reviewed-by: Keith Randall <khr@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

diff --git a/src/runtime/HACKING.md b/src/runtime/HACKING.md
index 89727ee80f1b4a06b85ba682aba5bacb63e111bf..924471e835f509a2e1e57e047221e4552a0e07d3 100644 (file)
--- a/src/runtime/HACKING.md
+++ b/src/runtime/HACKING.md
@@ -60,6 +60,14 @@ Every non-dead G has a *user stack* associated with it, which is what
 user Go code executes on. User stacks start small (e.g., 2K) and grow
 or shrink dynamically.
 
+When a goroutine exits, its stack memory may be freed immediately or
+retained for reuse by another goroutine. If the stack has the default
+starting size, it is kept with the `g` object for reuse. If the stack
+has grown beyond the starting size, it is freed and a new stack will
+be allocated when the `g` is reused. Note that the `g` object itself
+is never freed (as described above), but its associated stack memory
+is managed separately and can be reclaimed.
+
 Every M has a *system stack* associated with it (also known as the M's
 "g0" stack because it's implemented as a stub G) and, on Unix
 platforms, a *signal stack* (also known as the M's "gsignal" stack).