PageRenderTime 23ms CodeModel.GetById 18ms app.highlight 1ms RepoModel.GetById 2ms app.codeStats 0ms

/js/src/vprof/readme.txt

http://github.com/zpao/v8monkey
Plain Text | 130 lines | 110 code | 20 blank | 0 comment | 0 complexity | 68f2bad79f8f50bf8b651747a8567a50 MD5 | raw file
  1# ***** BEGIN LICENSE BLOCK *****
  2# Version: MPL 1.1/GPL 2.0/LGPL 2.1
  3#
  4# The contents of this file are subject to the Mozilla Public License Version
  5# 1.1 (the "License"); you may not use this file except in compliance with
  6# the License. You may obtain a copy of the License at
  7# http:#www.mozilla.org/MPL/
  8#
  9# Software distributed under the License is distributed on an "AS IS" basis,
 10# WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 11# for the specific language governing rights and limitations under the
 12# License.
 13#
 14# The Original Code is [Open Source Virtual Machine.].
 15#
 16# The Initial Developer of the Original Code is
 17# Adobe System Incorporated.
 18# Portions created by the Initial Developer are Copyright (C) 2008
 19# the Initial Developer. All Rights Reserved.
 20#
 21# Contributor(s):
 22#   Adobe AS3 Team
 23#
 24# Alternatively, the contents of this file may be used under the terms of
 25# either the GNU General Public License Version 2 or later (the "GPL"), or
 26# the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 27# in which case the provisions of the GPL or the LGPL are applicable instead
 28# of those above. If you wish to allow use of your version of this file only
 29# under the terms of either the GPL or the LGPL, and not to allow others to
 30# use your version of this file under the terms of the MPL, indicate your
 31# decision by deleting the provisions above and replace them with the notice
 32# and other provisions required by the GPL or the LGPL. If you do not delete
 33# the provisions above, a recipient may use your version of this file under
 34# the terms of any one of the MPL, the GPL or the LGPL.
 35#
 36# ***** END LICENSE BLOCK *****
 37
 38The 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).
 39
 40Usage:
 41#include "vprof.h"  // in the source file you want to use it
 42
 43_vprof (value); 
 44
 45At the end of the execution, for each probe you'll get the data associated with the probe, such as:
 46
 47File                                        line    avg     [min : max] total       count
 48..\..\pcre\pcre_valid_utf8.cpp  182 50222.75916 [0 :    104947] 4036955604  80381  
 49
 50The 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.
 51
 52A few typical uses
 53------------------
 54
 55To see how many times a given function gets executed do:
 56
 57void f()
 58{
 59    _vprof(1);
 60    ...
 61} 
 62
 63void f()
 64{
 65        _vprof(1);
 66        ...
 67       if (...) {
 68           _vprof(1);
 69           ...
 70       } else {
 71           _vprof(1);
 72           ...
 73       }
 74}
 75
 76Here are a few examples of using the value-profiling utility:
 77
 78  _vprof (e);
 79    at the end of program execution, you'll get a dump of the source location of this probe,
 80    its min, max, average, the total sum of all instances of e, and the total number of times this probe was called. 
 81
 82  _vprof (x > 0); 
 83    shows how many times and what percentage of the cases x was > 0, 
 84    that is the probablitiy that x > 0.
 85 
 86 _vprof (n % 2 == 0); 
 87    shows how many times n was an even number 
 88    as well as th probablitiy of n being an even number. 
 89 
 90 _hprof (n, 4, 1000, 5000, 5001, 10000); 
 91    gives you the histogram of n over the given 4 bucket boundaries:
 92        # cases <  1000 
 93        # cases >= 1000 and < 5000
 94        # cases >= 5000 and < 5001
 95        # cases >= 5001 and < 10000
 96        # cases >= 10000  
 97 
 98 _nvprof ("event name", value); 
 99    all instances with the same name are merged
100    so, you can call _vprof with the same event name at difference places
101 
102 _vprof (e, myProbe);  
103    value profile e and call myProbe (void* vprofID) at the profiling point.
104    inside the probe, the client has the predefined variables:
105    _VAL, _COUNT, _SUM, _MIN, _MAX, and the general purpose registers
106    _IVAR1, ..., IVAR4      general integer registrs
107    _I64VAR1, ..., I64VAR4  general integer64 registrs  
108    _DVAR1, ..., _DVAR4     general double registers
109    _GENPTR a generic pointer that can be used by the client 
110    the number of registers can be changed in vprof.h
111
112Named Events
113------------
114_nvprof ("event name", value);  
115    all instances with the same name are merged
116    so, you can call _vprof with the same event name at difference places
117
118
119Custom Probes
120--------------
121You can call your own custom probe at the profiling point.
122_vprof (v, myProbe);  
123   value profile v and call myProbe (void* vprofID) at the profiling point
124   inside the probe, the client has the predefined variables:
125   _VAL, _COUNT, _SUM, _MIN, _MAX, and the general purpose registers
126   _IVAR1, ..., IVAR4   general integer registrs
127   _I64VAR1, ..., I64VAR4 general integer64 registrs    
128   _DVAR1, ..., _DVAR4  general double registers
129  the number of registers can be changed in vprof.h
130  _GENPTR a generic pointer that can be used for almost anything