1Devel::NYTProf::ReadStrUesaemr(3C)ontributed Perl DocumeDnetvaetli:o:nNYTProf::ReadStream(3)
2
6 Devel::NYTProf::ReadStream - Read Devel::NYTProf data file as a stream
7
9 use Devel::NYTProf::ReadStream qw(for_chunks);
10 for_chunks {
12 my $tag = shift;
13 print "$tag\n";
14 # examine @_
15 ....
16 }
17 # quickly dump content of a file
19 use Data::Dump;
20 for_chunks(\&dd);
21
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 Currently the module only provide a single function:
27 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 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 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 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 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 for_chunk { say $_[0] } filename => "myprof.out";
50 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 Note that the chunks and their arguments are liable to change between
58 versions as NYTProf evolves.
59 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 COMMENT => $text
65 This chunk is just some textual content that can be ignored.
66 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 The attributes reported are:
74 basetime => $time
76 The time (epoch based) when the profiled perl process started.
77 It's the same value as $^T.
78 xs_version => $ver
80 The version of the Devel::NYTProf used for profiling.
81 perl_version => $ver
83 The version of perl used for profiling. This is a string like
84 "5.10.1".
85 clock_id => $num
87 What kind of clock was used to profile the program. Will be
88 "-1" for the default clock.
89 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 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 application => $string
99 The path to the program that ran; same as $0 in the program
100 itself.
101 START_DEFLATE
103 This chunk just say that from now on all chunks have been
104 compressed in the file.
105 PID_START => $pid, $parent_pid, $start_time
107 The process with the given $pid starts running (under the
108 profiler).
109 Dates from the way forking used to be supported. Likely to get
111 deprecated when we get better support for tracking the time the sub
112 profiler and statement profiler were actually active. (Which is
113 needed to calculate percentages.)
114 NEW_FID => $fid, $eval_fid, $eval_line, $flags, $size, $mtime, $name
116 Files are represented by integers called 'fid' (File IDs) and this
117 chunk declares the mapping between these numbers and file path
118 names.
119 TIME_BLOCK => $ticks, $fid, $line, $block_line, $sub_line
121 TIME_LINE => $ticks, $fid, $line
122 A TIME_BLOCK or TIME_LINE chunk is output each time the execution
123 of the program leaves a statement.
124 DISCOUNT
126 Indicates that the next TIME_BLOCK or TIME_LINE should not
127 increment the "number of times the statement was executed". See the
128 'leave' option.
129 SUB_INFO => $fid, $first_line, $last_line, $name
131 At the end of the run the profiler will output chunks that report
132 on the perl subroutines defined in all the files visited while
133 profiling. See also %DB::sub in perldebguts.
134 SUB_CALLERS => $fid, $line, $count, $incl_time, $excl_time, $reci_time,
136 $rec_depth, $name, $caller_name
137 At the end of the run the profiler will output chunks that report
138 on where subroutines were called from.
139 SRC_LINE => $fid, $line, $text
141 Used to reproduce the source code of the files and evals profiled.
142 Requires perl 5.8.9+ or 5.10.1+ or 5.12 or later. For earlier
143 versions of perl the source code of "perl -e '...'" and "perl -"
144 'files' is available if the "use_db_sub=1" option was used when
145 profiling.
146 PID_END => $pid, $end_time
148 The process with the given $pid is done running. See the
149 description of PID_START above.
150
152 Devel::NYTProf, Devel::NYTProf::Data
153
155 Gisle Aas
156
158 Copyright (C) 2008 by Adam Kaplan and The New York Times Company.
159 Copyright (C) 2008 by Tim Bunce, Ireland.
160 Copyright (C) 2008 by Gisle Aas
161 This library is free software; you can redistribute it and/or modify it
163 under the same terms as Perl itself, either Perl version 5.8.8 or, at
164 your option, any later version of Perl 5 you may have available.
165perl v5.12.2 2010-06-10 Devel::NYTProf::ReadStream(3)