ghc/rts/Storage.h

   1 /* -----------------------------------------------------------------------------
   2  * $Id: Storage.h,v 1.30 2001/03/02 14:36:16 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     ASSERT( p1 != p2 );                                                 \
 173     bd = Bdescr((P_)p1);                                                \
 174     if (bd->gen->no == 0) {                                             \
 175       ((StgInd *)p1)->indirectee = p2;                                  \
 176       SET_INFO(p1,&stg_IND_info);                                       \
 177       TICK_UPD_NEW_IND();                                               \
 178     } else {                                                            \
 179       if (info != &stg_BLACKHOLE_BQ_info) {                             \
 180         {                                                               \
 181           StgInfoTable *inf = get_itbl(p1);                             \
 182           nat np = inf->layout.payload.ptrs,                            \
 183               nw = inf->layout.payload.nptrs, i;                        \
 184           if (inf->type != THUNK_SELECTOR) {                            \
 185              for (i = np; i < np + nw; i++) {                           \
 186                 ((StgClosure *)p1)->payload[i] = 0;                     \
 187              }                                                          \
 188           }                                                             \
 189         }                                                               \
 190         ACQUIRE_LOCK(&sm_mutex);                                        \
 191         ((StgIndOldGen *)p1)->mut_link = bd->gen->mut_once_list;        \
 192         bd->gen->mut_once_list = (StgMutClosure *)p1;                   \
 193         RELEASE_LOCK(&sm_mutex);                                        \
 194       }                                                                 \
 195       ((StgIndOldGen *)p1)->indirectee = p2;                            \
 196       SET_INFO(p1,&stg_IND_OLDGEN_info);                                \
 197       TICK_UPD_OLD_IND();                                               \
 198     }                                                                   \
 199   }
 200 #endif
 201
 202 /* Static objects all live in the oldest generation
 203  */
 204 #define updateWithStaticIndirection(info, p1, p2)                       \
 205   {                                                                     \
 206     ASSERT( p1 != p2 );                                                 \
 207     ASSERT( ((StgMutClosure*)p1)->mut_link == NULL );                   \
 208                                                                         \
 209     ACQUIRE_LOCK(&sm_mutex);                                            \
 210     ((StgMutClosure *)p1)->mut_link = oldest_gen->mut_once_list;        \
 211     oldest_gen->mut_once_list = (StgMutClosure *)p1;                    \
 212     RELEASE_LOCK(&sm_mutex);                                            \
 213                                                                         \
 214     ((StgInd *)p1)->indirectee = p2;                                    \
 215     SET_INFO((StgInd *)p1, &stg_IND_STATIC_info);                       \
 216     TICK_UPD_STATIC_IND();                                              \
 217   }
 218
 219 #if defined(TICKY_TICKY) || defined(PROFILING)
 220 static inline void
 221 updateWithPermIndirection(const StgInfoTable *info, StgClosure *p1, StgClosure *p2)
 222 {
 223   bdescr *bd;
 224
 225   ASSERT( p1 != p2 );                                                   \
 226   bd = Bdescr((P_)p1);
 227   if (bd->gen->no == 0) {
 228     ((StgInd *)p1)->indirectee = p2;
 229     SET_INFO(p1,&stg_IND_PERM_info);
 230     TICK_UPD_NEW_PERM_IND(p1);
 231   } else {
 232     ((StgIndOldGen *)p1)->indirectee = p2;
 233     if (info != &stg_BLACKHOLE_BQ_info) {
 234       ACQUIRE_LOCK(&sm_mutex);
 235       ((StgIndOldGen *)p1)->mut_link = bd->gen->mut_once_list;
 236       bd->gen->mut_once_list = (StgMutClosure *)p1;
 237       RELEASE_LOCK(&sm_mutex);
 238     }
 239     SET_INFO(p1,&stg_IND_OLDGEN_PERM_info);
 240     TICK_UPD_OLD_PERM_IND();
 241   }
 242 }
 243 #endif
 244
 245 /* -----------------------------------------------------------------------------
 246    The CAF table - used to let us revert CAFs
 247    -------------------------------------------------------------------------- */
 248
 249 #if defined(DEBUG)
 250 void printMutOnceList(generation *gen);
 251 void printMutableList(generation *gen);
 252 #endif DEBUG
 253
 254 /* --------------------------------------------------------------------------
 255                       Address space layout macros
 256    --------------------------------------------------------------------------
 257
 258    Here are the assumptions GHC makes about address space layout.
 259    Broadly, it thinks there are three sections:
 260
 261      CODE    Read-only.  Contains code and read-only data (such as
 262                 info tables)
 263              Also called "text"
 264
 265      DATA    Read-write data.  Contains static closures (and on some
 266                 architectures, info tables too)
 267
 268      HEAP    Dynamically-allocated closures
 269
 270      USER    None of the above.  The only way USER things arise right
 271              now is when GHCi allocates a constructor info table, which
 272              it does by mallocing them.
 273
 274    Three macros identify these three areas:
 275      IS_CODE(p), IS_DATA(p), HEAP_ALLOCED(p)
 276
 277    HEAP_ALLOCED is called FOR EVERY SINGLE CLOSURE during GC.
 278    It needs to be FAST.
 279
 280    Implementation of HEAP_ALLOCED
 281    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 282    Concerning HEAP, most of the time (certainly under [Static] and [GHCi],
 283    we ensure that the heap is allocated above some fixed address HEAP_BASE
 284    (defined in MBlock.h).  In this case we set TEXT_BEFORE_HEAP, and we
 285    get a nice fast test.
 286
 287    Sometimes we can't be quite sure.  For example in Windows, we can't
 288    fix where our heap address space comes from.  In this case we un-set
 289    TEXT_BEFORE_HEAP. That makes it more expensive to test whether a pointer
 290    comes from the HEAP section, because we need to look at the allocator's
 291    address maps (see HEAP_ALLOCED macro)
 292
 293    Implementation of CODE and DATA
 294    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 295    Concerning CODE and DATA, there are three main regimes:
 296
 297      [Static] Totally      The segments are contiguous, and laid out
 298      statically linked     exactly as above
 299
 300      [GHCi] Static,        GHCi may load new modules, but it knows the
 301      except for GHCi       address map, so for any given address it can
 302                            still tell which section it belongs to
 303
 304      [DLL] OS-supported    Chunks of CODE and DATA may be mixed in
 305      dynamic loading       the address space, and we can't tell how
 306
 307
 308    For the [Static] case, we assume memory is laid out like this
 309    (in order of increasing addresses)
 310
 311        Start of memory
 312            CODE section
 313        TEXT_SECTION_END_MARKER   (usually _etext)
 314            DATA section
 315        DATA_SECTION_END_MARKER   (usually _end)
 316            USER section
 317        HEAP_BASE
 318            HEAP section
 319
 320    For the [GHCi] case, we have to consult GHCi's dynamic linker's
 321    address maps, which is done by macros
 322          is_dynamically_loaded_code_or_rodata_ptr
 323          is_dynamically_loaded_code_or_rwdata_ptr
 324
 325    For the [DLL] case, IS_CODE and IS_DATA are really not usable at all.
 326  */
 327
 328
 329 #undef TEXT_BEFORE_HEAP
 330 #ifndef mingw32_TARGET_OS
 331 #define TEXT_BEFORE_HEAP 1
 332 #endif
 333
 334 extern void* TEXT_SECTION_END_MARKER_DECL;
 335 extern void* DATA_SECTION_END_MARKER_DECL;
 336
 337 /* Take into account code sections in dynamically loaded object files. */
 338 #define IS_CODE_PTR(p) (  ((P_)(p) < (P_)&TEXT_SECTION_END_MARKER) \
 339                        || is_dynamically_loaded_code_or_rodata_ptr((char *)p) )
 340 #define IS_DATA_PTR(p) ( ((P_)(p) >= (P_)&TEXT_SECTION_END_MARKER && \
 341                           (P_)(p) < (P_)&DATA_SECTION_END_MARKER) \
 342                        || is_dynamically_loaded_rwdata_ptr((char *)p) )
 343 #define IS_USER_PTR(p) ( ((P_)(p) >= (P_)&DATA_SECTION_END_MARKER) \
 344                        && is_not_dynamically_loaded_ptr((char *)p) )
 345
 346 /* The HEAP_ALLOCED test below is called FOR EVERY SINGLE CLOSURE
 347  * during GC.  It needs to be FAST.
 348  *
 349  * BEWARE: when we're dynamically loading code (for GHCi), make sure
 350  * that we don't load any code above HEAP_BASE, or this test won't work.
 351  */
 352 #ifdef TEXT_BEFORE_HEAP
 353 # define HEAP_ALLOCED(x)  ((StgPtr)(x) >= (StgPtr)(HEAP_BASE))
 354 #else
 355 extern int is_heap_alloced(const void* x);
 356 # define HEAP_ALLOCED(x)  (is_heap_alloced(x))
 357 #endif
 358
 359
 360 /* --------------------------------------------------------------------------
 361    Macros for distinguishing data pointers from code pointers
 362    --------------------------------------------------------------------------
 363
 364   Specification
 365   ~~~~~~~~~~~~~
 366   The garbage collector needs to make some critical distinctions between pointers.
 367   In particular we need
 368
 369      LOOKS_LIKE_GHC_INFO(p)          p points to an info table
 370
 371   For both of these macros, p is
 372       *either* a pointer to a closure (static or heap allocated)
 373       *or* a return address on the (Haskell) stack
 374
 375   (Return addresses are in fact info-pointers, so that the Haskell stack
 376   looks very like a chunk of heap.)
 377
 378   The garbage collector uses LOOKS_LIKE_GHC_INFO when walking the stack, as it
 379   walks over the "pending arguments" on its way to the next return address.
 380   It is called moderately often, but not as often as HEAP_ALLOCED
 381
 382   ToDo: LOOKS_LIKE_GHC_INFO(p) does not return True when p points to a
 383   constructor info table allocated by GHCi.  We should really rename
 384   LOOKS_LIKE_GHC_INFO to LOOKS_LIKE_GHC_RETURN_INFO.
 385
 386   Implementation
 387   ~~~~~~~~~~~~~~
 388   LOOKS_LIKE_GHC_INFO is more complicated because of the need to distinguish
 389   between static closures and info tables.  It's a known portability problem.
 390   We have three approaches:
 391
 392   Plan A: Address-space partitioning.
 393     Keep info tables in the (single, contiguous) text segment:    IS_CODE_PTR(p)
 394     and static closures in the (single, contiguous) data segment: IS_DATA_PTR(p)
 395
 396   Plan A can fail for two reasons:
 397     * In many environments (eg. dynamic loading),
 398       text and data aren't in a single contiguous range.
 399     * When we compile through vanilla C (no mangling) we sometimes
 400       can't guaranteee to put info tables in the text section.  This
 401       happens eg. on MacOS where the C compiler refuses to put const
 402       data in the text section if it has any code pointers in it
 403       (which info tables do *only* when we're compiling without
 404       TABLES_NEXT_TO_CODE).
 405
 406   Hence, Plan B: (compile-via-C-with-mangling, or native code generation)
 407     Put a zero word before each static closure.
 408     When compiling to native code, or via C-with-mangling, info tables
 409     are laid out "backwards" from the address specified in the info pointer
 410     (the entry code goes forward from the info pointer).  Hence, the word
 411     before the one referenced the info pointer is part of the info table,
 412     and is guaranteed non-zero.
 413
 414     For reasons nobody seems to fully understand, the statically-allocated tables
 415     of INTLIKE and CHARLIKE closures can't have this zero word, so we
 416     have to test separately for them.
 417
 418     Plan B fails altogether for the compile-through-vanilla-C route, because
 419     info tables aren't laid out backwards.
 420
 421
 422   Hence, Plan C: (unregisterised, compile-through-vanilla-C route only)
 423     If we didn't manage to get info tables into the text section, then
 424     we can distinguish between a static closure pointer and an info
 425     pointer as follows:  the first word of an info table is a code pointer,
 426     and therefore in text space, whereas the first word of a closure pointer
 427     is an info pointer, and therefore not.  Shazam!
 428 */
 429
 430
 431 /* When working with Win32 DLLs, static closures are identified by
 432    being prefixed with a zero word. This is needed so that we can
 433    distinguish between pointers to static closures and (reversed!)
 434    info tables.
 435
 436    This 'scheme' breaks down for closure tables such as CHARLIKE,
 437    so we catch these separately.
 438
 439    LOOKS_LIKE_STATIC_CLOSURE()
 440        - discriminates between static closures and info tbls
 441          (needed by LOOKS_LIKE_GHC_INFO() below - [Win32 DLLs only.])
 442    LOOKS_LIKE_STATIC()
 443        - distinguishes between static and heap allocated data.
 444  */
 445 #if defined(ENABLE_WIN32_DLL_SUPPORT)
 446             /* definitely do not enable for mingw DietHEP */
 447 #define LOOKS_LIKE_STATIC(r) (!(HEAP_ALLOCED(r)))
 448
 449 /* Tiresome predicates needed to check for pointers into the closure tables */
 450 #define IS_CHARLIKE_CLOSURE(p) \
 451     ( (P_)(p) >= (P_)stg_CHARLIKE_closure && \
 452       (char*)(p) <= ((char*)stg_CHARLIKE_closure + \
 453                      (MAX_CHARLIKE-MIN_CHARLIKE) * sizeof(StgIntCharlikeClosure)) )
 454 #define IS_INTLIKE_CLOSURE(p) \
 455     ( (P_)(p) >= (P_)stg_INTLIKE_closure && \
 456       (char*)(p) <= ((char*)stg_INTLIKE_closure + \
 457                      (MAX_INTLIKE-MIN_INTLIKE) * sizeof(StgIntCharlikeClosure)) )
 458
 459 #define LOOKS_LIKE_STATIC_CLOSURE(r) (((*(((unsigned long *)(r))-1)) == 0) || IS_CHARLIKE_CLOSURE(r) || IS_INTLIKE_CLOSURE(r))
 460 #else
 461 #define LOOKS_LIKE_STATIC(r) IS_DATA_PTR(r)
 462 #define LOOKS_LIKE_STATIC_CLOSURE(r) IS_DATA_PTR(r)
 463 #endif
 464
 465
 466 /* -----------------------------------------------------------------------------
 467    Macros for distinguishing infotables from closures.
 468
 469    You'd think it'd be easy to tell an info pointer from a closure pointer:
 470    closures live on the heap and infotables are in read only memory.  Right?
 471    Wrong!  Static closures live in read only memory and Hugs allocates
 472    infotables for constructors on the (writable) C heap.
 473    -------------------------------------------------------------------------- */
 474
 475 /* not accurate by any means, but stops the assertions failing... */
 476 /* TODO TODO TODO TODO TODO TODO TODO TODO TODO TODO TODO TODO */
 477 #define IS_HUGS_CONSTR_INFO(info)  IS_USER_PTR(info)
 478
 479 /* LOOKS_LIKE_GHC_INFO is called moderately often during GC, but
 480  * Certainly not as often as HEAP_ALLOCED.
 481  */
 482 #ifdef TEXT_BEFORE_HEAP /* needed for mingw DietHEP */
 483 # define LOOKS_LIKE_GHC_INFO(info) IS_CODE_PTR(info)
 484 #else
 485 # define LOOKS_LIKE_GHC_INFO(info) (!HEAP_ALLOCED(info) \
 486                                     && !LOOKS_LIKE_STATIC_CLOSURE(info))
 487 #endif
 488
 489
 490 /* -----------------------------------------------------------------------------
 491    Macros for calculating how big a closure will be (used during allocation)
 492    -------------------------------------------------------------------------- */
 493
 494 /* ToDo: replace unsigned int by nat.  The only fly in the ointment is that
 495  * nat comes from Rts.h which many folk dont include.  Sigh!
 496  */
 497 static __inline__ StgOffset AP_sizeW    ( unsigned int n_args )
 498 { return sizeofW(StgAP_UPD) + n_args; }
 499
 500 static __inline__ StgOffset PAP_sizeW   ( unsigned int n_args )
 501 { return sizeofW(StgPAP)    + n_args; }
 502
 503 static __inline__ StgOffset CONSTR_sizeW( unsigned int p, unsigned int np )
 504 { return sizeofW(StgHeader) + p + np; }
 505
 506 static __inline__ StgOffset THUNK_SELECTOR_sizeW ( void )
 507 { return sizeofW(StgHeader) + MIN_UPD_SIZE; }
 508
 509 static __inline__ StgOffset BLACKHOLE_sizeW ( void )
 510 { return sizeofW(StgHeader) + MIN_UPD_SIZE; }
 511
 512 /* --------------------------------------------------------------------------
 513  * Sizes of closures
 514  * ------------------------------------------------------------------------*/
 515
 516 static __inline__ StgOffset sizeW_fromITBL( const StgInfoTable* itbl )
 517 { return sizeofW(StgClosure)
 518        + sizeofW(StgPtr)  * itbl->layout.payload.ptrs
 519        + sizeofW(StgWord) * itbl->layout.payload.nptrs; }
 520
 521 static __inline__ StgOffset pap_sizeW( StgPAP* x )
 522 { return PAP_sizeW(x->n_args); }
 523
 524 static __inline__ StgOffset arr_words_sizeW( StgArrWords* x )
 525 { return sizeofW(StgArrWords) + x->words; }
 526
 527 static __inline__ StgOffset mut_arr_ptrs_sizeW( StgMutArrPtrs* x )
 528 { return sizeofW(StgMutArrPtrs) + x->ptrs; }
 529
 530 static __inline__ StgWord tso_sizeW ( StgTSO *tso )
 531 { return TSO_STRUCT_SIZEW + tso->stack_size; }
 532
 533 #endif STORAGE_H
 534