1Devel::NYTProf::Data(3)User Contributed Perl DocumentatioDnevel::NYTProf::Data(3)
2
3
4

NAME

6       Devel::NYTProf::Data - Devel::NYTProf data loading and manipulation
7

SYNOPSIS

9         use Devel::NYTProf::Data;
10
11         $profile = Devel::NYTProf::Data->new( { filename => 'nytprof.out' } );
12
13         $profile->dump_profile_data();
14

DESCRIPTION

16       Reads a profile data file written by Devel::NYTProf, aggregates the
17       contents, and returns the results as a blessed data structure.
18
19       Access to the data should be via methods in this class to avoid
20       breaking encapsulation (and thus breaking your code when the data
21       structures change in future versions).
22
23       XXX Currently the documentation is out of date as this module is
24       evolving rapidly.
25

METHODS

27   new
28         $profile = Devel::NYTProf::Data->new( );
29
30         $profile = Devel::NYTProf::Data->new( {
31           filename => 'nytprof.out', # default
32           quiet    => 0,             # default, 1 to silence message
33         } );
34
35       Reads the specified file containing profile data written by
36       Devel::NYTProf, aggregates the contents, and returns the results as a
37       blessed data structure.
38
39   dump_profile_data
40         $profile->dump_profile_data;
41         $profile->dump_profile_data( {
42             filehandle => \*STDOUT,
43             separator  => "",
44         } );
45
46       Writes the profile data in a reasonably human friendly format to the
47       sepcified "filehandle" (default STDOUT).
48
49       For non-trivial profiles the output can be very large. As a guide,
50       there'll be at least one line of output for each line of code executed,
51       plus one for each place a subroutine was called from, plus one per
52       subroutine.
53
54       The default format is a Data::Dumper style whitespace-indented tree.
55       The types of data present can depend on the options used when
56       profiling.
57
58       If "separator" is true then instead of whitespace, each item of data is
59       indented with the path through the structure with "separator" used to
60       separarate the elements of the path.  This format is especially useful
61       for grep'ing and diff'ing.
62
63   normalize_variables
64         $profile->normalize_variables;
65
66       Traverses the profile data structure and normalizes highly variable
67       data, such as the time, in order that the data can more easily be
68       compared. This is mainly of use to the test suite.
69
70       The data normalized is:
71
72       ·   profile timing data: set to 0
73
74       ·   subroutines: timings are set to 0
75
76       ·   attributes, like basetime, xs_version, etc., are set to 0
77
78       ·   filenames: path prefixes matching absolute paths in @INC are
79           changed to "/.../"
80
81       ·   filenames: eval sequence numbers, like "(re_eval 2)" are changed to
82           0
83
84   subs_defined_in_file
85         $subs_defined_hash = $profile->subs_defined_in_file( $file, $include_lines );
86
87       Returns a reference to a hash containing information about subroutines
88       defined in a source file.  The $file argument can be an integer file id
89       (fid) or a file path.
90
91       Returns undef if the profile contains no "sub_subinfo" data for the
92       $file.
93
94       The keys of the returned hash are fully qualified subroutine names and
95       the corresponding value is a hash reference containing
96       Devel::NYTProf::SubInfo objects.
97
98       If $include_lines is true then the hash also contains integer keys
99       corresponding to the first line of the subroutine. The corresponding
100       value is a reference to an array. The array contains a hash ref for
101       each of the subroutines defined on that line, typically just one.
102
103   file_line_range_of_sub
104         ($file, $fid, $first, $last, $fi) = $profile->file_line_range_of_sub("main::foo");
105
106       Returns the filename, fid, and first and last line numbers, and
107       fileinfo object for the specified subroutine (which must be fully
108       qualified with a package name).
109
110       Returns an empty list if the subroutine name is not in the profile
111       data.
112
113       The $fid return is the 'original' fid associated with the file the
114       subroutine was created in.
115
116       The $file returned is the source file that defined the subroutine.
117
118       Subroutines that are implemented in XS have a line range of 0,0 and a
119       possibly unknown file (if NYTProf couldn't find a good match based on
120       the package name).
121
122       Subroutines that were called but only returned via an exception may
123       have a line range of undef,undef if they're xsubs or were defined
124       before NYTProf was enabled.
125
126   resolve_fid
127         $fid = $profile->resolve_fid( $file );
128
129       Returns the integer file id that corresponds to $file.
130
131       If $file can't be found and $file looks like a positive integer then
132       it's presumed to already be a fid and is returned. This is used to
133       enable other methods to work with fid or file arguments.
134
135       If $file can't be found but it uniquely matches the suffix of one of
136       the files then that corresponding fid is returned.
137

PROFILE DATA STRUTURE

139       XXX
140

LIMITATION

142       There's currently no way to merge profile data from multiple files.
143

SEE ALSO

145       Devel::NYTProf
146

AUTHOR

148       Adam Kaplan, "<akaplan at nytimes.com>" Tim Bunce,
149       <http://www.tim.bunce.name> and <http://blog.timbunce.org> Steve
150       Peters, "<steve at fisharerojo.org>"
151
153        Copyright (C) 2008 by Adam Kaplan and The New York Times Company.
154        Copyright (C) 2008,2009 by Tim Bunce, Ireland.
155
156       This library is free software; you can redistribute it and/or modify it
157       under the same terms as Perl itself, either Perl version 5.8.8 or, at
158       your option, any later version of Perl 5 you may have available.
159
160
161
162perl v5.12.2                      2010-11-19           Devel::NYTProf::Data(3)
Impressum