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   { $table
  22     { { $slot "word" } { "The " { $link word } " to call." } }
  23     { { $slot "in-d" } { "Sequence of input variables to the call. The items are ordered from top to bottom of the stack." } }
  24     { { $slot "out-d" } { "Output values of the call." } }
  25     { { $slot "method" } { "If the called word is generic and inlined here, then 'method' contains the inlined " { $link quotation } "." } }
  26     { { $slot "body" } { "If the called word is generic and inlined, then 'body' is a sequence of SSA nodes built from the inlined method." } }
  27     { { $slot "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." } }
  28   }
  29 } ;
  30
  31 HELP: #call-recursive
  32 { $class-description "In a " { $link #recursive } " block of the SSA tree, this node represents a call back to the beginning of the block." }
  33 { $see-also #recursive } ;
  34
  35 HELP: #declare
  36 { $class-description "SSA tree node emitted when " { $link declare } " declarations are encountered. It has the following slots:"
  37   { $table
  38     { { $slot "declaration" } { { $link assoc } " that maps values to the types they are declared as." } }
  39   }
  40 } ;
  41
  42 HELP: #enter-recursive
  43 { $class-description "This node works is placed first in the 'child' " { $link sequence } " for " { $link #recursive } " nodes and works like a header for it." }
  44 { $see-also #recursive #return-recursive } ;
  45
  46 HELP: #if
  47 { $class-description "SSA tree node that implements conditional branching. It has the following slots:"
  48   { $table
  49     { { $slot "children" }
  50       { "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." }
  51     }
  52   }
  53 } ;
  54
  55 HELP: #introduce
  56 { $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:"
  57   { $table
  58     { { $slot "out-d" } { "Array of values of the parameters being introduced." } }
  59   }
  60 } ;
  61
  62 HELP: #phi
  63 { $class-description "#phi is a SSA tree node type that unifies two branches in an " { $link #if } "." } ;
  64
  65 HELP: #push
  66 { $class-description "SSA tree node that puts a literal value on the stack. It has the following slots:"
  67   { $table
  68     { { $slot "out-d" } { "A one item array containing the " { $link <value> } " of the literal being pushed." } }
  69   }
  70 }
  71 { $notes "A " { $link quotation } " is also a literal." } ;
  72
  73 HELP: #recursive
  74 { $class-description "Instruction which encodes a loop. It has the following slots:"
  75   { $table
  76     { { $slot "child" } { "A sequence of nodes representing the body of the loop." } }
  77     { { $slot "loop?" } { "If " { $link t } ", the recursion is implemented using a jump, otherwise as a call back to the word." } }
  78   }
  79 }
  80 { $see-also inline-recursive-word } ;
  81
  82 HELP: #shuffle
  83 { $class-description "SSA tree node that represents a stack shuffling operation such as " { $link swap } ". It has the following slots:"
  84   { $table
  85     { { $slot "mapping" } { "An " { $link assoc } " that shows how the shuffle output values (the keys) correspond to their inputs (the values)." } }
  86   }
  87 } ;
  88
  89 HELP: node,
  90 { $values { "node" node } }
  91 { $description "Emits a node to the " { $link stack-visitor } " variable." } ;
  92
  93 ARTICLE: "compiler.tree" "High-level optimizer operating on lexical tree SSA IR"
  94 "Node types:"
  95 { $subsections
  96   #call
  97   #declare
  98   #shuffle
  99 }
 100 "Nodes for control flow:"
 101 { $subsections
 102   #call-recursive
 103   #enter-recursive
 104   #recursive
 105   #return-recursive
 106   #terminate
 107 }
 108 "Nodes for alien ffi:"
 109 { $subsections
 110   #alien-node
 111   #alien-invoke
 112   #alien-indirect
 113   #alien-assembly
 114   #alien-callback
 115 }
 116 "Nodes for branching:"
 117 { $subsections
 118   #dispatch
 119   #if
 120   #phi
 121 } ;
 122
 123 ABOUT: "compiler.tree"