readme.txt (3608B)
1 # This Source Code Form is subject to the terms of the Mozilla Public 2 # License, v. 2.0. If a copy of the MPL was not distributed with this 3 # file, You can obtain one at http://mozilla.org/MPL/2.0/. 4 5 The two files vprof.h and vprof.cpp implement a simple value-profiling mechanism. By including these two files in avmplus (or any other project), you can value profile data as you wish (currently integers). 6 7 Usage: 8 #include "vprof.h" // in the source file you want to use it 9 10 _vprof (value); 11 12 At the end of the execution, for each probe you'll get the data associated with the probe, such as: 13 14 File line avg [min : max] total count 15 ..\..\pcre\pcre_valid_utf8.cpp 182 50222.75916 [0 : 104947] 4036955604 80381 16 17 The probe is defined at line 182 of file pcre_vali_utf8.cpp. It was called 80381 times. The min value of the probe was 0 while its max was 10497 and its average was 50222.75916. The total sum of all values of the probe is 4036955604. Later, I plan to add more options on the spectrum of data among others. 18 19 A few typical uses 20 ------------------ 21 22 To see how many times a given function gets executed do: 23 24 void f() 25 { 26 _vprof(1); 27 ... 28 } 29 30 void f() 31 { 32 _vprof(1); 33 ... 34 if (...) { 35 _vprof(1); 36 ... 37 } else { 38 _vprof(1); 39 ... 40 } 41 } 42 43 Here are a few examples of using the value-profiling utility: 44 45 _vprof (e); 46 at the end of program execution, you'll get a dump of the source location of this probe, 47 its min, max, average, the total sum of all instances of e, and the total number of times this probe was called. 48 49 _vprof (x > 0); 50 shows how many times and what percentage of the cases x was > 0, 51 that is the probablitiy that x > 0. 52 53 _vprof (n % 2 == 0); 54 shows how many times n was an even number 55 as well as th probablitiy of n being an even number. 56 57 _hprof (n, 4, 1000, 5000, 5001, 10000); 58 gives you the histogram of n over the given 4 bucket boundaries: 59 # cases < 1000 60 # cases >= 1000 and < 5000 61 # cases >= 5000 and < 5001 62 # cases >= 5001 and < 10000 63 # cases >= 10000 64 65 _nvprof ("event name", value); 66 all instances with the same name are merged 67 so, you can call _vprof with the same event name at difference places 68 69 _vprof (e, myProbe); 70 value profile e and call myProbe (void* vprofID) at the profiling point. 71 inside the probe, the client has the predefined variables: 72 _VAL, _COUNT, _SUM, _MIN, _MAX, and the general purpose registers 73 _IVAR1, ..., IVAR4 general integer registrs 74 _I64VAR1, ..., I64VAR4 general integer64 registrs 75 _DVAR1, ..., _DVAR4 general double registers 76 _GENPTR a generic pointer that can be used by the client 77 the number of registers can be changed in vprof.h 78 79 Named Events 80 ------------ 81 _nvprof ("event name", value); 82 all instances with the same name are merged 83 so, you can call _vprof with the same event name at difference places 84 85 86 Custom Probes 87 -------------- 88 You can call your own custom probe at the profiling point. 89 _vprof (v, myProbe); 90 value profile v and call myProbe (void* vprofID) at the profiling point 91 inside the probe, the client has the predefined variables: 92 _VAL, _COUNT, _SUM, _MIN, _MAX, and the general purpose registers 93 _IVAR1, ..., IVAR4 general integer registrs 94 _I64VAR1, ..., I64VAR4 general integer64 registrs 95 _DVAR1, ..., _DVAR4 general double registers 96 the number of registers can be changed in vprof.h 97 _GENPTR a generic pointer that can be used for almost anything