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       NOTE the documentation is out of date and may not be updated soon.
24       It's also likely that the API will change drastically in future.  It's
25       possible, for example, that the data model will switch to use SQLite
26       and the http://metacpan.org/pod/ORLite ORM.
27
28       Let me know if you come to depend on a particular API and I'll try to
29       preserve it if practical.
30

METHODS

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

PROFILE DATA STRUTURE

144       XXX
145

LIMITATION

147       There's currently no way to merge profile data from multiple files.
148

SEE ALSO

150       Devel::NYTProf
151

AUTHOR

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