8311978: Shenandoah: Create abstraction over heap metrics for heuristics

src/hotspot/share/gc/shenandoah/heuristics/shenandoahAdaptiveHeuristics.hpp

@@ -52,6 +52,17 @@ class ShenandoahAllocationRate : public CHeapObj<mtGC> {
   TruncatedSeq _rate_avg;
 };
 
+/*
+ * The adaptive heuristic tracks the allocation behavior and average cycle
+ * time of the application. It attempts to start a cycle with enough time
+ * to complete before the available memory is exhausted. It errors on the
+ * side of starting cycles early to avoid allocation failures (degenerated
+ * cycles).
+ *
+ * This heuristic limits the number of regions for evacuation such that the
+ * evacuation reserve is respected. This helps it avoid allocation failures
+ * during evacuation. It preferentially selects regions with the most garbage.
+ */
 class ShenandoahAdaptiveHeuristics : public ShenandoahHeuristics {
 public:
   ShenandoahAdaptiveHeuristics(ShenandoahHeapStats* heap_stats);

src/hotspot/share/gc/shenandoah/heuristics/shenandoahAggressiveHeuristics.hpp

@@ -27,6 +27,10 @@
 
 #include "gc/shenandoah/heuristics/shenandoahHeuristics.hpp"
 
+/*
+ * This is a diagnostic heuristic that continuously runs collections
+ * cycles and adds every region with any garbage to the collection set.
+ */
 class ShenandoahAggressiveHeuristics : public ShenandoahHeuristics {
 public:
   ShenandoahAggressiveHeuristics(ShenandoahHeapStats* heap_stats);

src/hotspot/share/gc/shenandoah/heuristics/shenandoahCompactHeuristics.hpp

@@ -27,6 +27,10 @@
 
 #include "gc/shenandoah/heuristics/shenandoahHeuristics.hpp"
 
+/*
+ * This heuristic has simpler triggers than the adaptive heuristic. The
+ * size of the collection set is limited to 3/4 of available memory.
+ */
 class ShenandoahCompactHeuristics : public ShenandoahHeuristics {
 public:
   ShenandoahCompactHeuristics(ShenandoahHeapStats* heap_stats);

src/hotspot/share/gc/shenandoah/heuristics/shenandoahHeapStats.hpp

@@ -27,6 +27,13 @@
 
 #include "utilities/globalDefinitions.hpp"
 
+/*
+ * The purpose of this interface is to decouple the heuristics from a
+ * direct dependency on the ShenandoahHeap singleton instance. This is
+ * done to facilitate future unit testing of the heuristics and to support
+ * future operational modes of Shenandoah in which the heap may be split
+ * into generations.
+ */
 class ShenandoahHeapStats {
 public:
   virtual size_t soft_max_capacity() const = 0;

src/hotspot/share/gc/shenandoah/heuristics/shenandoahHeuristics.hpp

@@ -60,6 +60,11 @@
 class ShenandoahCollectionSet;
 class ShenandoahHeapRegion;
 
+/*
+ * Shenandoah heuristics are primarily responsible for deciding when to start
+ * a collection cycle and choosing which regions will be evacuated during the
+ * cycle.
+ */
 class ShenandoahHeuristics : public CHeapObj<mtGC> {
   static const intx Concurrent_Adjust   = -1; // recover from penalties
   static const intx Degenerated_Penalty = 10; // how much to penalize average GC duration history on Degenerated GC

src/hotspot/share/gc/shenandoah/heuristics/shenandoahPassiveHeuristics.hpp

@@ -27,6 +27,15 @@
 
 #include "gc/shenandoah/heuristics/shenandoahHeuristics.hpp"
 
+/*
+ * The passive heuristic is for use only with the passive mode. In
+ * the passive mode, Shenandoah only performs STW (i.e., degenerated)
+ * collections. All the barriers are disabled and there are no concurrent
+ * activities. Therefore, this heuristic _never_ triggers a cycle. It
+ * will select regions for evacuation based on ShenandoahEvacReserve,
+ * ShenandoahEvacWaste and ShenandoahGarbageThreshold. Note that it does
+ * not attempt to evacuate regions with more garbage.
+ */
 class ShenandoahPassiveHeuristics : public ShenandoahHeuristics {
 public:
   ShenandoahPassiveHeuristics(ShenandoahHeapStats* heap_stats);

src/hotspot/share/gc/shenandoah/heuristics/shenandoahStaticHeuristics.hpp

@@ -27,6 +27,11 @@
 
 #include "gc/shenandoah/heuristics/shenandoahHeuristics.hpp"
 
+/*
+ * The static heuristic will trigger cycles if the available memory falls
+ * below ShenandoahMinFreeThreshold percentage of total capacity. This
+ * heuristic will attempt to evacuation any region with any garbage.
+ */
 class ShenandoahStaticHeuristics : public ShenandoahHeuristics {
 public:
   ShenandoahStaticHeuristics(ShenandoahHeapStats* heap_stats);