basis/tools/profiler/sampling/sampling-docs.factor

   1 ! Copyright (C) 2010 Joe Groff.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: arrays calendar help.markup help.syntax math quotations threads
   4 tools.profiler.sampling.private ;
   5 IN: tools.profiler.sampling
   6
   7 { cross-section flat top-down top-down-max-depth profile profile. } related-words
   8 { cross-section* flat* top-down* top-down-max-depth* most-recent-profile-data } related-words
   9
  10 { total-sample-count gc-sample-count jit-sample-count foreign-sample-count foreign-thread-sample-count sample-thread sample-callstack } related-words
  11
  12 { total-time gc-time foreign-time foreign-thread-time } related-words
  13
  14 HELP: cross-section
  15 { $values
  16     { "depth" integer }
  17     { "tree" "a profile report" }
  18 }
  19 { $description "Generates a cross-section profile at " { $snippet "depth" } " from the results of the most recent " { $link profile } ". Each sample's time will be charged to the function " { $snippet "depth" } " levels deep in the callstack, or to the deepest function in the callstack if the callstack at the time of the sample is fewer than " { $snippet "depth" } " levels deep. The output " { $snippet "tree" } " can be printed with the " { $link profile. } " word." } ;
  20
  21 HELP: cross-section*
  22 { $values
  23     { "depth" integer } { "profile-data" "raw profile data" }
  24     { "tree" "a profile report" }
  25 }
  26 { $description "Generates a cross-section profile at " { $snippet "depth" } " from the profile results in " { $snippet "profile-data" } ". Each sample's time will be charged to the function " { $snippet "depth" } " levels deep in the callstack, or to the deepest function in the callstack if the callstack at the time of the sample is fewer than " { $snippet "depth" } " levels deep. The output " { $snippet "tree" } " can be printed with the " { $link profile. } " word." } ;
  27
  28 HELP: flat
  29 { $values
  30         { "flat" "a profile report" }
  31 }
  32 { $description "Generates a flat profile from the results of the most recent " { $link profile } ". Each sample's time will be charged to every function in the callstack at the time of the sample. The output " { $snippet "tree" } " can be printed with the " { $link profile. } " word." } ;
  33
  34 HELP: flat*
  35 { $values
  36     { "profile-data" "raw profile data" }
  37     { "flat" "a profile report" }
  38 }
  39 { $description "Generates a flat profile from the profile results in " { $snippet "profile-data" } ". Each sample's time will be charged to every function in the callstack at the time of the sample. The output " { $snippet "tree" } " can be printed with the " { $link profile. } " word." } ;
  40
  41 HELP: foreign-sample-count
  42 { $values
  43     { "sample" "a raw profile sample" }
  44     { "count" integer }
  45 }
  46 { $description "Returns the number of sample intervals spent in non-Factor code (such as the Factor VM, or FFI calls) during " { $snippet "sample" } "." } ;
  47
  48 HELP: foreign-thread-sample-count
  49 { $values
  50     { "sample" "a raw profile sample" }
  51     { "count" integer }
  52 }
  53 { $description "Returns the number of sample intervals spent executing non-Factor threads within the Factor process during " { $snippet "sample" } "." } ;
  54
  55 HELP: foreign-thread-time
  56 { $values
  57         { "n" duration }
  58 }
  59 { $description "Returns the total time spent executing non-Factor threads within the Factor process during the last " { $link profile } "." } ;
  60
  61 HELP: foreign-thread-time*
  62 { $values
  63     { "profile-data" "raw profile data" }
  64     { "n" duration }
  65 }
  66 { $description "Returns the total time spent executing non-Factor threads within the Factor process from the given " { $snippet "profile-data" } "." } ;
  67
  68 HELP: foreign-time
  69 { $values
  70         { "n" duration }
  71 }
  72 { $description "Returns the total time spent in non-Factor code (such as the Factor VM, or FFI calls) during the last " { $link profile } "." } ;
  73
  74 HELP: foreign-time*
  75 { $values
  76     { "profile-data" "raw profile data" }
  77     { "n" duration }
  78 }
  79 { $description "Returns the total time spent in non-Factor code (such as the Factor VM, or FFI calls) from the given " { $snippet "profile-data" } "." } ;
  80
  81 HELP: gc-sample-count
  82 { $values
  83     { "sample" "a raw profile sample" }
  84     { "count" integer }
  85 }
  86 { $description "Returns the number of sample intervals spent in the garbage collector during " { $snippet "sample" } "." } ;
  87
  88 HELP: gc-time
  89 { $values
  90         { "n" duration }
  91 }
  92 { $description "Returns the total time spent in the garbage collector during the last " { $link profile } "." } ;
  93
  94 HELP: gc-time*
  95 { $values
  96     { "profile-data" "raw profile data" }
  97     { "n" duration }
  98 }
  99 { $description "Returns the total time spent in the garbage collector from the given " { $snippet "profile-data" } "." } ;
 100
 101 HELP: jit-sample-count
 102 { $values
 103     { "sample" "a raw profile sample" }
 104     { "count" integer }
 105 }
 106 { $description "Returns the number of sample intervals spent in the non-optimizing compiler during " { $snippet "sample" } "." } ;
 107
 108 HELP: most-recent-profile-data
 109 { $values
 110         { "profile-data" "raw profile data" }
 111 }
 112 { $description "Returns the raw profile data from the most recent " { $link profile } ". This data can be saved and used with the " { $snippet "*" } " variants of reporting words, such as " { $link top-down* } " and " { $link flat* } ", independent of later executions of the profiler.." } ;
 113
 114 HELP: profile
 115 { $values
 116     { "quot" quotation }
 117 }
 118 { $description "Executes " { $snippet "quot" } " with the sampling profiler enabled. The results of the profile can subsequently be reported with words such as " { $link top-down } " and " { $link flat } ", or the raw data can be saved and inspected with " { $link most-recent-profile-data } "." } ;
 119
 120 HELP: profile-node
 121 { $class-description "Objects of this type are generated by profile reporting words such as " { $link top-down } ", " { $link top-down-max-depth } ", " { $link cross-section } ", and " { $link flat } "." } ;
 122
 123 HELP: profile.
 124 { $values
 125     { "tree" "a profile report" }
 126 }
 127 { $description "Formats and prints a profile report generated by " { $link top-down } ", " { $link top-down-max-depth } ", " { $link cross-section } ", or " { $link flat } "." } ;
 128
 129 HELP: raw-profile-data
 130 { $var-description "Holds raw profiling data. Set by the " { $link profile } " word after the profiling run is over." } ;
 131
 132 HELP: sample-callstack
 133 { $values
 134     { "sample" "a raw profile sample" }
 135     { "array" array }
 136 }
 137 { $description "Returns the callstack (the stack of functions currently executing) at the time of " { $snippet "sample" } "." } ;
 138
 139 HELP: sample-thread
 140 { $values
 141     { "sample" "a raw profile sample" }
 142     { "thread" thread }
 143 }
 144 { $description "Returns the currently-executing Factor thread at the time of " { $snippet "sample" } "." } ;
 145
 146 HELP: samples-per-second
 147 { $var-description "This variable controls the rate at which the profiler takes samples during calls to " { $link profile } "." } ;
 148
 149 HELP: samples>time
 150 { $values
 151     { "samples" integer }
 152     { "seconds" integer }
 153 }
 154 { $description "Converts a sample interval count to an integer based on the value of " { $link samples-per-second } "." } ;
 155
 156 HELP: top-down
 157 { $values
 158         { "tree" "a profile report" }
 159 }
 160 { $description "Generates a top-down tree profile from the results of the most recent " { $link profile } ". The output " { $snippet "tree" } " can be printed with the " { $link profile. } " word." } ;
 161
 162 HELP: top-down*
 163 { $values
 164     { "profile-data" "raw profile data" }
 165     { "tree" "a profile report" }
 166 }
 167 { $description "Generates a top-down tree profile from the profile results in " { $snippet "profile-data" } ". The output " { $snippet "tree" } " can be printed with the " { $link profile. } " word." } ;
 168
 169 HELP: top-down-max-depth
 170 { $values
 171     { "max-depth" integer }
 172     { "tree" "a profile report" }
 173 }
 174 { $description "Generates a top-down tree profile from the results of the most recent " { $link profile } ". Functions at a callstack depth greater than " { $snippet "max-depth" } " will be filtered out. The output " { $snippet "tree" } " can be printed with the " { $link profile. } " word." } ;
 175
 176 HELP: top-down-max-depth*
 177 { $values
 178     { "max-depth" integer } { "profile-data" "raw profile data" }
 179     { "tree" "a profile report" }
 180 }
 181 { $description "Generates a top-down tree profile from the profile results in " { $snippet "profile-data" } ". Functions at a callstack depth greater than " { $snippet "max-depth" } " will be filtered out. The output " { $snippet "tree" } " can be printed with the " { $link profile. } " word." } ;
 182
 183 HELP: total-sample-count
 184 { $values
 185     { "sample" "a raw profile sample" }
 186     { "count" integer }
 187 }
 188 { $description "Returns the total number of sample intervals spent during " { $snippet "sample" } "." } ;
 189
 190 HELP: total-time
 191 { $values
 192         { "n" duration }
 193 }
 194 { $description "Returns the total time spent during the most recent " { $link profile } "." } ;
 195
 196 HELP: total-time*
 197 { $values
 198     { "profile-data" "raw profile data" }
 199     { "n" duration }
 200 }
 201 { $description "Returns the total time spent from the given " { $snippet "profile-data" } "." } ;
 202
 203 ARTICLE: "tools.profiler.sampling" "Sampling profiler"
 204 "The " { $vocab-link "tools.profiler.sampling" } " vocabulary provides an interface to Factor's sampling profiler. It provides words for running the profiler:"
 205 { $subsections profile }
 206 "General statistics can then be collected:"
 207 { $subsections total-time gc-time foreign-time foreign-thread-time }
 208 "More detailed by-function profile reports can be generated:"
 209 { $subsections top-down top-down-max-depth cross-section flat }
 210 "The report data can then be printed:"
 211 { $subsections profile. }
 212 "Profile data can be saved for future reporting:"
 213 { $subsections most-recent-profile-data top-down* top-down-max-depth* cross-section* flat* }
 214 "For example, the following will profile a call to the foo word, and generate and display a top-down tree profile from the results:"
 215 { $code "[ foo ] profile
 216 top-down profile." }
 217 ;
 218
 219 ABOUT: "tools.profiler.sampling"
 220
 221 ! Implementation
 222
 223 ! Inaccuracies
 224 !   epilogue bias
 225 !   sample count phase
 226 !   not compensated for sample collection time
 227 !   nearest-neighbor reporting