basis/compiler/tree/propagation/call-effect/call-effect-docs.factor

   1 USING: combinators.private compiler.units effects help.markup help.syntax
   2 kernel quotations words ;
   3 IN: compiler.tree.propagation.call-effect
   4
   5 HELP: already-inlined-quot?
   6 { $values { "quot" quotation } { "?" boolean } }
   7 { $description "Some bookkeeping to make sure that crap like [ dup curry call( quot -- ) ] dup curry call( quot -- ) ] doesn't hang the compiler." } ;
   8
   9 HELP: cached-effect-valid?
  10 { $values { "quot" quotation } { "?" boolean } }
  11 { $description { $link t } " if the cached effect is valid." } ;
  12
  13 HELP: call-effect-ic
  14 { $values { "quot" quotation } { "effect" effect } { "inline-cache" inline-cache } }
  15 { $description "Checks if there is a hit in the call effect inline cache and if so calls the quotation using " { $link call-effect-unsafe } ". If there isn't a hit, the quotation is called in a slow way and the cache is updated." } ;
  16
  17 HELP: call-effect>quot
  18 { $values { "effect" effect } { "quot" quotation } }
  19 { $description "Emits a quotation for calling a quotation with the given stack effect." } ;
  20
  21 HELP: call-effect-slow>quot
  22 { $values { "effect" effect } { "quot" quotation } }
  23 { $description "Creates a quotation which wraps " { $link call-effect-unsafe } "." } ;
  24
  25 HELP: call-effect-unsafe?
  26 { $values { "quot" quotation } { "effect" effect } { "?" boolean } }
  27 { $description "Checks if the given effect is safe with regards to the quotation." } ;
  28
  29 HELP: update-inline-cache
  30 { $values { "word/quot" { $or word quotation } } { "ic" inline-cache } }
  31 { $description "Sets the inline caches " { $slot "value" } " to the given word/quot and updates its " { $slot "counter" } " to the value of the " { $link effect-counter } "." } ;
  32
  33 ARTICLE: "compiler.tree.propagation.call-effect" "Expansions of call( and execute( words"
  34 "call( and execute( have complex expansions."
  35 $nl
  36 "If the input quotation is a literal, or built up from curry and compose with terminal quotations literal, it is inlined at the call site."
  37 $nl
  38 "For dynamic call sites, call( uses the following strategy:"
  39 { $list
  40   "Inline caching. If the quotation is the same as last time, just call it unsafely"
  41   "Effect inference. Infer quotation's effect, caching it in the cached-effect slot, and compare it with declaration. If matches, call it unsafely."
  42   "Fallback. If the above doesn't work, call it and compare the datastack before and after to make sure it didn't mess anything up."
  43   "Inline caches and cached effects are invalidated whenever a macro is redefined, or a word's effect changes, by comparing a global counter against the counter value last observed. The counter is incremented by compiler.units."
  44 }
  45 $nl
  46 "execute( uses a similar strategy." ;
  47
  48 ABOUT: "compiler.tree.propagation.call-effect"