includes/rts/storage/GC.h

   1 /* -----------------------------------------------------------------------------
   2  *
   3  * (c) The GHC Team, 1998-2004
   4  *
   5  * External Storage Manger Interface
   6  *
   7  * ---------------------------------------------------------------------------*/
   8
   9 #ifndef RTS_STORAGE_GC_H
  10 #define RTS_STORAGE_GC_H
  11
  12 #include <stddef.h>
  13 #include "rts/OSThreads.h"
  14
  15 /* -----------------------------------------------------------------------------
  16  * Generational GC
  17  *
  18  * We support an arbitrary number of generations, with an arbitrary number
  19  * of steps per generation.  Notes (in no particular order):
  20  *
  21  *       - all generations except the oldest should have the same
  22  *         number of steps.  Multiple steps gives objects a decent
  23  *         chance to age before being promoted, and helps ensure that
  24  *         we don't end up with too many thunks being updated in older
  25  *         generations.
  26  *
  27  *       - the oldest generation has one step.  There's no point in aging
  28  *         objects in the oldest generation.
  29  *
  30  *       - generation 0, step 0 (G0S0) is the allocation area.  It is given
  31  *         a fixed set of blocks during initialisation, and these blocks
  32  *         normally stay in G0S0.  In parallel execution, each
  33  *         Capability has its own nursery.
  34  *
  35  *       - during garbage collection, each step which is an evacuation
  36  *         destination (i.e. all steps except G0S0) is allocated a to-space.
  37  *         evacuated objects are allocated into the step's to-space until
  38  *         GC is finished, when the original step's contents may be freed
  39  *         and replaced by the to-space.
  40  *
  41  *       - the mutable-list is per-generation (not per-step).  G0 doesn't
  42  *         have one (since every garbage collection collects at least G0).
  43  *
  44  *       - block descriptors contain pointers to both the step and the
  45  *         generation that the block belongs to, for convenience.
  46  *
  47  *       - static objects are stored in per-generation lists.  See GC.c for
  48  *         details of how we collect CAFs in the generational scheme.
  49  *
  50  *       - large objects are per-step, and are promoted in the same way
  51  *         as small objects, except that we may allocate large objects into
  52  *         generation 1 initially.
  53  *
  54  * ------------------------------------------------------------------------- */
  55
  56 // A count of blocks needs to store anything up to the size of memory
  57 // divided by the block size.  The safest thing is therefore to use a
  58 // type that can store the full range of memory addresses,
  59 // ie. StgWord.  Note that we have had some tricky int overflows in a
  60 // couple of cases caused by using ints rather than longs (e.g. #5086)
  61
  62 typedef StgWord memcount;
  63
  64 typedef struct nursery_ {
  65     bdescr *       blocks;
  66     memcount       n_blocks;
  67 } nursery;
  68
  69 typedef struct generation_ {
  70     unsigned int   no;                  // generation number
  71
  72     bdescr *       blocks;              // blocks in this gen
  73     memcount       n_blocks;            // number of blocks
  74     memcount       n_words;             // number of used words
  75
  76     bdescr *       large_objects;       // large objects (doubly linked)
  77     memcount       n_large_blocks;      // no. of blocks used by large objs
  78     memcount       n_new_large_words;   // words of new large objects
  79                                         // (for allocation stats)
  80
  81     memcount       max_blocks;          // max blocks
  82
  83     StgTSO *       threads;             // threads in this gen
  84                                         // linked via global_link
  85     struct generation_ *to;             // destination gen for live objects
  86
  87     // stats information
  88     unsigned int collections;
  89     unsigned int par_collections;
  90     unsigned int failed_promotions;
  91
  92     // ------------------------------------
  93     // Fields below are used during GC only
  94
  95 #if defined(THREADED_RTS)
  96     char pad[128];                      // make sure the following is
  97                                         // on a separate cache line.
  98     SpinLock     sync;                  // lock for large_objects
  99                                         //    and scavenged_large_objects
 100 #endif
 101
 102     int          mark;                  // mark (not copy)? (old gen only)
 103     int          compact;               // compact (not sweep)? (old gen only)
 104
 105     // During GC, if we are collecting this gen, blocks and n_blocks
 106     // are copied into the following two fields.  After GC, these blocks
 107     // are freed.
 108     bdescr *     old_blocks;            // bdescr of first from-space block
 109     memcount     n_old_blocks;         // number of blocks in from-space
 110     memcount     live_estimate;         // for sweeping: estimate of live data
 111
 112     bdescr *     scavenged_large_objects;  // live large objs after GC (d-link)
 113     memcount     n_scavenged_large_blocks; // size (not count) of above
 114
 115     bdescr *     bitmap;                // bitmap for compacting collection
 116
 117     StgTSO *     old_threads;
 118 } generation;
 119
 120 extern generation * generations;
 121 extern generation * g0;
 122 extern generation * oldest_gen;
 123
 124 /* -----------------------------------------------------------------------------
 125    Generic allocation
 126
 127    StgPtr allocate(Capability *cap, nat n)
 128                                 Allocates memory from the nursery in
 129                                 the current Capability.  This can be
 130                                 done without taking a global lock,
 131                                 unlike allocate().
 132
 133    StgPtr allocatePinned(Capability *cap, nat n)
 134                                 Allocates a chunk of contiguous store
 135                                 n words long, which is at a fixed
 136                                 address (won't be moved by GC).
 137                                 Returns a pointer to the first word.
 138                                 Always succeeds.
 139
 140                                 NOTE: the GC can't in general handle
 141                                 pinned objects, so allocatePinned()
 142                                 can only be used for ByteArrays at the
 143                                 moment.
 144
 145                                 Don't forget to TICK_ALLOC_XXX(...)
 146                                 after calling allocate or
 147                                 allocatePinned, for the
 148                                 benefit of the ticky-ticky profiler.
 149
 150    -------------------------------------------------------------------------- */
 151
 152 StgPtr  allocate        ( Capability *cap, lnat n );
 153 StgPtr  allocatePinned  ( Capability *cap, lnat n );
 154
 155 /* memory allocator for executable memory */
 156 void * allocateExec(unsigned int len, void **exec_addr);
 157 void   freeExec (void *p);
 158
 159 // Used by GC checks in external .cmm code:
 160 extern nat large_alloc_lim;
 161
 162 /* -----------------------------------------------------------------------------
 163    Performing Garbage Collection
 164    -------------------------------------------------------------------------- */
 165
 166 void performGC(void);
 167 void performMajorGC(void);
 168
 169 /* -----------------------------------------------------------------------------
 170    The CAF table - used to let us revert CAFs in GHCi
 171    -------------------------------------------------------------------------- */
 172
 173 void newCAF     (StgRegTable *reg, StgClosure *);
 174 void newDynCAF  (StgRegTable *reg, StgClosure *);
 175 void revertCAFs (void);
 176
 177 // Request that all CAFs are retained indefinitely.
 178 void setKeepCAFs (void);
 179
 180 /* -----------------------------------------------------------------------------
 181    Stats
 182    -------------------------------------------------------------------------- */
 183
 184 // Returns the total number of bytes allocated since the start of the program.
 185 HsInt64 getAllocations (void);
 186
 187 /* -----------------------------------------------------------------------------
 188    This is the write barrier for MUT_VARs, a.k.a. IORefs.  A
 189    MUT_VAR_CLEAN object is not on the mutable list; a MUT_VAR_DIRTY
 190    is.  When written to, a MUT_VAR_CLEAN turns into a MUT_VAR_DIRTY
 191    and is put on the mutable list.
 192    -------------------------------------------------------------------------- */
 193
 194 void dirty_MUT_VAR(StgRegTable *reg, StgClosure *p);
 195
 196 /* set to disable CAF garbage collection in GHCi. */
 197 /* (needed when dynamic libraries are used). */
 198 extern rtsBool keepCAFs;
 199
 200 INLINE_HEADER void initBdescr(bdescr *bd, generation *gen, generation *dest)
 201 {
 202     bd->gen     = gen;
 203     bd->gen_no  = gen->no;
 204     bd->dest_no = dest->no;
 205 }
 206
 207 #endif /* RTS_STORAGE_GC_H */