1Devel::NYTProf::ReadStrUesaemr(3C)ontributed Perl DocumeDnetvaetli:o:nNYTProf::ReadStream(3)
2
3
4

NAME

6       Devel::NYTProf::ReadStream - Read Devel::NYTProf data file as a stream
7

SYNOPSIS

9         use Devel::NYTProf::ReadStream qw(for_chunks);
10
11         for_chunks {
12             my $tag = shift;
13             print "$tag\n";
14             # examine @_
15             ....
16         }
17
18         # quickly dump content of a file
19         use Data::Dump;
20         for_chunks(\&dd);
21

DESCRIPTION

23       This module provide a low level interface for reading the contents of
24       nytprof.out files (Devel::NYTProf data files) as a stream of chunks.
25
26       Currently the module only provide a single function:
27
28       for_chunks( \&callback, %opts )
29           This function will read the nytprof.out file and invoke the given
30           callback function for each chunk in the file.
31
32           The first argument passed to the callback is the chunk tag.  The
33           rest of the arguments passed depend on the tag.  See "Chunks" for
34           the details.  The return value of the callback function is ignored.
35
36           The for_chunks() function will croak if the file can't be opened or
37           if the file format isn't recognized.  The global $. variable is
38           made to track the chunk sequence numbers and can be inspected in
39           the callback.
40
41           The behaviour of the function can be modified by passing key/value
42           pairs after the callback. The contents of %opts are passed to "new"
43           in Devel::NYTProf::Data.
44
45           The function is prototyped as "(&%)" which means that it can be
46           invoked with a bare block representing the callback function.  In
47           that case there should be no comma before any options.  Example:
48
49             for_chunk { say $_[0] } filename => "myprof.out";
50
51   Chunks
52       The nytprof.out file contains a sequence of tagged chunks that are
53       streamed out as the profiled program runs.  This documents how the
54       chunks appear when presented to the callback function of the
55       for_chunks() function for version 4.0 of the file format.
56
57       Note that the chunks and their arguments are liable to change between
58       versions as NYTProf evolves.
59
60       VERSION => $major, $minor
61           The first chunk in the file declare what version of the file format
62           was used for the current file.
63
64       COMMENT => $text
65           This chunk is just some textual content that can be ignored.
66
67       ATTRIBUTE => $key, $value
68           This chunk type is repeated at the beginning of the file and used
69           to declare various facts about the profiling run.  The only one
70           that's really interesting is "ticks_per_sec" that tell you how to
71           convert the $ticks values into seconds.
72
73           The attributes reported are:
74
75           basetime => $time
76               The time (epoch based) when the profiled perl process started.
77               It's the same value as $^T.
78
79           xs_version => $ver
80               The version of the Devel::NYTProf used for profiling.
81
82           perl_version => $ver
83               The version of perl used for profiling.  This is a string like
84               "5.10.1".
85
86           clock_id => $num
87               What kind of clock was used to profile the program.  Will be
88               "-1" for the default clock.
89
90           ticks_per_sec => $num
91               Divide the $ticks values in TIME_BLOCK/TIME_LINE by this number
92               to convert the time to seconds.
93
94           nv_size => 8
95               The $Config{nv_size} of the perl that wrote this file.  This
96               value must match for the perl that reads the file as well.
97
98           application => $string
99               The path to the program that ran; same as $0 in the program
100               itself.
101
102       OPTION => $key, $value
103           This chunk type is repeated at the beginning of the file and used
104           to record the options, e.g. set via the NYTPROF env var, that were
105           effect during the profiling run.
106
107       START_DEFLATE
108           This chunk just say that from now on all chunks have been
109           compressed in the file.
110
111       PID_START => $pid, $parent_pid, $start_time
112           The process with the given $pid starts running (under the
113           profiler).
114
115           Dates from the way forking used to be supported. Likely to get
116           deprecated when we get better support for tracking the time the sub
117           profiler and statement profiler were actually active. (Which is
118           needed to calculate percentages.)
119
120       NEW_FID => $fid, $eval_fid, $eval_line, $flags, $size, $mtime, $name
121           Files are represented by integers called 'fid' (File IDs) and this
122           chunk declares the mapping between these numbers and file path
123           names.
124
125       TIME_BLOCK => $ticks, $fid, $line, $block_line, $sub_line
126       TIME_LINE => $ticks, $fid, $line
127           A TIME_BLOCK or TIME_LINE chunk is output each time the execution
128           of the program leaves a statement.
129
130       DISCOUNT
131           Indicates that the next TIME_BLOCK or TIME_LINE should not
132           increment the "number of times the statement was executed". See the
133           'leave' option.
134
135       SUB_INFO => $fid, $first_line, $last_line, $name
136           At the end of the run the profiler will output chunks that report
137           on the perl subroutines defined in all the files visited while
138           profiling.  See also %DB::sub in perldebguts.
139
140       SUB_CALLERS => $fid, $line, $count, $incl_time, $excl_time, $reci_time,
141       $rec_depth, $name, $caller_name
142           At the end of the run the profiler will output chunks that report
143           on where subroutines were called from.
144
145       SRC_LINE => $fid, $line, $text
146           Used to reproduce the source code of the files and evals profiled.
147           Requires perl 5.8.9+ or 5.10.1+ or 5.12 or later. For earlier
148           versions of perl the source code of "perl -e '...'" and "perl -"
149           'files' is available if the "use_db_sub=1" option was used when
150           profiling.
151
152       PID_END => $pid, $end_time
153           The process with the given $pid is done running.  See the
154           description of PID_START above.
155

SEE ALSO

157       Devel::NYTProf, Devel::NYTProf::Data
158

AUTHOR

160       Gisle Aas
161
163        Copyright (C) 2008 by Adam Kaplan and The New York Times Company.
164        Copyright (C) 2008 by Tim Bunce, Ireland.
165        Copyright (C) 2008 by Gisle Aas
166
167       This library is free software; you can redistribute it and/or modify it
168       under the same terms as Perl itself, either Perl version 5.8.8 or, at
169       your option, any later version of Perl 5 you may have available.
170
171
172
173perl v5.34.0                      2021-07-22     Devel::NYTProf::ReadStream(3)
Impressum