js/src/doc/gc.rst

   1 SpiderMonkey garbage collector
   2 ==============================
   3
   4 The SpiderMonkey garbage collector is responsible for allocating memory
   5 representing JavaScript data structures and deallocating them when they are no
   6 longer in use. It aims to collect as much data as possible in as little time
   7 as possible. As well as JavaScript data it is also used to allocate some
   8 internal SpiderMonkey data structures.
   9
  10 The garbage collector is a hybrid tracing collector, and has the following
  11 features:
  12
  13  - :ref:`Precise <precise-gc>`
  14  - :ref:`Incremental <incremental-gc>`
  15  - :ref:`Generational <generational-gc>`
  16  - :ref:`Partially concurrent <concurrent-gc>`
  17  - :ref:`Parallel <parallel-gc>`
  18  - :ref:`Compacting <compacting-gc>`
  19  - :ref:`Partitioned heap <partitioned-heap>`
  20
  21 For an overview of garbage collection see:
  22 https://en.wikipedia.org/wiki/Tracing_garbage_collection
  23
  24 Description of features
  25 #######################
  26
  27 .. _precise-gc:
  28
  29 Precise collection
  30 ******************
  31
  32 The GC is 'precise' in that it knows the layout of allocations (which is used
  33 to determine reachable children) and also the location of all stack roots. This
  34 means it does not need to resort to conservative techniques that may cause
  35 garbage to be retained unnecessarily.
  36
  37 Knowledge of the stack is achieved with C++ wrapper classes that must be used
  38 for stack roots and handles (pointers) to them. This is enforced by the
  39 SpiderMonkey API (which operates in terms of these types) and checked by a
  40 static analysis that reports places when unrooted GC pointers can be present
  41 when a GC could occur.
  42
  43 For details of stack rooting, see: https://github.com/mozilla-spidermonkey/spidermonkey-embedding-examples/blob/esr78/docs/GC%20Rooting%20Guide.md
  44
  45 We also have a :doc:`static analysis <HazardAnalysis/index>` for detecting
  46 errors in rooting. It can be :doc:`run locally or in CI <HazardAnalysis/running>`.
  47
  48 .. _incremental-gc:
  49
  50 Incremental collection
  51 **********************
  52
  53 'Stop the world' collectors run a whole collection in one go, which can result
  54 in unacceptable pauses for users.  An incremental collector breaks its
  55 execution into a number of small slices, reducing user impact.
  56
  57 As far as possible the SpiderMonkey collector runs incrementally.  Not all
  58 parts of a collection can be performed incrementally however as there are some
  59 operations that need to complete atomically with respect to the rest of the
  60 program.
  61
  62 Currently, most of the collection is performed incrementally.  Root marking,
  63 compacting, and an initial part of sweeping are not.
  64
  65 .. _generational-gc:
  66
  67 Generational collection
  68 ***********************
  69
  70 Most real world allocations either die very quickly or live for a long
  71 time. This suggests an approach to collection where allocations are moved
  72 between 'generations' (separate heaps) depending on how long they have
  73 survived. Generations containing young allocations are fast to collect and can
  74 be collected more frequently; older generations are collected less often.
  75
  76 The SpiderMonkey collector implements a single young generation (the nursery)
  77 and a single old generation (the tenured heap). Collecting the nursery is
  78 known as a minor GC as opposed to a major GC that collects the whole heap
  79 (including the nursery).
  80
  81 .. _concurrent-gc:
  82
  83 Concurrent collection
  84 *********************
  85
  86 Many systems have more than one CPU and therefore can benefit from offloading
  87 GC work to another core.  In GC terms 'concurrent' usually refers to GC work
  88 happening while the main program continues to run.
  89
  90 The SpiderMonkey collector currently only uses concurrency in limited phases.
  91
  92 This includes most finalization work (there are some restrictions as not all
  93 finalization code can tolerate this) and some other aspects such as allocating
  94 and decommitting blocks of memory.
  95
  96 Performing marking work concurrently is currently being investigated.
  97
  98 .. _parallel-gc:
  99
 100 Parallel collection
 101 *******************
 102
 103 In GC terms 'parallel' usually means work performed in parallel while the
 104 collector is running, as opposed to the main program itself.  The SpiderMonkey
 105 collector performs work within GC slices in parallel wherever possible.
 106
 107 .. _compacting-gc:
 108
 109 Compacting collection
 110 *********************
 111
 112 The collector allocates data with the same type and size in 'arenas' (often know
 113 as slabs). After many allocations have died this can leave many arenas
 114 containing free space (external fragmentation). Compacting remedies this by
 115 moving allocations between arenas to free up as much memory as possible.
 116
 117 Compacting involves tracing the entire heap to update pointers to moved data
 118 and is not incremental so it only happens rarely, or in response to memory
 119 pressure notifications.
 120
 121 .. _partitioned-heap:
 122
 123 Partitioned heap
 124 ****************
 125
 126 The collector has the concept of 'zones' which are separate heaps which can be
 127 collected independently. Objects in different zones can refer to each other
 128 however.
 129
 130 Zones are also used to help incrementalize parts of the collection. For
 131 example, compacting is not fully incremental but can be performed one zone at
 132 a time.
 133
 134 Other documentation
 135 ###################
 136
 137 More details about the Garbage Collector (GC) can be found by looking for the
 138 `[SMDOC] Garbage Collector`_ comment in the sources.
 139
 140 .. _[SMDOC] Garbage Collector: https://searchfox.org/mozilla-central/search?q=[SMDOC]+Garbage+Collector