Bug 1549660 - Update docs for heap threshold parameters r=jonco
authorPaul Bone <pbone@mozilla.com>
Wed, 08 May 2019 07:01:23 +0000
changeset 534897 500d54b803cac1044a45d3205da10d3770d1eb0b
parent 534896 9d883ff1a903085737c94bb08362dedb7490a313
child 534898 3c314e0b2db01c75c490e8fbb2bae0bfb0f591c3
push id2082
push userffxbld-merge
push dateMon, 01 Jul 2019 08:34:18 +0000
treeherdermozilla-release@2fb19d0466d2 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersjonco
bugs1549660
milestone68.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1549660 - Update docs for heap threshold parameters r=jonco This change adds more detailed documentation for the parameters that control heap threasholds & factors. It also corrects some minor points and updates a code reference. Differential Revision: https://phabricator.services.mozilla.com/D30162
js/public/GCAPI.h
--- a/js/public/GCAPI.h
+++ b/js/public/GCAPI.h
@@ -133,21 +133,41 @@ typedef enum JSGCParamKey {
    * Maximum size the GC mark stack can grow to.
    *
    * Pref: none
    * Default: MarkStack::DefaultCapacity
    */
   JSGC_MARK_STACK_LIMIT = 10,
 
   /**
+   * The "do we collect?" decision depends on various parameters and can be
+   * summarised as:
+   *
+   *    ZoneSize * 1/UsageFactor > Max(ThresholdBase, LastSize) * GrowthFactor
+   *
+   * Where
+   *   ZoneSize: Current size of this zone.
+   *   LastSize: Heap size immediately after the most recent collection.
+   *   ThresholdBase: The JSGC_ALLOCATION_THRESHOLD parameter
+   *   GrowthFactor: A number above 1, calculated based on some of the
+   *                 following parameters.
+   *                 See computeZoneHeapGrowthFactorForHeapSize() in GC.cpp
+   *   UsageFactor: JSGC_ALLOCATION_THRESHOLD_FACTOR or
+   *                JSGC_ALLOCATION_THRESHOLD_FACTOR_AVOID_INTERRUPT or 1.0 for
+   *                non-incremental collections.
+   *
+   * The RHS of the equation above is calculated and sets
+   * zone->threshold.gcTriggerBytes(). When usage.gcBytes() surpasses
+   * threshold.gcTriggerBytes() for a zone, the zone may be scheduled for a GC.
+   */
+
+  /**
    * GCs less than this far apart in time will be considered 'high-frequency
    * GCs'.
    *
-   * See setGCLastBytes in jsgc.cpp.
-   *
    * Pref: javascript.options.mem.gc_high_frequency_time_limit_ms
    * Default: HighFrequencyThreshold
    */
   JSGC_HIGH_FREQUENCY_TIME_LIMIT = 11,
 
   /**
    * Start of dynamic heap growth.
    *
@@ -201,21 +221,19 @@ typedef enum JSGCParamKey {
    * If true, high-frequency GCs will use a longer mark slice.
    *
    * Pref: javascript.options.mem.gc_dynamic_mark_slice
    * Default: DynamicMarkSliceEnabled
    */
   JSGC_DYNAMIC_MARK_SLICE = 18,
 
   /**
-   * Lower limit after which we limit the heap growth.
+   * Lower limit for collecting a zone.
    *
-   * The base value used to compute zone->threshold.gcTriggerBytes(). When
-   * usage.gcBytes() surpasses threshold.gcTriggerBytes() for a zone, the
-   * zone may be scheduled for a GC, depending on the exact circumstances.
+   * Zones smaller than this size will not normally be collected.
    *
    * Pref: javascript.options.mem.gc_allocation_threshold_mb
    * Default GCZoneAllocThresholdBase
    */
   JSGC_ALLOCATION_THRESHOLD = 19,
 
   /**
    * We try to keep at least this many unused chunks in the free chunk pool at
@@ -239,26 +257,31 @@ typedef enum JSGCParamKey {
    * Whether compacting GC is enabled.
    *
    * Pref: javascript.options.mem.gc_compacting
    * Default: CompactingEnabled
    */
   JSGC_COMPACTING_ENABLED = 23,
 
   /**
-   * Factor for triggering a GC based on JSGC_ALLOCATION_THRESHOLD
+   * Percentage for triggering a GC based on zone->threshold.gcTriggerBytes().
+   *
+   * When the heap reaches this percentage of the allocation threshold an
+   * incremental collection is started.
    *
    * Default: ZoneAllocThresholdFactorDefault
    * Pref: None
    */
   JSGC_ALLOCATION_THRESHOLD_FACTOR = 25,
 
   /**
-   * Factor for triggering a GC based on JSGC_ALLOCATION_THRESHOLD.
-   * Used if another GC (in different zones) is already running.
+   * Percentage for triggering a GC based on zone->threshold.gcTriggerBytes().
+   *
+   * Used instead of the above percentage if if another GC (in different zones)
+   * is already running.
    *
    * Default: ZoneAllocThresholdFactorAvoidInterruptDefault
    * Pref: None
    */
   JSGC_ALLOCATION_THRESHOLD_FACTOR_AVOID_INTERRUPT = 26,
 
   /**
    * Attempt to run a minor GC in the idle time if the free space falls