basis/generator/generator-docs.factor

   1 USING: help.markup help.syntax words debugger generator.fixup
   2 generator.registers quotations kernel vectors arrays effects
   3 sequences ;
   4 IN: generator
   5
   6 ARTICLE: "generator" "Compiled code generator"
   7 "Most of the words in the " { $vocab-link "generator" } " vocabulary are internal to the compiler and user code has no reason to call them."
   8 $nl
   9 "Debugging information can be enabled or disabled; this hook is used by " { $link "tools.deploy" } ":"
  10 { $subsection compiled-stack-traces? }
  11 "Assembler intrinsics can be defined for low-level optimization:"
  12 { $subsection define-intrinsic }
  13 { $subsection define-intrinsics }
  14 { $subsection define-if-intrinsic }
  15 { $subsection define-if-intrinsics }
  16 "The main entry point into the code generator:"
  17 { $subsection generate } ;
  18
  19 ABOUT: "generator"
  20
  21 HELP: compiled
  22 { $var-description "During compilation, holds a hashtable mapping words to 5-element arrays holding compiled code." } ;
  23
  24 HELP: compiling-word
  25 { $var-description "The word currently being compiled, set by " { $link with-generator } "." } ;
  26
  27 HELP: compiling-label
  28 { $var-description "The label currently being compiled, set by " { $link with-generator } "." } ;
  29
  30 HELP: compiled-stack-traces?
  31 { $values { "?" "a boolean" } }
  32 { $description "Iftrue, compiled code blocks will retain what word they were compiled from. This information is used by " { $link :c } " to display call stack traces after an error is thrown from compiled code. This is on by default; the deployment tool switches it off to save some space in the deployed image." } ;
  33
  34 HELP: literal-table
  35 { $var-description "Holds a vector of literal objects referenced from the currently compiling word. If " { $link compiled-stack-traces? } " is on, " { $link begin-compiling } " ensures that the first entry is the word being compiled." } ;
  36
  37 HELP: begin-compiling
  38 { $values { "word" word } { "label" word } }
  39 { $description "Prepares to generate machine code for a word." } ;
  40
  41 HELP: with-generator
  42 { $values { "node" "a dataflow node" } { "word" word } { "label" word } { "quot" "a quotation with stack effect " { $snippet "( node -- )" } } }
  43 { $description "Generates machine code for " { $snippet "label" } " by applying the quotation to the dataflow node." } ;
  44
  45 HELP: generate-node
  46 { $values { "node" "a dataflow node" } { "next" "a dataflow node" } }
  47 { $contract "Generates machine code for a dataflow node, and outputs the next node to generate machine code for." }
  48 { $notes "This word can only be called from inside the quotation passed to " { $link with-generator } "." } ;
  49
  50 HELP: generate-nodes
  51 { $values { "node" "a dataflow node" } }
  52 { $description "Recursively generate machine code for a dataflow graph." }
  53 { $notes "This word can only be called from inside the quotation passed to " { $link with-generator } "." } ;
  54
  55 HELP: generate
  56 { $values { "word" word } { "label" word } { "node" "a dataflow node" } }
  57 { $description "Generates machine code for " { $snippet "label" } " from " { $snippet "node" } ". The value of " { $snippet "word" } " is retained for debugging purposes; it is the word which will appear in a call stack trace if this compiled code block throws an error when run." } ;
  58
  59 HELP: word-dataflow
  60 { $values { "word" word } { "effect" effect } { "dataflow" "a dataflow graph" } }
  61 { $description "Outputs the dataflow graph of a word, taking specializers into account (see " { $link "specializers" } ")." } ;
  62
  63 HELP: define-intrinsics
  64 { $values { "word" word } { "intrinsics" "a sequence of " { $snippet "{ quot assoc }" } " pairs" } }
  65 { $description "Defines a set of assembly intrinsics for the word. When a call to the word is being compiled, each intrinsic is tested in turn; the first applicable one will be called to generate machine code. If no suitable intrinsic is found, a simple call to the word is compiled instead."
  66 $nl
  67 "See " { $link with-template } " for an explanation of the keys which may appear in " { $snippet "assoc" } "." } ;
  68
  69 HELP: define-intrinsic
  70 { $values { "word" word } { "quot" quotation } { "assoc" "an assoc" } }
  71 { $description "Defines an assembly intrinsic for the word. When a call to the word is being compiled, this intrinsic will be used if it is found to be applicable. If it is not applicable, a simple call to the word is compiled instead."
  72 $nl
  73 "See " { $link with-template } " for an explanation of the keys which may appear in " { $snippet "assoc" } "." } ;
  74
  75 HELP: if>boolean-intrinsic
  76 { $values { "quot" "a quotation with stack effect " { $snippet "( label -- )" } } }
  77 { $description "Generates code which pushes " { $link t } " or " { $link f } " on the data stack, depending on whether the quotation jumps to the label or not." } ;
  78
  79 HELP: define-if-intrinsics
  80 { $values { "word" word } { "intrinsics" "a sequence of " { $snippet "{ quot inputs }" } " pairs" } }
  81 { $description "Defines a set of conditional assembly intrinsics for the word, which must have a boolean value as its single output."
  82 $nl
  83 "The quotations must have stack effect " { $snippet "( label -- )" } "; they are required to branch to the label if the word evaluates to true."
  84 $nl
  85 "The " { $snippet "inputs" } " are in the same format as the " { $link +input+ } " key to " { $link with-template } "; a description can be found in the documentation for thatt word." }
  86 { $notes "Conditional intrinsics are used when the word is followed by a call to " { $link if } ". They allow for tighter code to be generated in certain situations; for example, if two integers are being compared and the result is immediately used to branch, the intermediate boolean does not need to be pushed at all." } ;
  87
  88 HELP: define-if-intrinsic
  89 { $values { "word" word } { "quot" "a quotation with stack effect " { $snippet "( label -- )" } } { "inputs" "a sequence of input register specifiers" } }
  90 { $description "Defines a conditional assembly intrinsic for the word, which must have a boolean value as its single output."
  91 $nl
  92 "See " { $link define-if-intrinsics } " for a description of the parameters." } ;