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

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