Changes between Version 17 and Version 18 of Commentary/Rts/Storage/HeapObjects


Ignore:
Timestamp:
Feb 14, 2012 9:53:03 PM (3 years ago)
Author:
heisenbug
Comment:

sanitize links (use pseudo-URL syntax)

Legend:

Unmodified
Added
Removed
Modified
  • Commentary/Rts/Storage/HeapObjects

    v17 v18  
    2424== Heap Objects == 
    2525 
    26 All heap objects have the same basic layout, embodied by the type {{{StgClosure}}} in [[GhcFile(includes/rts/storage/Closures.h)]].  The diagram below shows the layout of a heap object: 
     26All heap objects have the same basic layout, embodied by the type {{{StgClosure}}} in [source:includes/rts/storage/Closures.h Closures.h].  The diagram below shows the layout of a heap object: 
    2727 
    2828[[Image(heap-object.png)]] 
    2929 
    30 A heap object always begins with a ''header'', defined by {{{StgHeader}}} in [[GhcFile(includes/rts/storage/Closures.h)]]: 
     30A heap object always begins with a ''header'', defined by {{{StgHeader}}} in [source:includes/rts/storage/Closures.h Closures.h]: 
    3131 
    3232{{{ 
     
    5656== Info Tables == 
    5757 
    58 The info table contains all the information that the runtime needs to know about the closure.  The layout of info tables is defined by {{{StgInfoTable}}} in [[GhcFile(includes/rts/storage/InfoTables.h)]].  The basic info table layout looks like this: 
     58The info table contains all the information that the runtime needs to know about the closure.  The layout of info tables is defined by {{{StgInfoTable}}} in [source:includes/rts/storage/InfoTables.h InfoTables.h].  The basic info table layout looks like this: 
    5959 
    6060[[Image(basic-itbl.png)]] 
     
    6363   
    6464 * The ''closure type'' is a constant describing the kind of closure this is (function, thunk, constructor etc.).  All 
    65    the closure types are defined in [[GhcFile(includes/rts/storage/ClosureTypes.h)]], and many of them have corresponding C struct 
    66    definitions in [[GhcFile(includes/rts/storage/Closures.h)]]. 
     65   the closure types are defined in [source:includes/rts/storage/ClosureTypes.h ClosureTypes.h], and many of them have corresponding C struct 
     66   definitions in [source:includes/rts/storage/Closures.h Closures.h]. 
    6767 
    6868 * The ''SRT bitmap'' field is used to support [wiki:Commentary/Rts/CAFs garbage collection of CAFs]. 
     
    116116The size field gives the size of the payload, and each bit of the bitmap is 1 if the corresponding word of payload contains a pointer to a live object. 
    117117 
    118 The macros {{{MK_BITMAP}}}, {{{BITMAP_SIZE}}}, and {{{BITMAP_BITS}}} in [[GhcFile(includes/rts/storage/InfoTables.h)]] provide ways to conveniently operate on small bitmaps. 
    119  
    120 '''Large bitmaps.''' If the size of the stack frame is larger than the 27 words that a small bitmap can describe, then the fallback mechanism is the large bitmap.  A large bitmap is a separate structure, containing a single word size and a multi-word bitmap: see {{{StgLargeBitmap}}} in [[GhcFile(includes/rts/storage/InfoTables.h)]]. 
     118The macros {{{MK_BITMAP}}}, {{{BITMAP_SIZE}}}, and {{{BITMAP_BITS}}} in [source:includes/rts/storage/InfoTables.h InfoTables.h] provide ways to conveniently operate on small bitmaps. 
     119 
     120'''Large bitmaps.''' If the size of the stack frame is larger than the 27 words that a small bitmap can describe, then the fallback mechanism is the large bitmap.  A large bitmap is a separate structure, containing a single word size and a multi-word bitmap: see {{{StgLargeBitmap}}} in [source:includes/rts/storage/InfoTables.h InfoTables.h]. 
    121121 
    122122 
     
    132132   scattered through the object code, and only the linker knows where. 
    133133 
    134 To find out whether a particular object is dynamic or static, use the [wiki:Commentary/Rts/Storage/HeapAlloced HEAP_ALLOCED()] macro, from [[GhcFile(rts/sm/MBlock.h)]].  This macro works by consulting a bitmap (or structured bitmap) that tells for each [wiki:Commentary/Rts/Storage#Structureofblocks megablock] of memory whether it is part of the dynamic heap or not. 
     134To find out whether a particular object is dynamic or static, use the [wiki:Commentary/Rts/Storage/HeapAlloced HEAP_ALLOCED()] macro, from [source:rts/sm/MBlock.h].  This macro works by consulting a bitmap (or structured bitmap) that tells for each [wiki:Commentary/Rts/Storage#Structureofblocks megablock] of memory whether it is part of the dynamic heap or not. 
    135135 
    136136=== Dynamic objects === 
     
    139139enough to be overwritten by a 
    140140forwarding pointer ([[ref(Forwarding Pointers)]]) during GC. 
    141 The minimum size of the payload is given by {{{MIN_PAYLOAD_SIZE}}} in [[GhcFile(includes/rts/Constants.h)]]. 
     141The minimum size of the payload is given by {{{MIN_PAYLOAD_SIZE}}} in [source:includes/rts/Constants.h]. 
    142142 
    143143=== Static objects === 
     
    154154static variant of an object has compatible layout with the dynamic 
    155155variant.  To access the static link field of a closure, use the 
    156 {{{STATIC_LINK()}}} macro from [[GhcFile(includes/rts/storage/ClosureMacros.h)]]. 
     156{{{STATIC_LINK()}}} macro from [source:includes/rts/storage/ClosureMacros.h]. 
    157157 
    158158----------- 
     
    274274There is a fixed set of pre-compiled selector thunks built into the 
    275275RTS, representing offsets from 0 to {{{MAX_SPEC_SELECTOR_THUNK}}}, 
    276 see [[GhcFile(rts/StgStdThunks.cmm)]]. 
     276see [source:rts/StgStdThunks.cmm]. 
    277277The info tables are labelled {{{__sel_n_upd_info}}} where {{{n}}} is the 
    278278offset.  Non-updating versions are also built in, with info tables 
     
    307307   this function.  The pointerhood of these words are described 
    308308   by the function's bitmap (see {{{scavenge_PAP_payload()}}} in  
    309    [[GhcFile(rts/sm/Scav.c)]] for an example of traversing a PAP). 
     309   [source:rts/sm/Scav.c] for an example of traversing a PAP). 
    310310 
    311311There is just one standard form of PAP. There is just one info table 
     
    339339Since the payload is a chunk of stack, the GC can use its normal stack-walking code to traverse it. 
    340340 
    341 {{{AP_STACK}}} closures are built by {{{raiseAsync()}}} in [[GhcFile(rts/RaiseAsync.c)]] when an [wiki:Commentary/Rts/AsyncExceptions asynchronous exception] is raised. 
     341{{{AP_STACK}}} closures are built by {{{raiseAsync()}}} in [source:rts/RaiseAsync.c] when an [wiki:Commentary/Rts/AsyncExceptions asynchronous exception] is raised. 
    342342 
    343343=== Indirections === 
     
    365365 * {{{IND_OLDGEN_PERM}}}: same as above, but for the old generation. 
    366366 * {{{IND_STATIC}}}: a static indirection, arises when we update a {{{THUNK_STATIC}}}.  A new {{{IND_STATIC}}} 
    367    is placed on the mutable list when it is created (see {{{newCaf()}}} in [[GhcFile(rts/sm/Storage.c)]]). 
     367   is placed on the mutable list when it is created (see {{{newCaf()}}} in [source:rts/sm/Storage.c]). 
    368368 
    369369=== Byte-code objects === 
     
    398398TSOs are ordinary objects that live in the heap, so we can use the existing allocation and garbage collection machinery to manage them.  This gives us one important benefit: the garbage collector can detect when a blocked thread is unreachable, and hence can never become runnable again.  When this happens, we can notify the thread by sending it the {{{BlockedIndefinitely}}} exception. 
    399399 
    400 GHC keeps stacks contiguous, there are no "stack chunk" objects.  This is simpler, but means that when growing a stack we have to copy the old contents to a larger area (see {{{threadStackOverflow()}}} in [[GhcFile(rts/Schedule.c)]]). (EZY: I'm pretty sure this is not the case anymore, see http://hackage.haskell.org/trac/ghc/blog/stack-chunks) 
    401  
    402 The TSO structure contains several fields.  For full details see [[GhcFile(includes/rts/storage/TSO.h)]].  Some of the more important fields are: 
     400GHC keeps stacks contiguous, there are no "stack chunk" objects.  This is simpler, but means that when growing a stack we have to copy the old contents to a larger area (see {{{threadStackOverflow()}}} in [source:rts/Schedule.c]). (EZY: I'm pretty sure this is not the case anymore, see http://hackage.haskell.org/trac/ghc/blog/stack-chunks) 
     401 
     402The TSO structure contains several fields.  For full details see [source:includes/rts/storage/TSO.h].  Some of the more important fields are: 
    403403 
    404404 * ''link'': field for linking TSOs together in a list.  For example, the threads blocked on an {{{MVar}}} are kept in 
    405405   a queue threaded through the link field of each TSO. 
    406  * ''global_link'': links all TSOs together; the head of this list is {{{all_threads}}} in [[GhcFile(rts/Schedule.c)]]. 
     406 * ''global_link'': links all TSOs together; the head of this list is {{{all_threads}}} in [source:rts/Schedule.c]. 
    407407 * ''what_next'': how to resume execution of this thread.  The valid values are: 
    408408   * {{{ThreadRunGhc}}}: continue by returning to the top stack frame. 
     
    412412     to its new location. 
    413413   * {{{ThreadComplete}}}: this thread has finished and can be garbage collected when it is unreachable. 
    414  * ''why_blocked'': for a blocked thread, indicates why the thread is blocked.  See [[GhcFile(includes/rts/Constants.h)]] for 
     414 * ''why_blocked'': for a blocked thread, indicates why the thread is blocked.  See [source:includes/rts/Constants.h] for 
    415415   the list of possible values. 
    416416 * ''block_info'': for a blocked thread, gives more information about the reason for blockage, eg. when blocked on an