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