basis/compiler/tree/tree-docs.factor

   1 USING: alien assocs help.markup help.syntax kernel kernel.private
   2 quotations sequences stack-checker.alien stack-checker.inlining
   3 stack-checker.values stack-checker.visitor words ;
   4 IN: compiler.tree
   5
   6 HELP: node
   7 { $class-description "Base class for all SSA tree nodes. The node is an " { $link identity-tuple } " which means that two different node instances with the same attributes are not equal." } ;
   8
   9 HELP: #alien-node
  10 { $class-description "Base class for alien nodes. Its " { $snippet "params" } " slot holds an instance of the " { $link alien-node-params } " class." } ;
  11
  12 HELP: #alien-invoke
  13 { $class-description "SSA tree node that calls a function in a dynamically linked library." }
  14 { $see-also alien-invoke } ;
  15
  16 HELP: #alien-callback
  17 { $class-description "SSA tree node that constructs an alien callback. It is not a subclass of " { $link #alien-node } "." } ;
  18
  19 HELP: #call
  20 { $class-description "SSA tree node that calls a word. It has the following slots:"
  21   { $slots
  22     { "word" { "The " { $link word } " to call." } }
  23     { "in-d" { "Sequence of input variables to the call. The items are ordered from top to bottom of the stack." } }
  24     { "out-d" { "Output values of the call." } }
  25     { "body" { "If the called word is generic and inlined, then 'body' is a sequence of SSA nodes built from the inlined method." } }
  26     { "method" { "If the called word is generic and inlined here, then 'method' contains the inlined " { $link quotation } "." } }
  27     { "class" { "a class" } }
  28     { "info" { "If the called word is generic and inlined, then the info slot contains an assoc of value infos for the body of the inlined generic. It is set during the propagation pass of the optimizer." } }
  29   }
  30 } ;
  31
  32 HELP: #call-recursive
  33 { $class-description "In a " { $link #recursive } " block of the SSA tree, this node represents a call back to the beginning of the block." }
  34 { $see-also #recursive } ;
  35
  36 HELP: #declare
  37 { $class-description "SSA tree node emitted when " { $link declare } " declarations are encountered. It has the following slots:"
  38   { $slots
  39     { "declaration" { { $link assoc } " that maps values to the types they are declared as." } }
  40   }
  41 } ;
  42
  43 HELP: #enter-recursive
  44 { $class-description "This node works is placed first in the 'child' " { $link sequence } " for " { $link #recursive } " nodes and works like a header for it." }
  45 { $see-also #recursive #return-recursive } ;
  46
  47 HELP: #if
  48 { $class-description "SSA tree node that implements conditional branching. It has the following slots:"
  49   { $slots
  50     { "children"
  51       { "A two item " { $link sequence } ". The first item holds the instructions executed if the condition is true and the second those that are executed if it is not true." }
  52     }
  53   }
  54 } ;
  55
  56 HELP: #introduce
  57 { $class-description "SSA tree node that puts an input value from the \"outside\" on the stack. It is used to \"introduce\" data stack parameter whenever they are needed. It has the following slots:"
  58   { $slots
  59     { "out-d" { "Array of values of the parameters being introduced." } }
  60   }
  61 } ;
  62
  63 HELP: #phi
  64 { $class-description "#phi is a SSA tree node type that unifies two branches in an " { $link #if } "." } ;
  65
  66 HELP: #push
  67 { $class-description "SSA tree node that puts a literal value on the stack. It has the following slots:"
  68   { $slots
  69     { "literal" { "A literal data value." } }
  70     { "out-d" { "A one item array containing the " { $link <value> } " of the literal being pushed." } }
  71   }
  72 }
  73 { $notes "A " { $link quotation } " is also a literal." } ;
  74
  75 HELP: #recursive
  76 { $class-description "Instruction which encodes a loop. It has the following slots:"
  77   { $slots
  78     { "child" { "A sequence of nodes representing the body of the loop." } }
  79     { "loop?" { "If " { $link t } ", the recursion is implemented using a jump, otherwise as a call back to the word." } }
  80   }
  81 }
  82 { $see-also inline-recursive-word } ;
  83
  84 HELP: #shuffle
  85 { $class-description "SSA tree node that represents a stack shuffling operation such as " { $link swap } ". It has the following slots:"
  86   { $slots
  87     { "mapping" { "An " { $link assoc } " that shows how the shuffle output values (the keys) correspond to their inputs (the values)." } }
  88     { "in-d" { "Sequence of datastack input variables." } }
  89     { "out-d" { "Output datastack values." } }
  90     { "in-r" { "Sequence of retainstack inputs." } }
  91     { "out-r" { "Output retainstack values." } }
  92   }
  93 } ;
  94
  95 HELP: node,
  96 { $values { "node" node } }
  97 { $description "Emits a node to the " { $link stack-visitor } " variable." } ;
  98
  99 ARTICLE: "compiler.tree" "High-level optimizer operating on lexical tree SSA IR"
 100 "The base node type:"
 101 { $subsections
 102   node
 103 }
 104 "Nodes for data:"
 105 { $subsections
 106   #declare
 107   #introduce
 108   #shuffle
 109   #renaming
 110   #copy
 111   #push
 112 }
 113 "Nodes for control flow:"
 114 { $subsections
 115   #call
 116   #call-recursive
 117   #enter-recursive
 118   #recursive
 119   #return
 120   #return-recursive
 121   #terminate
 122 }
 123 "Nodes for alien ffi:"
 124 { $subsections
 125   #alien-node
 126   #alien-invoke
 127   #alien-indirect
 128   #alien-assembly
 129   #alien-callback
 130 }
 131 "Nodes for branching:"
 132 { $subsections
 133   #branch
 134   #if
 135   #dispatch
 136   #phi
 137 } ;
 138
 139 ABOUT: "compiler.tree"