basis/tools/time/time-docs.factor

   1 USING: help.markup help.syntax memory system tools.dispatch
   2 tools.memory quotations vm ;
   3 IN: tools.time
   4
   5 ARTICLE: "timing" "Timing code and collecting statistics"
   6 "You can time the execution of a quotation in the listener:"
   7 { $subsections time }
   8 "This word also collects statistics about method dispatch and garbage collection:"
   9 { $subsections dispatch-stats. gc-events. gc-stats. gc-summary. }
  10 "A lower-level word puts timings on the stack, intead of printing:"
  11 { $subsections benchmark }
  12 "You can also read the system clock directly; see " { $link "system" } "."
  13 { $see-also "profiling" "calendar" } ;
  14
  15 ABOUT: "timing"
  16
  17 HELP: benchmark
  18 { $values { "quot" quotation }
  19           { "runtime" "the runtime in microseconds" } }
  20       { $description "Runs a quotation, measuring the total wall clock time." }
  21 { $notes "A nicer word for interactive use is " { $link time } "." } ;
  22
  23 HELP: time
  24 { $values { "quot" quotation } }
  25 { $description "Runs a quotation, gathering statistics about method dispatch and garbage collection, and then prints the total run time." } ;
  26
  27 { benchmark system-micros time } related-words
  28
  29 HELP: collect-gc-events
  30 { $values { "quot" quotation } }
  31 { $description "Calls the quotation, storing an array of " { $link gc-event } " instances in the " { $link gc-events } " variable." }
  32 { $notes "The " { $link time } " combinator automatically calls this combinator." } ;
  33
  34 HELP: collect-dispatch-stats
  35 { $values { "quot" quotation } }
  36 { $description "Calls the quotation, collecting method dispatch statistics and storing them in the " { $link last-dispatch-stats } " variable. " }
  37 { $notes "The " { $link time } " combinator automatically calls this combinator." } ;