Typos and possible content errors in "Garbage Collection in Java" tutorial ( https://dev.java/learn/jvm/tool/garbage-collection/ )

[willy-b]

Hello dev.java team!

Thanks again for these excellent tutorials. I write to report a few typos and possible content errors in the "Garbage Collection in Java" tutorial ( https://dev.java/learn/jvm/tool/garbage-collection/ ). At least the following typos/issues are present.

---

In what is currently the 2nd page of the tutorial, "Garbage Collection in Java" https://dev.java/learn/jvm/tool/garbage-collection/java-specifics/ (archived as is at: https://web.archive.org/web/20260331191516/https://dev.java/learn/jvm/tool/garbage-collection/java-specifics/ ):

• In the sentence, "The garbage collector doesn't scan each object individually, but insteads starts from "root" objects."

  • "insteads" should be "instead"

• In the sentence, "Examples of root objects are; local variabes, static class fields, active Java threads, and JNI references.",

  • "variabes" should be "variables" (which local variables specifically are they talking about as root here I wonder)

• In the sentence, "During the sweep phase all objects that are unreachable, those whose marking bit currently false (0), are removed."

  • "those whose marking bit currently false" should be "those whose marking bit IS currently false"

---

In the page "Deep-dive of ZGC's Architecture" of the tutorial, https://dev.java/learn/jvm/tool/garbage-collection/zgc-deepdive/ (archived as is at https://web.archive.org/web/20260331193234/https://dev.java/learn/jvm/tool/garbage-collection/zgc-deepdive/ ),
the image illustrating colored pointers and the breakdown of pointer bits used for metadata vs addressing is not consistent with the text:

Specifically:

• The text says 22 bits of metadata, diagram shows 20: The sentence "ZGC uses a 64-bit pointer with 22 bits reserved for metadata about the pointer" implies that a maximum of 64-22 == 42 bits would be left for addressing (subtracting the metadata bits from the total), but in the diagram, 44 bits are used for addressing and 20 bits (16 reserved and 4 for coloring) are used for metadata.
• The text says 18 bits reserved for future use (of 22 metadata bits), diagram shows 16 unused (of 20 metadata bits in diagram). The source sentence for this is: "Currently, 4 bits are in use, while the other 18 remain in reserve for future use." This information does not match the diagram (as highlighted in my image attached above).
• As far as comparing to other sources of information about ZGC, the diagram/image matches https://cr.openjdk.org/~pliden/slides/ZGC-PLMeetup-2019.pdf (archived as is at https://web.archive.org/web/20260402001418/https://cr.openjdk.org/~pliden/slides/ZGC-PLMeetup-2019.pdf ), which also shows 20 bits of metadata (16 unused, 4 for coloring) and 44 address bits in a 64-bit pointer (not matching text here).
• Note the diagram and text may both be valid under different configurations of ZGC, e.g. under x86 a brief check of the source code shows https://github.com/openjdk/jdk/blob/c18e3a3377e67f50ab065d1ac9365c7d43950fb6/src/hotspot/cpu/x86/gc/z/zAddress_x86.cpp#L36 , which says

  const size_t min_address_offset_bits = 42; // 4TB
  const size_t max_address_offset_bits = 44; // 16TB

showing this may be tuned according to the desired max heap size (I think after multiplying by the virtual-to-physical and numa multipliers, see https://github.com/openjdk/jdk/blob/c18e3a3377e67f50ab065d1ac9365c7d43950fb6/src/hotspot/share/gc/z/zAddress.cpp#L154 ). So the text may be describing the 4TB configuration while the diagram shows the 16TB configuration. But there is no reason for the text and diagram to be inconsistent.

Also, it may be useful to add links to the ZGC project itself for such details for further reading, e.g. citing a source for the metadata bit count or colored pointer bits.

---

Thanks again for everything on this site! I submit these reports in the hope they help avoid confusion for other readers. Feel free to leave this open even if the above items are resolved, as I would be happy to confirm the changes and also report anything else I have found (if anything) during my continued review.

[JosePaumard]

Thank you again for your review and fixes! I just pushed a fix.

[willy-b]

Thanks!

In the page "Deep-dive of ZGC's Architecture" of the tutorial, https://dev.java/learn/jvm/tool/garbage-collection/zgc-deepdive/ (archived with your changes at https://web.archive.org/web/20260402135128/https://dev.java/learn/jvm/tool/garbage-collection/zgc-deepdive/ ),

you have updated the sentence to read:

ZGC uses a 64-bit pointer with 22 bits reserved for metadata about the pointer for 4TB heaps, and 24 bits for 16TB heaps.

This appears not quite correct, as:

• 20 metadata bits are used in the 16TB address space configuration (not 24 bits) (increasing metadata space decreases addressing space)
• The 4TB and 16TB numbers are not directly the possible heap size but rather raw address space size which may be larger than the actual useful heap size
• These are example configurations but it appears it can be adjusted at least within this range on e.g. the x86 platform, on other platforms there may be different ranges.

It my be better to say something like

ZGC reserves space within its memory pointers for metadata. On x86 with 64-bit pointers for example ZGC may reserve 20 to 22 bits for metadata about the pointer, leaving 44 to 42 bits respectively for addressing (supporting 16TB to 4TB of address space respectively, see e.g. https://github.com/openjdk/jdk/blob/c18e3a3377e67f50ab065d1ac9365c7d43950fb6/src/hotspot/cpu/x86/gc/z/zAddress_x86.cpp#L36 , https://github.com/openjdk/jdk/blob/c18e3a3377e67f50ab065d1ac9365c7d43950fb6/src/hotspot/share/gc/z/zAddress.cpp#L154 )

and possibly link to https://cr.openjdk.org/~pliden/slides/ZGC-PLMeetup-2019.pdf (archived as is at https://web.archive.org/web/20260402001418/https://cr.openjdk.org/~pliden/slides/ZGC-PLMeetup-2019.pdf ) as well.

[A note for readers of my comments from various backgrounds who may not be familiar (does not need to go into the article):
"TB" by convention when referring to memory capacity can refer to the power-of-2 T prefix (2^40 or 1024^4), strictly speaking the Tebi prefix or TiB per IEC ISO 8000-13, not the SI units standard power of ten Tera prefix for 10^12, though they are close in value (since 10^3 is close to 1024 or 2^10). For a discussion of this see e.g. https://en.wikipedia.org/w/index.php?title=Byte&oldid=1345796233#Multiple-byte_units .

That is also the way TB is being used in the ZGC source code comments referenced, e.g. https://github.com/openjdk/jdk/blob/c18e3a3377e67f50ab065d1ac9365c7d43950fb6/src/hotspot/cpu/x86/gc/z/zAddress_x86.cpp#L36 , which says

const size_t min_address_offset_bits = 42; // 4TB
const size_t max_address_offset_bits = 44; // 16TB

where e.g. 44 bits would be ~17.6 TB if using power of ten Tera ( 10^12 == (10^3)^4 instead of 2^40 == (2^10)^4 called Tebi instead of Tera in IEC ISO 8000-13 ) ]

Also your other updated sentence, to note the image is showing a different configuration than what the text describes:

As of JDK 19, colored pointers in ZGC look like this diagram (for 16TB heap)

should perhaps instead say "(for 16TB address space)" or "(for the 16TB address space configuration)", as the address space requirement for a given heap size may be much larger than the actual heap size .

---

Re: "Garbage Collection in Java" https://dev.java/learn/jvm/tool/garbage-collection/java-specifics/ (archived with your updates at https://web.archive.org/web/20260402141239/https://dev.java/learn/jvm/tool/garbage-collection/java-specifics/ )

Thanks for fixing the items mentioned!

At least one item remaining is that in "Examples of root objects are;" the semicolon should be a colon.

---

Thanks!