basis/tools/profiler/profiler-docs.factor

   1 USING: tools.profiler.private tools.time help.markup help.syntax
   2 quotations io strings words definitions ;
   3 IN: tools.profiler
   4
   5 ARTICLE: "profiler-limitations" "Profiler limitations"
   6 "Certain optimizations performed by the compiler can inhibit accurate call counting:"
   7 { $list
   8     "Calls to open-coded intrinsics are not counted. Certain words are open-coded as inline machine code, and in some cases optimized out altogether; this includes stack shuffling operations, conditionals, and many object allocation operations."
   9     { "Calls to " { $link POSTPONE: inline } " words are not counted." }
  10     { "Calls to methods which were inlined as a result of type inference are not counted." }
  11     "Tail-recursive loops will only count the initial invocation of the word, not every tail call."
  12 } ;
  13
  14 ARTICLE: "profiling" "Profiling code"
  15 "The " { $vocab-link "tools.profiler" } " vocabulary implements a simple call counting profiler."
  16 $nl
  17 "Quotations can be passed to a combinator which calls them with the profiler enabled:"
  18 { $subsection profile }
  19 "After a quotation has been profiled, call counts can be presented in various ways:"
  20 { $subsection profile. }
  21 { $subsection vocab-profile. }
  22 { $subsection usage-profile. }
  23 { $subsection vocabs-profile. }
  24 { $subsection method-profile. }
  25 { $subsection "profiler-limitations" }
  26 { $see-also "ui-profiler" } ;
  27
  28 ABOUT: "profiling"
  29
  30 HELP: counters
  31 { $values { "words" "a sequence of words" } { "assoc" "an association list mapping words to integers" } }
  32 { $description "Outputs an association list of word call counts." } ;
  33
  34 HELP: counters.
  35 { $values { "assoc" "an association list mapping words to integers" } }
  36 { $description "Prints an association list of call counts to " { $link output-stream } "." } ;
  37
  38 HELP: profile
  39 { $values { "quot" quotation } }
  40 { $description "Calls the quotation while collecting word call counts, which can then be displayed using " { $link profile. } " or related words." } ;
  41
  42 HELP: profile.
  43 { $description "Prints a table of call counts from the most recent invocation of " { $link profile } "." } ;
  44
  45 HELP: vocab-profile.
  46 { $values { "vocab" string } }
  47 { $description "Prints a table of call counts from the most recent invocation of " { $link profile } ", for words in the " { $snippet "vocab" } " vocabulary only." }
  48 { $examples { $code "\"math\" vocab-profile." } } ;
  49
  50 HELP: usage-profile.
  51 { $values { "word" word } }
  52 { $description "Prints a table of call counts from the most recent invocation of " { $link profile } ", for words which directly call " { $snippet "word" } " only." }
  53 { $notes "This word obtains the list of static usages with the " { $link smart-usage } " word, and is not aware of dynamic call history. Consider the following scenario. A word " { $snippet "X" } " can execute word " { $snippet "Y" } " in a conditional branch, and " { $snippet "X" } " is executed many times during the profiling run, but this particular branch executing " { $snippet "Y" } " is never taken. However, some other word does execute " { $snippet "Y" } " multiple times. Then " { $snippet "\\ Y usage-profile." } " will list a number of calls to " { $snippet "X" } ", even though " { $snippet "Y" } " was never executed " { $emphasis "from" } " " { $snippet "X" } "." }
  54 { $examples { $code "\\ + usage-profile." } } ;
  55
  56 HELP: vocabs-profile.
  57 { $description "Print a table of cumilative call counts for each vocabulary. Vocabularies whose words were not called are supressed from the output." } ;
  58
  59 HELP: method-profile.
  60 { $description "Print a table of cumilative call counts for each method. Methods which were not called are supressed from the output." } ;
  61
  62 HELP: profiling ( ? -- )
  63 { $values { "?" "a boolean" } }
  64 { $description "Internal primitive to switch on call counting. This word should not be used; instead use " { $link profile } "." } ;
  65
  66 { time profile } related-words