Devel::NYTProf::ReadStUser(Contributed Perl DocumDevel::NYTProf::ReadStream(3)NAMEDevel::NYTProf::ReadStream - Read Devel::NYTProf data file as a stream
SYNOPSIS
use Devel::NYTProf::ReadStreamqw(for_chunks);
for_chunks {
my $tag = shift;
print "$tag\n";
# examine @_
....
}
# quickly dump content of a file
use Data::Dump;
for_chunks(\&dd);
DESCRIPTION
This module provide a low level interface for reading the contents of
nytprof.out files (Devel::NYTProf data files) as a stream of chunks.
Currently the module only provide a single function:
for_chunks( \&callback, %opts )
This function will read the nytprof.out file and invoke the given
callback function for each chunk in the file.
The first argument passed to the callback is the chunk tag. The
rest of the arguments passed depend on the tag. See "Chunks" for
the details. The return value of the callback function is ignored.
The for_chunks() function will croak if the file can't be opened or
if the file format isn't recognized. The global $. variable is
made to track the chunk sequence numbers and can be inspected in
the callback.
The behaviour of the function can be modified by passing key/value
pairs after the callback. The contents of %opts are passed to "new"
in Devel::NYTProf::Data.
The function is prototyped as "(&%)" which means that it can be
invoked with a bare block representing the callback function. In
that case there should be no comma before any options. Example:
for_chunk { say $_[0] } filename => "myprof.out";
Chunks
The nytprof.out file contains a sequence of tagged chunks that are
streamed out as the profiled program runs. This documents how the
chunks appear when presented to the callback function of the
for_chunks() function for version 4.0 of the file format.
Note that the chunks and their arguments are liable to change between
versions as NYTProf evolves.
VERSION => $major, $minor
The first chunk in the file declare what version of the file format
was used for the current file.
COMMENT => $text
This chunk is just some textual content that can be ignored.
ATTRIBUTE => $key, $value
This chunk type is repeated at the beginning of the file and used
to declare various facts about the profiling run. The only one
that's really interesting is "ticks_per_sec" that tell you how to
convert the $ticks values into seconds.
The attributes reported are:
basetime => $time
The time (epoch based) when the profiled perl process started.
It's the same value as $^T.
xs_version => $ver
The version of the Devel::NYTProf used for profiling.
perl_version => $ver
The version of perl used for profiling. This is a string like
"5.10.1".
clock_id => $num
What kind of clock was used to profile the program. Will be
"-1" for the default clock.
ticks_per_sec => $num
Divide the $ticks values in TIME_BLOCK/TIME_LINE by this number
to convert the time to seconds.
nv_size => 8
The $Config{nv_size} of the perl that wrote this file. This
value must match for the perl that reads the file as well.
application => $string
The path to the program that ran; same as $0 in the program
itself.
START_DEFLATE
This chunk just say that from now on all chunks have been
compressed in the file.
PID_START => $pid, $parent_pid, $start_time
The process with the given $pid starts running (under the
profiler).
Dates from the way forking used to be supported. Likely to get
deprecated when we get better support for tracking the time the sub
profiler and statement profiler were actually active. (Which is
needed to calculate percentages.)
NEW_FID => $fid, $eval_fid, $eval_line, $flags, $size, $mtime, $name
Files are represented by integers called 'fid' (File IDs) and this
chunk declares the mapping between these numbers and file path
names.
TIME_BLOCK => $ticks, $fid, $line, $block_line, $sub_line
TIME_LINE => $ticks, $fid, $line
A TIME_BLOCK or TIME_LINE chunk is output each time the execution
of the program leaves a statement.
DISCOUNT
Indicates that the next TIME_BLOCK or TIME_LINE should not
increment the "number of times the statement was executed". See the
'leave' option.
SUB_INFO => $fid, $first_line, $last_line, $name
At the end of the run the profiler will output chunks that report
on the perl subroutines defined in all the files visited while
profiling. See also %DB::sub in perldebguts.
SUB_CALLERS => $fid, $line, $count, $incl_time, $excl_time, $reci_time,
$rec_depth, $name, $caller_name
At the end of the run the profiler will output chunks that report
on where subroutines were called from.
SRC_LINE => $fid, $line, $text
Used to reproduce the source code of the files and evals profiled.
Requires perl 5.8.9+ or 5.10.1+ or 5.12 or later. For earlier
versions of perl the source code of "perl -e '...'" and "perl -"
'files' is available if the "use_db_sub=1" option was used when
profiling.
PID_END => $pid, $end_time
The process with the given $pid is done running. See the
description of PID_START above.
SEE ALSO
Devel::NYTProf, Devel::NYTProf::Data
AUTHOR
Gisle Aas
COPYRIGHT AND LICENSE
Copyright (C) 2008 by Adam Kaplan and The New York Times Company.
Copyright (C) 2008 by Tim Bunce, Ireland.
Copyright (C) 2008 by Gisle Aas
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself, either Perl version 5.8.8 or, at
your option, any later version of Perl 5 you may have available.
perl v5.14.2 2010-06-10 Devel::NYTProf::ReadStream(3)