doc/life_of_a_context.txt

   1 = The life of a context.
   2
   3 == Definitions:
   4
   5 Virtual bottom (om->context_bottom): The lowest context, address wise, in the
   6 stack that is not referenced.
   7
   8 == Description:
   9
  10 All contexts begin life in the context stack (state->om->contexts).
  11 A context is allocated at the next available position in the stack
  12 (contexts->current).
  13
  14 The context is then activated. When another method call is performed, the cpu
  15 registers are saved into it, and it is registered as the new context's sender.
  16
  17 Now there are 3 paths:
  18
  19 1. The context is ready to return, and has not been referenced. Because of the
  20    order in which contexts are allocated on the context stack, the most recent
  21    context is always on the bottom. So the space it took up is decremented from
  22    contexts->current, so the next context uses the same memory.
  23
  24 2. Same as 1, but the context was referenced. Before decrementing
  25          contexts->current, the address of the context is compared against the
  26          virtual bottom of the stack. Because the context has been referenced, it is
  27          equal to the virtual bottom, so the context stack is not decremented,
  28    leaving this context alive in the context stack.
  29
  30 3. Same as 2, but instead a context created by a method send in this context is
  31    referenced. When this context goes to return, it's address is lower than the
  32    virtual bottom, so the contexts->current is left unchanged.
  33
  34 == Phase 2
  35
  36 When the baker GC is run, the first thing it does is formalize all contexts
  37 between the true bottom and the virtual bottom. These are contexts that ones
  38 that were directly referenced, or indirectly referenced (a child was
  39 referenced).
  40
  41 The baker GC is then run. Any references to contexts in the context stack will
  42 be of contexts between the true bottom and the virtual bottom only, and when
  43 they are seen by the GC, they will be copied into the normal baker heap. This
  44 causes the sender chain to be pulled into the baker heap too.
  45
  46 The baker GC finishes. All contexts that were referenced have been pulled into
  47 the baker GC and contain all proper OOPs.
  48
  49 The context stack is walked again, this time, from virtual bottom to the top.
  50 These are all the contexts that were not referenced. The first context in the
  51 stack's sender will now point to a context in the baker heap. That context is
  52 then copied to the true bottom of the context stack. The same is done for all
  53 the rest of the contexts still in the context stack, moving them one after
  54 another closer to the bottom. This compacts the context stack, removing all
  55 contexts that have been placed into the baker heap.
  56
  57 == Phase 2.5
  58
  59 When the mark/sweep GC is run, the contexts on the context stack are walked
  60 specifically, marking the objects that they point to. This is the only extra
  61 effort that the mark/sweep GC requires of the context stack.
  62
  63 == Phase 3: Baker GC context death
  64
  65 When a context store in the baker GC returns, it's sender is set to nil (to
  66 break the chain) and it is left in the heap, to be cleaned up the next time
  67 the GC runs.
  68
  69 == heap == baker GC heap
  70
  71 Scenarios:
  72
  73 0. no contexts
  74    A. nil
  75    B. on the stack
  76
  77    B->sender is nil, and B will be on the stack, as it's the first context.
  78 1. all on stack.
  79    A. on stack
  80    B. child of A, on stack
  81
  82    on GC, B->sender is adjusted for new location of A, post compacting.
  83    if A has not been referenced, A is the ctx located in memory just before B.
  84 2. heap and stack.
  85    A. in heap
  86    B. child, on stack
  87
  88    on GC, B->sender is compacted by baker, returning new location.
  89    B is located at the virtual bottom.
  90 3. both in heap
  91    A. in heap
  92    B. child, in heap
  93
  94    on GC, B->sender is compacted by baker, returning new location.
  95 4. stack and heap
  96    A. on stack
  97    B. child, in heap (can only be BlockContext)
  98
  99          A is referenced, thus below virtual bottom. On GC of B, B->sender causes A
 100    to be copied into heap, returning new location.
 101
 102 == Assertions:
 103
 104 A context can never be in the mark_sweep GC.
 105
 106 A context referenced in the heap must be also in heap, or below virtual bottom
 107 (about to be copied)
 108
 109 A sender on the stack must be in the heap or exactly CTX_SIZE less that the
 110 current context.
 111
 112 Only the context closest to the virtual bottom may be referenced by an object
 113 in the heap.
 114
 115 If a context is on the stack and not referenced, it's class is nil.
 116
 117 If a context is on the stack and referenced, it's class is fastctx.
 118
 119 If a context is in the heap, it's class is either fastctx or blokctx.
 120