Documentation: misleading description of GOGC

[MikeMitchellWebDev]

Go version

1.22

Output of go env in your module/workspace:

n/a

What did you do?

If I have a live heap of 7, with no non-heap source of work, the target heap goal of the garbage collector is calculated like this:

`        target := 7 + (7 + 0 + 0) GOGC/100`

So if GOGC is 100, the total heap footprint will be 14 at the next gc cycle. To state the obvious, GOGC is used to calculate the heap goal but after the heap goal is set it is the operation of the pacer that determines whether the gc occurs before the target or overshoots the target.

I use the above example because in the garbage collector guide https://tip.golang.org/doc/gc-guide there is an inaccurate description of GOGC. Using the numbers 8 for live heap (and 2 for GoRoots), the guide calculates the target correctly like this:

   ` target := 8 + (8+2) GOGC/100 //target is 18 with GOGC of 100`

but then there is a misleading verbal description of the formula. It goes: "Then, with a GOGC value of 100, the amount of new memory that will be allocated before the next GC runs will be 10 MiB, or 100% of the 10 MiB of work, for a total heap footprint of 18MiB." It is misleding to say, "or 100% of the 10MiB of work" as it implies that a GOGC setting of 100 indicates, after the goal is already percent, what percent of the new work (100%) will be done to reach that goal.

To put it another way, by saying 100% of the 10 MiB of work, you are implying that, with a GOGC setting of 100, 100% of the difference between 8 (the current heap) and 18 MiB (the projected heap footprint) will be carried out due to a GOGC setting of 100, which is obviously totally false, as it would also be false to suggest a GOGC setting of 50 means only 50% of the difference between 8 and 18Mib will be carried out.

Why do you add the extra stress in the sentence 10 MiB, or 100% of the 10MiB of work? Do you agree that it implies that 100% of the 10MiB difference between 8 and 18 will be done due to a GOGC setting of 100?

Because of my misunderstanding of what you were trying to say, I misinterpreted your intention in the next two sentences of the paragraph, and I reported the issue as a math error on Friday, as I thought the two elliptical sentences ending the paragraph (not quoted here) were incorrectly summarizing the target heap formula. A member of your team quite rightly closed the issue as there is no math error. I only re-opened this issue under a different topic because I believe I have finally put my finger on what is wrong (in my opinion) with this paragraph, and I believe it could be a potentially serious issue. An incorrect understanding of GOGC can lead to an incorrect setting at runtime with no protections in place to catch it, which could lead to an increase likelihood of an unexpected program crash. Go programs are used in all different types of devices and a GOGC setting needs to be used carefully. People look to this blog for accurate information. Whether you rewrite the paragraph is up to you. I know you have a lot of other issues to attend to. Thank you for your attention.

What did you see happen?

see above

What did you expect to see?

more accurately phrased information about GOGC

[zongzw]

I have the same confusion when it comes to understanding this text. I'm not an english-native speaker, but can read/write kinds of ducment. However, I felt difficult reading this page..Apologize if this comment brings you chaos..

[seankhliao]

I don't see the issue here. Given the premise that GOGC is used to calculate a new goal, I don't see where else you could have come up with a goal of 18.