ghc/rts/Storage.h

   1 /* -----------------------------------------------------------------------------
   2  * $Id: Storage.h,v 1.29 2001/02/11 17:51:08 simonmar Exp $
   3  *
   4  * (c) The GHC Team, 1998-1999
   5  *
   6  * External Storage Manger Interface
   7  *
   8  * ---------------------------------------------------------------------------*/
   9
  10 #ifndef STORAGE_H
  11 #define STORAGE_H
  12
  13 #include "Block.h"
  14 #include "BlockAlloc.h"
  15 #include "StoragePriv.h"
  16
  17 /* -----------------------------------------------------------------------------
  18    Initialisation / De-initialisation
  19    -------------------------------------------------------------------------- */
  20
  21 extern void initStorage(void);
  22 extern void exitStorage(void);
  23
  24 /* -----------------------------------------------------------------------------
  25    Generic allocation
  26
  27    StgPtr allocate(int n)       Allocates a chunk of contiguous store
  28                                 n words long, returning a pointer to
  29                                 the first word.  Always succeeds.
  30
  31                                 Don't forget to TICK_ALLOC_XXX(...)
  32                                 after calling allocate, for the
  33                                 benefit of the ticky-ticky profiler.
  34
  35    rtsBool doYouWantToGC(void)  Returns True if the storage manager is
  36                                 ready to perform a GC, False otherwise.
  37
  38    lnat  allocated_bytes(void)  Returns the number of bytes allocated
  39                                 via allocate() since the last GC.
  40                                 Used in the reoprting of statistics.
  41
  42    SMP: allocate and doYouWantToGC can be used from STG code, they are
  43    surrounded by a mutex.
  44    -------------------------------------------------------------------------- */
  45
  46 extern StgPtr  allocate(nat n);
  47 static inline rtsBool doYouWantToGC(void)
  48 {
  49   return (alloc_blocks >= alloc_blocks_lim);
  50 }
  51 extern lnat allocated_bytes(void);
  52
  53 /* -----------------------------------------------------------------------------
  54    ExtendNursery(hp,hplim)      When hplim is reached, try to grab
  55                                 some more allocation space.  Returns
  56                                 False if the allocation space is
  57                                 exhausted, and the application should
  58                                 call GarbageCollect().
  59   -------------------------------------------------------------------------- */
  60
  61 #define ExtendNursery(hp,hplim)                 \
  62   (CurrentNursery->free = (P_)(hp)+1,           \
  63    CurrentNursery->link == NULL ? rtsFalse :    \
  64    (CurrentNursery = CurrentNursery->link,      \
  65     OpenNursery(hp,hplim),                      \
  66     rtsTrue))
  67
  68 extern void PleaseStopAllocating(void);
  69
  70 /* -----------------------------------------------------------------------------
  71    Performing Garbage Collection
  72
  73    GarbageCollect(get_roots)    Performs a garbage collection.
  74                                 'get_roots' is called to find all the
  75                                 roots that the system knows about.
  76
  77    StgClosure                   Called by get_roots on each root.
  78    MarkRoot(StgClosure *p)      Returns the new location of the root.
  79    -------------------------------------------------------------------------- */
  80
  81 extern void   GarbageCollect(void (*get_roots)(void),rtsBool force_major_gc);
  82 extern StgClosure *MarkRoot(StgClosure *p);
  83
  84 /* -----------------------------------------------------------------------------
  85    Generational garbage collection support
  86
  87    recordMutable(StgPtr p)       Informs the garbage collector that a
  88                                  previously immutable object has
  89                                  become (permanently) mutable.  Used
  90                                  by thawArray and similar.
  91
  92    updateWithIndirection(p1,p2)  Updates the object at p1 with an
  93                                  indirection pointing to p2.  This is
  94                                  normally called for objects in an old
  95                                  generation (>0) when they are updated.
  96
  97    updateWithPermIndirection(p1,p2)  As above but uses a permanent indir.
  98
  99    -------------------------------------------------------------------------- */
 100
 101 /*
 102  * Storage manager mutex
 103  */
 104 #ifdef SMP
 105 extern pthread_mutex_t sm_mutex;
 106 #endif
 107
 108 /* ToDo: shouldn't recordMutable and recordOldToNewPtrs acquire some
 109  * kind of lock in the SMP case?
 110  */
 111 static inline void
 112 recordMutable(StgMutClosure *p)
 113 {
 114   bdescr *bd;
 115
 116 #ifdef SMP
 117   ASSERT(p->header.info == &stg_WHITEHOLE_info || closure_MUTABLE(p));
 118 #else
 119   ASSERT(closure_MUTABLE(p));
 120 #endif
 121
 122   bd = Bdescr((P_)p);
 123   if (bd->gen->no > 0) {
 124     p->mut_link = bd->gen->mut_list;
 125     bd->gen->mut_list = p;
 126   }
 127 }
 128
 129 static inline void
 130 recordOldToNewPtrs(StgMutClosure *p)
 131 {
 132   bdescr *bd;
 133
 134   bd = Bdescr((P_)p);
 135   if (bd->gen->no > 0) {
 136     p->mut_link = bd->gen->mut_once_list;
 137     bd->gen->mut_once_list = p;
 138   }
 139 }
 140
 141 #ifndef DEBUG
 142 #define updateWithIndirection(info, p1, p2)                             \
 143   {                                                                     \
 144     bdescr *bd;                                                         \
 145                                                                         \
 146     bd = Bdescr((P_)p1);                                                \
 147     if (bd->gen->no == 0) {                                             \
 148       ((StgInd *)p1)->indirectee = p2;                                  \
 149       SET_INFO(p1,&stg_IND_info);                                       \
 150       TICK_UPD_NEW_IND();                                               \
 151     } else {                                                            \
 152       ((StgIndOldGen *)p1)->indirectee = p2;                            \
 153       if (info != &stg_BLACKHOLE_BQ_info) {                             \
 154         ACQUIRE_LOCK(&sm_mutex);                                        \
 155         ((StgIndOldGen *)p1)->mut_link = bd->gen->mut_once_list;        \
 156         bd->gen->mut_once_list = (StgMutClosure *)p1;                   \
 157         RELEASE_LOCK(&sm_mutex);                                        \
 158       }                                                                 \
 159       SET_INFO(p1,&stg_IND_OLDGEN_info);                                \
 160       TICK_UPD_OLD_IND();                                               \
 161     }                                                                   \
 162   }
 163 #else
 164
 165 /* In the DEBUG case, we also zero out the slop of the old closure,
 166  * so that the sanity checker can tell where the next closure is.
 167  */
 168 #define updateWithIndirection(info, p1, p2)                             \
 169   {                                                                     \
 170     bdescr *bd;                                                         \
 171                                                                         \
 172     bd = Bdescr((P_)p1);                                                \
 173     if (bd->gen->no == 0) {                                             \
 174       ((StgInd *)p1)->indirectee = p2;                                  \
 175       SET_INFO(p1,&stg_IND_info);                                       \
 176       TICK_UPD_NEW_IND();                                               \
 177     } else {                                                            \
 178       if (info != &stg_BLACKHOLE_BQ_info) {                             \
 179         {                                                               \
 180           StgInfoTable *inf = get_itbl(p1);                             \
 181           nat np = inf->layout.payload.ptrs,                            \
 182               nw = inf->layout.payload.nptrs, i;                        \
 183           if (inf->type != THUNK_SELECTOR) {                            \
 184              for (i = np; i < np + nw; i++) {                           \
 185                 ((StgClosure *)p1)->payload[i] = 0;                     \
 186              }                                                          \
 187           }                                                             \
 188         }                                                               \
 189         ACQUIRE_LOCK(&sm_mutex);                                        \
 190         ((StgIndOldGen *)p1)->mut_link = bd->gen->mut_once_list;        \
 191         bd->gen->mut_once_list = (StgMutClosure *)p1;                   \
 192         RELEASE_LOCK(&sm_mutex);                                        \
 193       }                                                                 \
 194       ((StgIndOldGen *)p1)->indirectee = p2;                            \
 195       SET_INFO(p1,&stg_IND_OLDGEN_info);                                \
 196       TICK_UPD_OLD_IND();                                               \
 197     }                                                                   \
 198   }
 199 #endif
 200
 201 /* Static objects all live in the oldest generation
 202  */
 203 #define updateWithStaticIndirection(info, p1, p2)                       \
 204   {                                                                     \
 205     ASSERT( ((StgMutClosure*)p1)->mut_link == NULL );                   \
 206                                                                         \
 207     ACQUIRE_LOCK(&sm_mutex);                                            \
 208     ((StgMutClosure *)p1)->mut_link = oldest_gen->mut_once_list;        \
 209     oldest_gen->mut_once_list = (StgMutClosure *)p1;                    \
 210     RELEASE_LOCK(&sm_mutex);                                            \
 211                                                                         \
 212     ((StgInd *)p1)->indirectee = p2;                                    \
 213     SET_INFO((StgInd *)p1, &stg_IND_STATIC_info);                       \
 214     TICK_UPD_STATIC_IND();                                              \
 215   }
 216
 217 #if defined(TICKY_TICKY) || defined(PROFILING)
 218 static inline void
 219 updateWithPermIndirection(const StgInfoTable *info, StgClosure *p1, StgClosure *p2)
 220 {
 221   bdescr *bd;
 222
 223   bd = Bdescr((P_)p1);
 224   if (bd->gen->no == 0) {
 225     ((StgInd *)p1)->indirectee = p2;
 226     SET_INFO(p1,&stg_IND_PERM_info);
 227     TICK_UPD_NEW_PERM_IND(p1);
 228   } else {
 229     ((StgIndOldGen *)p1)->indirectee = p2;
 230     if (info != &stg_BLACKHOLE_BQ_info) {
 231       ACQUIRE_LOCK(&sm_mutex);
 232       ((StgIndOldGen *)p1)->mut_link = bd->gen->mut_once_list;
 233       bd->gen->mut_once_list = (StgMutClosure *)p1;
 234       RELEASE_LOCK(&sm_mutex);
 235     }
 236     SET_INFO(p1,&stg_IND_OLDGEN_PERM_info);
 237     TICK_UPD_OLD_PERM_IND();
 238   }
 239 }
 240 #endif
 241
 242 /* -----------------------------------------------------------------------------
 243    The CAF table - used to let us revert CAFs
 244    -------------------------------------------------------------------------- */
 245
 246 #if defined(DEBUG)
 247 void printMutOnceList(generation *gen);
 248 void printMutableList(generation *gen);
 249 #endif DEBUG
 250
 251 /* --------------------------------------------------------------------------
 252                       Address space layout macros
 253    --------------------------------------------------------------------------
 254
 255    Here are the assumptions GHC makes about address space layout.
 256    Broadly, it thinks there are three sections:
 257
 258      CODE    Read-only.  Contains code and read-only data (such as
 259                 info tables)
 260              Also called "text"
 261
 262      DATA    Read-write data.  Contains static closures (and on some
 263                 architectures, info tables too)
 264
 265      HEAP    Dynamically-allocated closures
 266
 267      USER    None of the above.  The only way USER things arise right
 268              now is when GHCi allocates a constructor info table, which
 269              it does by mallocing them.
 270
 271    Three macros identify these three areas:
 272      IS_CODE(p), IS_DATA(p), HEAP_ALLOCED(p)
 273
 274    HEAP_ALLOCED is called FOR EVERY SINGLE CLOSURE during GC.
 275    It needs to be FAST.
 276
 277    Implementation of HEAP_ALLOCED
 278    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 279    Concerning HEAP, most of the time (certainly under [Static] and [GHCi],
 280    we ensure that the heap is allocated above some fixed address HEAP_BASE
 281    (defined in MBlock.h).  In this case we set TEXT_BEFORE_HEAP, and we
 282    get a nice fast test.
 283
 284    Sometimes we can't be quite sure.  For example in Windows, we can't
 285    fix where our heap address space comes from.  In this case we un-set
 286    TEXT_BEFORE_HEAP. That makes it more expensive to test whether a pointer
 287    comes from the HEAP section, because we need to look at the allocator's
 288    address maps (see HEAP_ALLOCED macro)
 289
 290    Implementation of CODE and DATA
 291    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 292    Concerning CODE and DATA, there are three main regimes:
 293
 294      [Static] Totally      The segments are contiguous, and laid out
 295      statically linked     exactly as above
 296
 297      [GHCi] Static,        GHCi may load new modules, but it knows the
 298      except for GHCi       address map, so for any given address it can
 299                            still tell which section it belongs to
 300
 301      [DLL] OS-supported    Chunks of CODE and DATA may be mixed in
 302      dynamic loading       the address space, and we can't tell how
 303
 304
 305    For the [Static] case, we assume memory is laid out like this
 306    (in order of increasing addresses)
 307
 308        Start of memory
 309            CODE section
 310        TEXT_SECTION_END_MARKER   (usually _etext)
 311            DATA section
 312        DATA_SECTION_END_MARKER   (usually _end)
 313            USER section
 314        HEAP_BASE
 315            HEAP section
 316
 317    For the [GHCi] case, we have to consult GHCi's dynamic linker's
 318    address maps, which is done by macros
 319          is_dynamically_loaded_code_or_rodata_ptr
 320          is_dynamically_loaded_code_or_rwdata_ptr
 321
 322    For the [DLL] case, IS_CODE and IS_DATA are really not usable at all.
 323  */
 324
 325
 326 #undef TEXT_BEFORE_HEAP
 327 #ifndef mingw32_TARGET_OS
 328 #define TEXT_BEFORE_HEAP 1
 329 #endif
 330
 331 extern void* TEXT_SECTION_END_MARKER_DECL;
 332 extern void* DATA_SECTION_END_MARKER_DECL;
 333
 334 /* Take into account code sections in dynamically loaded object files. */
 335 #define IS_CODE_PTR(p) (  ((P_)(p) < (P_)&TEXT_SECTION_END_MARKER) \
 336                        || is_dynamically_loaded_code_or_rodata_ptr((char *)p) )
 337 #define IS_DATA_PTR(p) ( ((P_)(p) >= (P_)&TEXT_SECTION_END_MARKER && \
 338                           (P_)(p) < (P_)&DATA_SECTION_END_MARKER) \
 339                        || is_dynamically_loaded_rwdata_ptr((char *)p) )
 340 #define IS_USER_PTR(p) ( ((P_)(p) >= (P_)&DATA_SECTION_END_MARKER) \
 341                        && is_not_dynamically_loaded_ptr((char *)p) )
 342
 343 /* The HEAP_ALLOCED test below is called FOR EVERY SINGLE CLOSURE
 344  * during GC.  It needs to be FAST.
 345  *
 346  * BEWARE: when we're dynamically loading code (for GHCi), make sure
 347  * that we don't load any code above HEAP_BASE, or this test won't work.
 348  */
 349 #ifdef TEXT_BEFORE_HEAP
 350 # define HEAP_ALLOCED(x)  ((StgPtr)(x) >= (StgPtr)(HEAP_BASE))
 351 #else
 352 extern int is_heap_alloced(const void* x);
 353 # define HEAP_ALLOCED(x)  (is_heap_alloced(x))
 354 #endif
 355
 356
 357 /* --------------------------------------------------------------------------
 358    Macros for distinguishing data pointers from code pointers
 359    --------------------------------------------------------------------------
 360
 361   Specification
 362   ~~~~~~~~~~~~~
 363   The garbage collector needs to make some critical distinctions between pointers.
 364   In particular we need
 365
 366      LOOKS_LIKE_GHC_INFO(p)          p points to an info table
 367
 368   For both of these macros, p is
 369       *either* a pointer to a closure (static or heap allocated)
 370       *or* a return address on the (Haskell) stack
 371
 372   (Return addresses are in fact info-pointers, so that the Haskell stack
 373   looks very like a chunk of heap.)
 374
 375   The garbage collector uses LOOKS_LIKE_GHC_INFO when walking the stack, as it
 376   walks over the "pending arguments" on its way to the next return address.
 377   It is called moderately often, but not as often as HEAP_ALLOCED
 378
 379   ToDo: LOOKS_LIKE_GHC_INFO(p) does not return True when p points to a
 380   constructor info table allocated by GHCi.  We should really rename
 381   LOOKS_LIKE_GHC_INFO to LOOKS_LIKE_GHC_RETURN_INFO.
 382
 383   Implementation
 384   ~~~~~~~~~~~~~~
 385   LOOKS_LIKE_GHC_INFO is more complicated because of the need to distinguish
 386   between static closures and info tables.  It's a known portability problem.
 387   We have three approaches:
 388
 389   Plan A: Address-space partitioning.
 390     Keep info tables in the (single, contiguous) text segment:    IS_CODE_PTR(p)
 391     and static closures in the (single, contiguous) data segment: IS_DATA_PTR(p)
 392
 393   Plan A can fail for two reasons:
 394     * In many environments (eg. dynamic loading),
 395       text and data aren't in a single contiguous range.
 396     * When we compile through vanilla C (no mangling) we sometimes
 397       can't guaranteee to put info tables in the text section.  This
 398       happens eg. on MacOS where the C compiler refuses to put const
 399       data in the text section if it has any code pointers in it
 400       (which info tables do *only* when we're compiling without
 401       TABLES_NEXT_TO_CODE).
 402
 403   Hence, Plan B: (compile-via-C-with-mangling, or native code generation)
 404     Put a zero word before each static closure.
 405     When compiling to native code, or via C-with-mangling, info tables
 406     are laid out "backwards" from the address specified in the info pointer
 407     (the entry code goes forward from the info pointer).  Hence, the word
 408     before the one referenced the info pointer is part of the info table,
 409     and is guaranteed non-zero.
 410
 411     For reasons nobody seems to fully understand, the statically-allocated tables
 412     of INTLIKE and CHARLIKE closures can't have this zero word, so we
 413     have to test separately for them.
 414
 415     Plan B fails altogether for the compile-through-vanilla-C route, because
 416     info tables aren't laid out backwards.
 417
 418
 419   Hence, Plan C: (unregisterised, compile-through-vanilla-C route only)
 420     If we didn't manage to get info tables into the text section, then
 421     we can distinguish between a static closure pointer and an info
 422     pointer as follows:  the first word of an info table is a code pointer,
 423     and therefore in text space, whereas the first word of a closure pointer
 424     is an info pointer, and therefore not.  Shazam!
 425 */
 426
 427
 428 /* When working with Win32 DLLs, static closures are identified by
 429    being prefixed with a zero word. This is needed so that we can
 430    distinguish between pointers to static closures and (reversed!)
 431    info tables.
 432
 433    This 'scheme' breaks down for closure tables such as CHARLIKE,
 434    so we catch these separately.
 435
 436    LOOKS_LIKE_STATIC_CLOSURE()
 437        - discriminates between static closures and info tbls
 438          (needed by LOOKS_LIKE_GHC_INFO() below - [Win32 DLLs only.])
 439    LOOKS_LIKE_STATIC()
 440        - distinguishes between static and heap allocated data.
 441  */
 442 #if defined(ENABLE_WIN32_DLL_SUPPORT)
 443             /* definitely do not enable for mingw DietHEP */
 444 #define LOOKS_LIKE_STATIC(r) (!(HEAP_ALLOCED(r)))
 445
 446 /* Tiresome predicates needed to check for pointers into the closure tables */
 447 #define IS_CHARLIKE_CLOSURE(p) \
 448     ( (P_)(p) >= (P_)stg_CHARLIKE_closure && \
 449       (char*)(p) <= ((char*)stg_CHARLIKE_closure + \
 450                      (MAX_CHARLIKE-MIN_CHARLIKE) * sizeof(StgIntCharlikeClosure)) )
 451 #define IS_INTLIKE_CLOSURE(p) \
 452     ( (P_)(p) >= (P_)stg_INTLIKE_closure && \
 453       (char*)(p) <= ((char*)stg_INTLIKE_closure + \
 454                      (MAX_INTLIKE-MIN_INTLIKE) * sizeof(StgIntCharlikeClosure)) )
 455
 456 #define LOOKS_LIKE_STATIC_CLOSURE(r) (((*(((unsigned long *)(r))-1)) == 0) || IS_CHARLIKE_CLOSURE(r) || IS_INTLIKE_CLOSURE(r))
 457 #else
 458 #define LOOKS_LIKE_STATIC(r) IS_DATA_PTR(r)
 459 #define LOOKS_LIKE_STATIC_CLOSURE(r) IS_DATA_PTR(r)
 460 #endif
 461
 462
 463 /* -----------------------------------------------------------------------------
 464    Macros for distinguishing infotables from closures.
 465
 466    You'd think it'd be easy to tell an info pointer from a closure pointer:
 467    closures live on the heap and infotables are in read only memory.  Right?
 468    Wrong!  Static closures live in read only memory and Hugs allocates
 469    infotables for constructors on the (writable) C heap.
 470    -------------------------------------------------------------------------- */
 471
 472 /* not accurate by any means, but stops the assertions failing... */
 473 /* TODO TODO TODO TODO TODO TODO TODO TODO TODO TODO TODO TODO */
 474 #define IS_HUGS_CONSTR_INFO(info)  IS_USER_PTR(info)
 475
 476 /* LOOKS_LIKE_GHC_INFO is called moderately often during GC, but
 477  * Certainly not as often as HEAP_ALLOCED.
 478  */
 479 #ifdef TEXT_BEFORE_HEAP /* needed for mingw DietHEP */
 480 # define LOOKS_LIKE_GHC_INFO(info) IS_CODE_PTR(info)
 481 #else
 482 # define LOOKS_LIKE_GHC_INFO(info) (!HEAP_ALLOCED(info) \
 483                                     && !LOOKS_LIKE_STATIC_CLOSURE(info))
 484 #endif
 485
 486
 487 /* -----------------------------------------------------------------------------
 488    Macros for calculating how big a closure will be (used during allocation)
 489    -------------------------------------------------------------------------- */
 490
 491 /* ToDo: replace unsigned int by nat.  The only fly in the ointment is that
 492  * nat comes from Rts.h which many folk dont include.  Sigh!
 493  */
 494 static __inline__ StgOffset AP_sizeW    ( unsigned int n_args )
 495 { return sizeofW(StgAP_UPD) + n_args; }
 496
 497 static __inline__ StgOffset PAP_sizeW   ( unsigned int n_args )
 498 { return sizeofW(StgPAP)    + n_args; }
 499
 500 static __inline__ StgOffset CONSTR_sizeW( unsigned int p, unsigned int np )
 501 { return sizeofW(StgHeader) + p + np; }
 502
 503 static __inline__ StgOffset THUNK_SELECTOR_sizeW ( void )
 504 { return sizeofW(StgHeader) + MIN_UPD_SIZE; }
 505
 506 static __inline__ StgOffset BLACKHOLE_sizeW ( void )
 507 { return sizeofW(StgHeader) + MIN_UPD_SIZE; }
 508
 509 /* --------------------------------------------------------------------------
 510  * Sizes of closures
 511  * ------------------------------------------------------------------------*/
 512
 513 static __inline__ StgOffset sizeW_fromITBL( const StgInfoTable* itbl )
 514 { return sizeofW(StgClosure)
 515        + sizeofW(StgPtr)  * itbl->layout.payload.ptrs
 516        + sizeofW(StgWord) * itbl->layout.payload.nptrs; }
 517
 518 static __inline__ StgOffset pap_sizeW( StgPAP* x )
 519 { return PAP_sizeW(x->n_args); }
 520
 521 static __inline__ StgOffset arr_words_sizeW( StgArrWords* x )
 522 { return sizeofW(StgArrWords) + x->words; }
 523
 524 static __inline__ StgOffset mut_arr_ptrs_sizeW( StgMutArrPtrs* x )
 525 { return sizeofW(StgMutArrPtrs) + x->ptrs; }
 526
 527 static __inline__ StgWord tso_sizeW ( StgTSO *tso )
 528 { return TSO_STRUCT_SIZEW + tso->stack_size; }
 529
 530 #endif STORAGE_H
 531