Bug 1725539 - p4. Document the new GC scheduling code r=smaug

Depends on D123098

Differential Revision: https://phabricator.services.mozilla.com/D123099

dom/base/CCGCScheduler.cpp

@@ -10,6 +10,103 @@
 #include "mozilla/dom/ScriptSettings.h"
 #include "nsRefreshDriver.h"
 
+/*
+ * GC Scheduling from Firefox
+ * ==========================
+ *
+ * See also GC Scheduling from SpiderMonkey's perspective here:
+ * https://searchfox.org/mozilla-central/source/js/src/gc/Scheduling.h
+ *
+ * From Firefox's perspective GCs can start in 5 different ways:
+ *
+ *  * The JS engine just starts doing a GC for its own reasons (see above).
+ *    Firefox finds out about these via a callback in nsJSEnvironment.cpp
+ *  * PokeGC()
+ *  * PokeFullGC()
+ *  * PokeShrinkingGC()
+ *  * memory-pressure GCs (via a listener in nsJSEnvironment.cpp).
+ *
+ * PokeGC
+ * ------
+ *
+ * void CCGCScheduler::PokeGC(JS::GCReason aReason, JSObject* aObj,
+ *                            TimeDuration aDelay)
+ *
+ * PokeGC provides a way for callers to say "Hey, there may be some memory
+ * associated with this object (via Zone) you can collect."  PokeGC will:
+ *  * add the zone to a set,
+ *  * set flags including what kind of GC to run (SetWantMajorGC),
+ *  * then creates the mGCRunner with a short delay.
+ *
+ * The delay can allow other calls to PokeGC to add their zones so they can
+ * be collected together.
+ *
+ * See below for what happens when mGCRunner fires.
+ *
+ * PokeFullGC
+ * ----------
+ *
+ * void CCGCScheduler::PokeFullGC()
+ *
+ * PokeFullGC will create a timer that will initiate a "full" (all zones)
+ * collection.  This is usually used after a regular collection if a full GC
+ * seems like a good idea (to collect inter-zone references).
+ *
+ * When the timer fires it will:
+ *  * set flags (SetWantMajorGC),
+ *  * start the mGCRunner with zero delay.
+ *
+ * See below for when mGCRunner fires.
+ *
+ * PokeShrinkingGC
+ * ---------------
+ *
+ * void CCGCScheduler::PokeShrinkingGC()
+ *
+ * PokeShrinkingGC is called when Firefox's user is inactive.
+ * Like PokeFullGC, PokeShrinkingGC uses a timer, but the timeout is longer
+ * which should prevent the ShrinkingGC from starting if the user only
+ * glances away for a brief time.  When the timer fires it will:
+ *
+ *  * set flags (SetWantMajorGC),
+ *  * create the mGCRunner.
+ *
+ * There is a check if the user is still inactive in GCRunnerFired), if the
+ * user has become active the shrinking GC is canceled and either a regular
+ * GC (if requested, see mWantAtLeastRegularGC) or no GC is run.
+ *
+ * When mGCRunner fires
+ * --------------------
+ *
+ * When mGCRunner fires it calls GCRunnerFired.  This starts in the
+ * WaitToMajorGC state:
+ *
+ *  * If this is a parent process it jumps to the next state
+ *  * If this is a content process it will ask the parent if now is a good
+ *      time to do a GC.  (MayGCNow)
+ *  * kill the mGCRunner
+ *  * Exit
+ *
+ * Meanwhile the parent process will queue GC requests so that not too many
+ * are running in parallel overwhelming the CPU cores (see
+ * IdleSchedulerParent).
+ *
+ * When the promise from MayGCNow is resolved it will set some
+ * state (NoteReadyForMajorGC) and restore the mGCRunner.
+ *
+ * When the mGCRunner runs a second time (or this is the parent process and
+ * which jumped over the above logic.  It will be in the StartMajorGC state.
+ * It will initiate the GC for real, usually.  If it's a shrinking GC and the
+ * user is now active again it may abort.  See GCRunnerFiredDoGC().
+ *
+ * The runner will then run the first slice of the garbage collection.
+ * Later slices are also run by the runner, the final slice kills the runner
+ * from the GC callback in nsJSEnvironment.cpp.
+ *
+ * There is additional logic in the code to handle concurrent requests of
+ * various kinds.
+ */
+
 namespace mozilla {
 
 void CCGCScheduler::NoteGCBegin() {

js/src/gc/Scheduling.h

@@ -10,6 +10,9 @@
  * GC Scheduling Overview
  * ======================
  *
+ * See also GC scheduling from Firefox's perspective here:
+ * https://searchfox.org/mozilla-central/source/dom/base/CCGCScheduler.cpp
+ *
  * Scheduling GC's in SpiderMonkey/Firefox is tremendously complicated because
  * of the large number of subtle, cross-cutting, and widely dispersed factors
  * that must be taken into account. A summary of some of the more important