From b8be5de81ee78f51fbd600498093b542e75a710e Mon Sep 17 00:00:00 2001 From: kovan Date: Tue, 3 Feb 2026 16:07:55 +0100 Subject: [PATCH] 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 --- src/runtime/HACKING.md | 8 ++++++++ 1 file changed, 8 insertions(+) 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). -- 2.52.0