basis/compiler/generator/generator-docs.factor

   1 USING: help.markup help.syntax words debugger
   2 compiler.generator.fixup compiler.generator.registers quotations
   3 kernel vectors arrays effects sequences ;
   4 IN: compiler.generator
   5
   6 ARTICLE: "generator" "Compiled code generator"
   7 "Most of the words in the " { $vocab-link "compiler.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: begin-compiling
  35 { $values { "word" word } { "label" word } }
  36 { $description "Prepares to generate machine code for a word." } ;
  37
  38 HELP: with-generator
  39 { $values { "nodes" "a sequence of nodes" } { "word" word } { "label" word } { "quot" "a quotation with stack effect " { $snippet "( node -- )" } } }
  40 { $description "Generates machine code for " { $snippet "label" } " by applying the quotation to the sequence of nodes." } ;
  41
  42 HELP: generate-node
  43 { $values { "node" "a dataflow node" } { "next" "a dataflow node" } }
  44 { $contract "Generates machine code for a dataflow node, and outputs the next node to generate machine code for." }
  45 { $notes "This word can only be called from inside the quotation passed to " { $link with-generator } "." } ;
  46
  47 HELP: generate-nodes
  48 { $values { "nodes" "a sequence of nodes" } }
  49 { $description "Recursively generate machine code for a dataflow graph." }
  50 { $notes "This word can only be called from inside the quotation passed to " { $link with-generator } "." } ;
  51
  52 HELP: generate
  53 { $values { "word" word } { "label" word } { "nodes" "a sequence of nodes" } }
  54 { $description "Generates machine code for " { $snippet "label" } " from " { $snippet "nodes" } ". 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." } ;
  55
  56 HELP: define-intrinsics
  57 { $values { "word" word } { "intrinsics" "a sequence of " { $snippet "{ quot assoc }" } " pairs" } }
  58 { $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."
  59 $nl
  60 "See " { $link with-template } " for an explanation of the keys which may appear in " { $snippet "assoc" } "." } ;
  61
  62 HELP: define-intrinsic
  63 { $values { "word" word } { "quot" quotation } { "assoc" "an assoc" } }
  64 { $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."
  65 $nl
  66 "See " { $link with-template } " for an explanation of the keys which may appear in " { $snippet "assoc" } "." } ;
  67
  68 HELP: if>boolean-intrinsic
  69 { $values { "quot" "a quotation with stack effect " { $snippet "( label -- )" } } }
  70 { $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." } ;
  71
  72 HELP: define-if-intrinsics
  73 { $values { "word" word } { "intrinsics" "a sequence of " { $snippet "{ quot inputs }" } " pairs" } }
  74 { $description "Defines a set of conditional assembly intrinsics for the word, which must have a boolean value as its single output."
  75 $nl
  76 "The quotations must have stack effect " { $snippet "( label -- )" } "; they are required to branch to the label if the word evaluates to true."
  77 $nl
  78 "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." }
  79 { $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." } ;
  80
  81 HELP: define-if-intrinsic
  82 { $values { "word" word } { "quot" "a quotation with stack effect " { $snippet "( label -- )" } } { "inputs" "a sequence of input register specifiers" } }
  83 { $description "Defines a conditional assembly intrinsic for the word, which must have a boolean value as its single output."
  84 $nl
  85 "See " { $link define-if-intrinsics } " for a description of the parameters." } ;