From: kovan Date: Tue, 3 Feb 2026 15:07:55 +0000 (+0100) Subject: runtime: clarify g object vs stack memory lifetime in HACKING.md X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=b8be5de81ee78f51fbd600498093b542e75a710e;p=gostls13.git 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 Change-Id: Icb3afbb5392401d695ab129c341ce10106e5a4f0 Reviewed-on: https://go-review.googlesource.com/c/go/+/741505 Reviewed-by: Michael Knyszek Auto-Submit: Keith Randall Reviewed-by: Keith Randall Reviewed-by: Keith Randall LUCI-TryBot-Result: Go LUCI --- diff --git a/src/runtime/HACKING.md b/src/runtime/HACKING.md index 89727ee80f..924471e835 100644 --- 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).