runtime: document MemStats better #15849
Comments
quentinmit
added
the
NeedsFix
|
additionally, would be nice if the documentation explains how they relate (or not relate) to pprof heap profile result. |
|
one example among many: from looking through mheap.go, it looks like none of the counters are decremented when memory is released to the system. Specifically, |
|
Postponing to 1.8. |
|
CL https://golang.org/cl/28972 mentions this issue. |
I'm not sure where to put this that would make sense and people would see it. We do document in runtime/pprof that profiles are as of the most recently completed GC. I've added a blurb to ReadMemStats to clarify that it's instantaneous and to contrast it with profiles, but I don't know if it'll do any good. |
|
CL https://golang.org/cl/29270 mentions this issue. |
Back in Go 1.4, memstats.next_gc was both the heap size at which GC would trigger, and the size GC kept the heap under. When we switched to concurrent GC in Go 1.5, we got somewhat confused and made this variable the trigger heap size, while gcController.heapGoal became the goal heap size. memstats.next_gc is exposed to the user via MemStats.NextGC, while gcController.heapGoal is not. This is unfortunate because 1) the heap goal is far more useful for diagnostics, and 2) the trigger heap size is just part of the GC trigger heuristic, which means it wouldn't be useful to an application even if it tried to use it. We never noticed this mess because MemStats.NextGC is practically undocumented. Now that we're trying to document MemStats, it became clear that this field had diverged from its original usefulness. Clean up this mess by shuffling things back around so that next_gc is the goal heap size and the new (unexposed) memstats.gc_trigger field is the trigger heap size. This eliminates gcController.heapGoal. Updates #15849. Change-Id: I2cbbd43b1d78bdf613cb43f53488bd63913189b7 Reviewed-on: https://go-review.googlesource.com/29270 Run-TryBot: Austin Clements <[email protected]> TryBot-Result: Gobot Gobot <[email protected]> Reviewed-by: Hyang-Ah Hana Kim <[email protected]> Reviewed-by: Rick Hudson <[email protected]>
The current runtime.MemStats documentation is terse and impenetrable. Questions about the meanings of these fields come up not infrequently. We should improve its documentation so that it actually explains what the fields mean as well as enough of the allocation model to understand their meanings and apply them to debugging.
/cc @RLH @hyangah
The text was updated successfully, but these errors were encountered: