core/inference/backend/backend-docs.factor

   1 USING: help.syntax help.markup words effects inference.dataflow
   2 inference.state kernel sequences
   3 kernel.private combinators sequences.private ;
   4 IN: inference.backend
   5
   6 HELP: literal-expected
   7 { $error-description "Thrown when inference encounters a " { $link call } " or " { $link if } " being applied to a value which is not known to be a literal. Such a form can have an arbitrary stack effect, and does not compile." }
   8 { $notes "This error will be thrown when compiling any combinator, such as " { $link each } ". However, words calling combinators can compile if the combinator is declared " { $link POSTPONE: inline } " and the quotation being passed in is a literal." } ;
   9
  10 HELP: too-many->r
  11 { $error-description "Thrown if inference notices a quotation pushing elements on the retain stack without popping them at the end." }
  12 { $notes "See " { $link "shuffle-words" } " for retain stack usage conventions." } ;
  13
  14 HELP: too-many-r>
  15 { $error-description "Thrown if inference notices a quotation popping elements from the return stack it did not place there." }
  16 { $notes "See " { $link "shuffle-words" } " for retain stack usage conventions." } ;
  17
  18 HELP: unify-lengths
  19 { $values { "seq" sequence } { "newseq" "a new sequence" } }
  20 { $description "Pads sequences in " { $snippet "seq" } " with computed value placeholders to ensure they are all the same length." } ;
  21
  22 HELP: cannot-unify-specials
  23 { $description "Throws an " { $link cannot-unify-specials } "." }
  24 { $error-description "Thrown when some but not all branches in a conditional output " { $link curry } " or " { $link compose } " values. This case is not supported by stack effect inference yet. It does not indicate there is a programming error." } ;
  25
  26 HELP: unify-values
  27 { $values { "seq" sequence } { "value" "an object" } }
  28 { $description "If all values in the sequence are equal, outputs the value, otherwise outputs a computed value placeholder." } ;
  29
  30 HELP: unbalanced-branches-error
  31 { $values { "in" "a sequence of integers" } { "out" "a sequence of integers" } }
  32 { $description "Throws an " { $link unbalanced-branches-error } "." }
  33 { $error-description "Thrown when inference encounters an " { $link if } ", " { $link dispatch } " or " { $link cond } " where the branches do not all exit with the same stack height." }
  34 { $notes "Conditionals with variable stack effects are considered to be bad style and should be avoided since they do not compile."
  35 $nl
  36 "If this error comes up when inferring the stack effect of a recursive word, check the word's stack effect declaration; it might be wrong." } ;
  37
  38 HELP: unify-effect
  39 { $values { "quots" "a sequence of quotations" } { "in" "a sequence of integers" } { "out" "a sequence of stacks" } { "newin" "a sequence of integers" } { "newout" "a sequence of stacks" } }
  40 { $description "Unifies the stack effects of a number of branches, and outputs new values for " { $link d-in } " and " { $link meta-d } "." } ;
  41
  42 HELP: consume/produce
  43 { $values { "node" "a dataflow node" } { "effect" "an instance of " { $link effect } } }
  44 { $description "Adds a node to the dataflow graph that calls " { $snippet "word" } " with a stack effect of " { $snippet "effect" } "." } ;
  45
  46 HELP: cannot-infer-effect
  47 { $values { "word" word } }
  48 { $description "Throws a " { $link cannot-infer-effect } " error." }
  49 { $error-description "Thrown when inference encounters a call to a word which is already known not to have a static stack effect, due to a prior inference attempt failing." } ;
  50
  51 HELP: inline-word
  52 { $values { "word" word } }
  53 { $description "Called during inference to infer stack effects of inline words."
  54 $nl
  55 "If the inline word is recursive, a new " { $link #label } " node is added to the dataflow graph, and the word has to be inferred twice, to determine which literals survive the recursion (eg, quotations) and which don't (loop indices, etc)."
  56 $nl
  57 "If the inline word is not recursive, the resulting nodes are spliced into the dataflow graph, and no " { $link #label } " node is created." } ;
  58
  59 HELP: effect-error
  60 { $values { "word" word } { "effect" "an instance of " { $link effect } } }
  61 { $description "Throws an " { $link effect-error } "." }
  62 { $error-description "Thrown when a word's inferred stack effect does not match its declared stack effect." } ;
  63
  64 HELP: missing-effect
  65 { $error-description "Thrown when inference encounters a word lacking a stack effect declaration. Stack effects of words must be declared, with the exception of words which only push literals on the stack." } ;
  66
  67 HELP: recursive-quotation-error
  68 { $error-description "Thrown when a quotation calls itself, directly or indirectly, within the same word. Stack effect inference becomes equivalent to the halting problem if quotation recursion has to be taken into account, hence it is not permitted." }
  69 { $examples
  70     "Here is an example of quotation recursion:"
  71     { $code "[ [ dup call ] dup call ] infer." }
  72 } ;