[project @ 2001-02-08 14:36:21 by simonmar]
[ghc-hetmet.git] / ghc / rts / Storage.h
1 /* -----------------------------------------------------------------------------
2  * $Id: Storage.h,v 1.26 2001/02/08 14:36:21 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 /* Temporary measure to ensure we retain all the dynamically-loaded CAFs */
85 #ifdef GHCI
86 extern void markCafs( void );
87 #endif
88
89 /* -----------------------------------------------------------------------------
90    Generational garbage collection support
91
92    recordMutable(StgPtr p)       Informs the garbage collector that a
93                                  previously immutable object has
94                                  become (permanently) mutable.  Used
95                                  by thawArray and similar.
96
97    updateWithIndirection(p1,p2)  Updates the object at p1 with an
98                                  indirection pointing to p2.  This is
99                                  normally called for objects in an old
100                                  generation (>0) when they are updated.
101
102    updateWithPermIndirection(p1,p2)  As above but uses a permanent indir.
103
104    -------------------------------------------------------------------------- */
105
106 /*
107  * Storage manager mutex
108  */
109 #ifdef SMP
110 extern pthread_mutex_t sm_mutex;
111 #endif
112
113 /* ToDo: shouldn't recordMutable and recordOldToNewPtrs acquire some
114  * kind of lock in the SMP case?
115  */
116 static inline void
117 recordMutable(StgMutClosure *p)
118 {
119   bdescr *bd;
120
121 #ifdef SMP
122   ASSERT(p->header.info == &stg_WHITEHOLE_info || closure_MUTABLE(p));
123 #else
124   ASSERT(closure_MUTABLE(p));
125 #endif
126
127   bd = Bdescr((P_)p);
128   if (bd->gen->no > 0) {
129     p->mut_link = bd->gen->mut_list;
130     bd->gen->mut_list = p;
131   }
132 }
133
134 static inline void
135 recordOldToNewPtrs(StgMutClosure *p)
136 {
137   bdescr *bd;
138   
139   bd = Bdescr((P_)p);
140   if (bd->gen->no > 0) {
141     p->mut_link = bd->gen->mut_once_list;
142     bd->gen->mut_once_list = p;
143   }
144 }
145
146 #ifndef DEBUG
147 #define updateWithIndirection(info, p1, p2)                             \
148   {                                                                     \
149     bdescr *bd;                                                         \
150                                                                         \
151     bd = Bdescr((P_)p1);                                                \
152     if (bd->gen->no == 0) {                                             \
153       ((StgInd *)p1)->indirectee = p2;                                  \
154       SET_INFO(p1,&stg_IND_info);                                       \
155       TICK_UPD_NEW_IND();                                               \
156     } else {                                                            \
157       ((StgIndOldGen *)p1)->indirectee = p2;                            \
158       if (info != &stg_BLACKHOLE_BQ_info) {                             \
159         ACQUIRE_LOCK(&sm_mutex);                                        \
160         ((StgIndOldGen *)p1)->mut_link = bd->gen->mut_once_list;        \
161         bd->gen->mut_once_list = (StgMutClosure *)p1;                   \
162         RELEASE_LOCK(&sm_mutex);                                        \
163       }                                                                 \
164       SET_INFO(p1,&stg_IND_OLDGEN_info);                                \
165       TICK_UPD_OLD_IND();                                               \
166     }                                                                   \
167   }
168 #else
169
170 /* In the DEBUG case, we also zero out the slop of the old closure,
171  * so that the sanity checker can tell where the next closure is.
172  */
173 #define updateWithIndirection(info, p1, p2)                             \
174   {                                                                     \
175     bdescr *bd;                                                         \
176                                                                         \
177     bd = Bdescr((P_)p1);                                                \
178     if (bd->gen->no == 0) {                                             \
179       ((StgInd *)p1)->indirectee = p2;                                  \
180       SET_INFO(p1,&stg_IND_info);                                       \
181       TICK_UPD_NEW_IND();                                               \
182     } else {                                                            \
183       if (info != &stg_BLACKHOLE_BQ_info) {                             \
184         {                                                               \
185           StgInfoTable *inf = get_itbl(p1);                             \
186           nat np = inf->layout.payload.ptrs,                            \
187               nw = inf->layout.payload.nptrs, i;                        \
188           for (i = np; i < np + nw; i++) {                              \
189              ((StgClosure *)p1)->payload[i] = 0;                        \
190           }                                                             \
191         }                                                               \
192         ACQUIRE_LOCK(&sm_mutex);                                        \
193         ((StgIndOldGen *)p1)->mut_link = bd->gen->mut_once_list;        \
194         bd->gen->mut_once_list = (StgMutClosure *)p1;                   \
195         RELEASE_LOCK(&sm_mutex);                                        \
196       }                                                                 \
197       ((StgIndOldGen *)p1)->indirectee = p2;                            \
198       SET_INFO(p1,&stg_IND_OLDGEN_info);                                \
199       TICK_UPD_OLD_IND();                                               \
200     }                                                                   \
201   }
202 #endif
203
204 /* Static objects all live in the oldest generation
205  */
206 #define updateWithStaticIndirection(info, p1, p2)                       \
207   {                                                                     \
208     ASSERT( ((StgMutClosure*)p1)->mut_link == NULL );                   \
209                                                                         \
210     ACQUIRE_LOCK(&sm_mutex);                                            \
211     ((StgMutClosure *)p1)->mut_link = oldest_gen->mut_once_list;        \
212     oldest_gen->mut_once_list = (StgMutClosure *)p1;                    \
213     RELEASE_LOCK(&sm_mutex);                                            \
214                                                                         \
215     ((StgInd *)p1)->indirectee = p2;                                    \
216     SET_INFO((StgInd *)p1, &stg_IND_STATIC_info);                       \
217     TICK_UPD_STATIC_IND();                                              \
218   }
219
220 #if defined(TICKY_TICKY) || defined(PROFILING)
221 static inline void
222 updateWithPermIndirection(const StgInfoTable *info, StgClosure *p1, StgClosure *p2) 
223 {
224   bdescr *bd;
225
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(INTERPRETER)
250 typedef struct StgCAFTabEntry_ {
251     StgClosure*   closure;
252     StgInfoTable* origItbl;
253 } StgCAFTabEntry;
254
255 extern void addToECafTable ( StgClosure* closure, StgInfoTable* origItbl );
256 extern void clearECafTable ( void );
257
258 extern StgCAF*         ecafList;
259 extern StgCAFTabEntry* ecafTable;
260 extern StgInt          usedECafTable;
261 extern StgInt          sizeECafTable;
262 #endif
263
264 #if defined(DEBUG)
265 void printMutOnceList(generation *gen);
266 void printMutableList(generation *gen);
267 #endif DEBUG
268
269 /* --------------------------------------------------------------------------
270                       Address space layout macros
271    --------------------------------------------------------------------------
272
273    Here are the assumptions GHC makes about address space layout.
274    Broadly, it thinks there are three sections:
275
276      CODE    Read-only.  Contains code and read-only data (such as
277                 info tables)
278              Also called "text"
279
280      DATA    Read-write data.  Contains static closures (and on some
281                 architectures, info tables too)
282
283      HEAP    Dynamically-allocated closures
284
285      USER    None of the above.  The only way USER things arise right 
286              now is when GHCi allocates a constructor info table, which
287              it does by mallocing them.
288
289    Three macros identify these three areas:
290      IS_CODE(p), IS_DATA(p), HEAP_ALLOCED(p)
291
292    HEAP_ALLOCED is called FOR EVERY SINGLE CLOSURE during GC.
293    It needs to be FAST.
294
295    Implementation of HEAP_ALLOCED
296    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
297    Concerning HEAP, most of the time (certainly under [Static] and [GHCi],
298    we ensure that the heap is allocated above some fixed address HEAP_BASE
299    (defined in MBlock.h).  In this case we set TEXT_BEFORE_HEAP, and we
300    get a nice fast test.
301
302    Sometimes we can't be quite sure.  For example in Windows, we can't 
303    fix where our heap address space comes from.  In this case we un-set 
304    TEXT_BEFORE_HEAP. That makes it more expensive to test whether a pointer
305    comes from the HEAP section, because we need to look at the allocator's
306    address maps (see HEAP_ALLOCED macro)
307
308    Implementation of CODE and DATA
309    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
310    Concerning CODE and DATA, there are three main regimes:
311
312      [Static] Totally      The segments are contiguous, and laid out 
313      statically linked     exactly as above
314
315      [GHCi] Static,        GHCi may load new modules, but it knows the
316      except for GHCi       address map, so for any given address it can
317                            still tell which section it belongs to
318
319      [DLL] OS-supported    Chunks of CODE and DATA may be mixed in 
320      dynamic loading       the address space, and we can't tell how
321
322
323    For the [Static] case, we assume memory is laid out like this
324    (in order of increasing addresses)
325
326        Start of memory
327            CODE section
328        TEXT_SECTION_END_MARKER   (usually _etext)
329            DATA section
330        DATA_SECTION_END_MARKER   (usually _end)
331            USER section
332        HEAP_BASE
333            HEAP section
334
335    For the [GHCi] case, we have to consult GHCi's dynamic linker's
336    address maps, which is done by macros
337          is_dynamically_loaded_code_or_rodata_ptr
338          is_dynamically_loaded_code_or_rwdata_ptr
339
340    For the [DLL] case, IS_CODE and IS_DATA are really not usable at all.
341  */
342
343
344 #undef TEXT_BEFORE_HEAP
345 #ifndef mingw32_TARGET_OS
346 #define TEXT_BEFORE_HEAP 1
347 #endif
348
349 extern void* TEXT_SECTION_END_MARKER_DECL;
350 extern void* DATA_SECTION_END_MARKER_DECL;
351
352 #if defined(INTERPRETER) || defined(GHCI)
353 /* Take into account code sections in dynamically loaded object files. */
354 #define IS_CODE_PTR(p) (  ((P_)(p) < (P_)&TEXT_SECTION_END_MARKER) \
355                        || is_dynamically_loaded_code_or_rodata_ptr((char *)p) )
356 #define IS_DATA_PTR(p) ( ((P_)(p) >= (P_)&TEXT_SECTION_END_MARKER && \
357                           (P_)(p) < (P_)&DATA_SECTION_END_MARKER) \
358                        || is_dynamically_loaded_rwdata_ptr((char *)p) )
359 #define IS_USER_PTR(p) ( ((P_)(p) >= (P_)&DATA_SECTION_END_MARKER) \
360                        && is_not_dynamically_loaded_ptr((char *)p) )
361 #else
362 #define IS_CODE_PTR(p) ((P_)(p) < (P_)&TEXT_SECTION_END_MARKER)
363 #define IS_DATA_PTR(p) ((P_)(p) >= (P_)&TEXT_SECTION_END_MARKER && (P_)(p) < (P_)&DATA_SECTION_END_MARKER)
364 #define IS_USER_PTR(p) ((P_)(p) >= (P_)&DATA_SECTION_END_MARKER)
365 #endif
366
367 /* The HEAP_ALLOCED test below is called FOR EVERY SINGLE CLOSURE
368  * during GC.  It needs to be FAST.
369  *
370  * BEWARE: when we're dynamically loading code (for GHCi), make sure
371  * that we don't load any code above HEAP_BASE, or this test won't work.
372  */
373 #ifdef TEXT_BEFORE_HEAP
374 # define HEAP_ALLOCED(x)  ((StgPtr)(x) >= (StgPtr)(HEAP_BASE))
375 #else
376 extern int is_heap_alloced(const void* x);
377 # define HEAP_ALLOCED(x)  (is_heap_alloced(x))
378 #endif
379
380
381 /* --------------------------------------------------------------------------
382    Macros for distinguishing data pointers from code pointers
383    --------------------------------------------------------------------------
384
385   Specification
386   ~~~~~~~~~~~~~
387   The garbage collector needs to make some critical distinctions between pointers.
388   In particular we need
389  
390      LOOKS_LIKE_GHC_INFO(p)          p points to an info table
391
392   For both of these macros, p is
393       *either* a pointer to a closure (static or heap allocated)
394       *or* a return address on the (Haskell) stack
395
396   (Return addresses are in fact info-pointers, so that the Haskell stack
397   looks very like a chunk of heap.)
398
399   The garbage collector uses LOOKS_LIKE_GHC_INFO when walking the stack, as it
400   walks over the "pending arguments" on its way to the next return address.
401   It is called moderately often, but not as often as HEAP_ALLOCED
402
403   ToDo: LOOKS_LIKE_GHC_INFO(p) does not return True when p points to a
404   constructor info table allocated by GHCi.  We should really rename 
405   LOOKS_LIKE_GHC_INFO to LOOKS_LIKE_GHC_RETURN_INFO.
406
407   Implementation
408   ~~~~~~~~~~~~~~
409   LOOKS_LIKE_GHC_INFO is more complicated because of the need to distinguish 
410   between static closures and info tables.  It's a known portability problem.
411   We have three approaches:
412
413   Plan A: Address-space partitioning.  
414     Keep info tables in the (single, contiguous) text segment:    IS_CODE_PTR(p)
415     and static closures in the (single, contiguous) data segment: IS_DATA_PTR(p)
416
417   Plan A can fail for two reasons:
418     * In many environments (eg. dynamic loading),
419       text and data aren't in a single contiguous range.  
420     * When we compile through vanilla C (no mangling) we sometimes
421       can't guaranteee to put info tables in the text section.  This
422       happens eg. on MacOS where the C compiler refuses to put const
423       data in the text section if it has any code pointers in it
424       (which info tables do *only* when we're compiling without
425       TABLES_NEXT_TO_CODE).
426     
427   Hence, Plan B: (compile-via-C-with-mangling, or native code generation)
428     Put a zero word before each static closure.
429     When compiling to native code, or via C-with-mangling, info tables
430     are laid out "backwards" from the address specified in the info pointer
431     (the entry code goes forward from the info pointer).  Hence, the word
432     before the one referenced the info pointer is part of the info table,
433     and is guaranteed non-zero.
434
435     For reasons nobody seems to fully understand, the statically-allocated tables
436     of INTLIKE and CHARLIKE closures can't have this zero word, so we
437     have to test separately for them.
438
439     Plan B fails altogether for the compile-through-vanilla-C route, because
440     info tables aren't laid out backwards.
441
442
443   Hence, Plan C: (unregisterised, compile-through-vanilla-C route only)
444     If we didn't manage to get info tables into the text section, then
445     we can distinguish between a static closure pointer and an info
446     pointer as follows:  the first word of an info table is a code pointer,
447     and therefore in text space, whereas the first word of a closure pointer
448     is an info pointer, and therefore not.  Shazam!
449 */
450
451
452 /* When working with Win32 DLLs, static closures are identified by
453    being prefixed with a zero word. This is needed so that we can
454    distinguish between pointers to static closures and (reversed!)
455    info tables.
456
457    This 'scheme' breaks down for closure tables such as CHARLIKE,
458    so we catch these separately.
459   
460    LOOKS_LIKE_STATIC_CLOSURE() 
461        - discriminates between static closures and info tbls
462          (needed by LOOKS_LIKE_GHC_INFO() below - [Win32 DLLs only.])
463    LOOKS_LIKE_STATIC() 
464        - distinguishes between static and heap allocated data.
465  */
466 #if defined(ENABLE_WIN32_DLL_SUPPORT) && !defined(INTERPRETER)
467             /* definitely do not enable for mingw DietHEP */
468 #define LOOKS_LIKE_STATIC(r) (!(HEAP_ALLOCED(r)))
469
470 /* Tiresome predicates needed to check for pointers into the closure tables */
471 #define IS_CHARLIKE_CLOSURE(p) \
472     ( (P_)(p) >= (P_)stg_CHARLIKE_closure && \
473       (char*)(p) <= ((char*)stg_CHARLIKE_closure + \
474                      (MAX_CHARLIKE-MIN_CHARLIKE) * sizeof(StgIntCharlikeClosure)) )
475 #define IS_INTLIKE_CLOSURE(p) \
476     ( (P_)(p) >= (P_)stg_INTLIKE_closure && \
477       (char*)(p) <= ((char*)stg_INTLIKE_closure + \
478                      (MAX_INTLIKE-MIN_INTLIKE) * sizeof(StgIntCharlikeClosure)) )
479
480 #define LOOKS_LIKE_STATIC_CLOSURE(r) (((*(((unsigned long *)(r))-1)) == 0) || IS_CHARLIKE_CLOSURE(r) || IS_INTLIKE_CLOSURE(r))
481 #else
482 #define LOOKS_LIKE_STATIC(r) IS_DATA_PTR(r)
483 #define LOOKS_LIKE_STATIC_CLOSURE(r) IS_DATA_PTR(r)
484 #endif
485
486
487 /* -----------------------------------------------------------------------------
488    Macros for distinguishing infotables from closures.
489    
490    You'd think it'd be easy to tell an info pointer from a closure pointer:
491    closures live on the heap and infotables are in read only memory.  Right?
492    Wrong!  Static closures live in read only memory and Hugs allocates
493    infotables for constructors on the (writable) C heap.
494    -------------------------------------------------------------------------- */
495
496 #ifdef INTERPRETER
497 #  ifdef USE_MINIINTERPRETER
498      /* yoiks: one of the dreaded pointer equality tests */
499 #    define IS_HUGS_CONSTR_INFO(info) \
500             (((StgInfoTable *)(info))->entry == (StgFunPtr)&Hugs_CONSTR_entry)
501 #  else
502 #    define IS_HUGS_CONSTR_INFO(info) 0 /* ToDo: more than mildly bogus */
503 #  endif
504 #elif GHCI
505    /* not accurate by any means, but stops the assertions failing... */
506 #  define IS_HUGS_CONSTR_INFO(info)  IS_USER_PTR(info)
507 #else
508 #  define IS_HUGS_CONSTR_INFO(info) 0 /* ToDo: more than mildly bogus */
509 #endif
510
511 /* LOOKS_LIKE_GHC_INFO is called moderately often during GC, but
512  * Certainly not as often as HEAP_ALLOCED.
513  */
514 #ifdef TEXT_BEFORE_HEAP /* needed for mingw DietHEP */
515 # define LOOKS_LIKE_GHC_INFO(info) IS_CODE_PTR(info)
516 #else
517 # define LOOKS_LIKE_GHC_INFO(info) (!HEAP_ALLOCED(info) \
518                                     && !LOOKS_LIKE_STATIC_CLOSURE(info))
519 #endif
520
521
522 /* -----------------------------------------------------------------------------
523    Macros for calculating how big a closure will be (used during allocation)
524    -------------------------------------------------------------------------- */
525
526 /* ToDo: replace unsigned int by nat.  The only fly in the ointment is that
527  * nat comes from Rts.h which many folk dont include.  Sigh!
528  */
529 static __inline__ StgOffset AP_sizeW    ( unsigned int n_args )              
530 { return sizeofW(StgAP_UPD) + n_args; }
531
532 static __inline__ StgOffset PAP_sizeW   ( unsigned int n_args )              
533 { return sizeofW(StgPAP)    + n_args; }
534
535 static __inline__ StgOffset CONSTR_sizeW( unsigned int p, unsigned int np )  
536 { return sizeofW(StgHeader) + p + np; }
537
538 static __inline__ StgOffset THUNK_SELECTOR_sizeW ( void )                    
539 { return sizeofW(StgHeader) + MIN_UPD_SIZE; }
540
541 static __inline__ StgOffset BLACKHOLE_sizeW ( void )                    
542 { return sizeofW(StgHeader) + MIN_UPD_SIZE; }
543
544 /* --------------------------------------------------------------------------
545  * Sizes of closures
546  * ------------------------------------------------------------------------*/
547
548 static __inline__ StgOffset sizeW_fromITBL( const StgInfoTable* itbl ) 
549 { return sizeofW(StgClosure) 
550        + sizeofW(StgPtr)  * itbl->layout.payload.ptrs 
551        + sizeofW(StgWord) * itbl->layout.payload.nptrs; }
552
553 static __inline__ StgOffset pap_sizeW( StgPAP* x )
554 { return PAP_sizeW(x->n_args); }
555
556 static __inline__ StgOffset arr_words_sizeW( StgArrWords* x )
557 { return sizeofW(StgArrWords) + x->words; }
558
559 static __inline__ StgOffset mut_arr_ptrs_sizeW( StgMutArrPtrs* x )
560 { return sizeofW(StgMutArrPtrs) + x->ptrs; }
561
562 static __inline__ StgWord tso_sizeW ( StgTSO *tso )
563 { return TSO_STRUCT_SIZEW + tso->stack_size; }
564
565 #endif STORAGE_H
566