.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Devel::NYTProf::ReadStream 3pm"
.TH Devel::NYTProf::ReadStream 3pm "2018-11-02" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Devel::NYTProf::ReadStream \- Read Devel::NYTProf data file as a stream
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Devel::NYTProf::ReadStream qw(for_chunks);
\&
\&  for_chunks {
\&      my $tag = shift;
\&      print "$tag\en";
\&      # examine @_
\&      ....
\&  }
\&
\&  # quickly dump content of a file
\&  use Data::Dump;
\&  for_chunks(\e&dd);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provide a low level interface for reading the contents of
\&\fInytprof.out\fR files (Devel::NYTProf data files) as a stream of chunks.
.PP
Currently the module only provide a single function:
.ie n .IP "for_chunks( \e&callback, %opts )" 4
.el .IP "for_chunks( \e&callback, \f(CW%opts\fR )" 4
.IX Item "for_chunks( &callback, %opts )"
This function will read the \fInytprof.out\fR file and invoke the
given callback function for each chunk in the file.
.Sp
The first argument passed to the callback is the chunk tag.  The rest
of the arguments passed depend on the tag.  See \*(L"Chunks\*(R" for the
details.  The return value of the callback function is ignored.
.Sp
The \fBfor_chunks()\fR function will croak if the file can't be opened or if
the file format isn't recognized.  The global \f(CW$.\fR variable is made
to track the chunk sequence numbers and can be inspected in the
callback.
.Sp
The behaviour of the function can be modified by passing key/value
pairs after the callback. The contents of \f(CW%opts\fR are passed to
\&\*(L"new\*(R" in Devel::NYTProf::Data.
.Sp
The function is prototyped as \f(CW\*(C`(&%)\*(C'\fR 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:
.Sp
.Vb 1
\&  for_chunk { say $_[0] } filename => "myprof.out";
.Ve
.SS "Chunks"
.IX Subsection "Chunks"
The \fInytprof.out\fR 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
\&\fBfor_chunks()\fR function for version 4.0 of the file format.
.PP
\&\fINote that the chunks and their arguments are liable to change
between versions as NYTProf evolves.\fR
.ie n .IP "\s-1VERSION\s0 => $major, $minor" 4
.el .IP "\s-1VERSION\s0 => \f(CW$major\fR, \f(CW$minor\fR" 4
.IX Item "VERSION => $major, $minor"
The first chunk in the file declare what version of the file format
was used for the current file.
.ie n .IP "\s-1COMMENT\s0 => $text" 4
.el .IP "\s-1COMMENT\s0 => \f(CW$text\fR" 4
.IX Item "COMMENT => $text"
This chunk is just some textual content that can be ignored.
.ie n .IP "\s-1ATTRIBUTE\s0 => $key, $value" 4
.el .IP "\s-1ATTRIBUTE\s0 => \f(CW$key\fR, \f(CW$value\fR" 4
.IX Item "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 \f(CW\*(C`ticks_per_sec\*(C'\fR that tell you how to convert
the \f(CW$ticks\fR values into seconds.
.Sp
The attributes reported are:
.RS 4
.ie n .IP "basetime => $time" 4
.el .IP "basetime => \f(CW$time\fR" 4
.IX Item "basetime => $time"
The time (epoch based) when the profiled perl process started.
It's the same value as \f(CW$^T\fR.
.ie n .IP "xs_version => $ver" 4
.el .IP "xs_version => \f(CW$ver\fR" 4
.IX Item "xs_version => $ver"
The version of the Devel::NYTProf used for profiling.
.ie n .IP "perl_version => $ver" 4
.el .IP "perl_version => \f(CW$ver\fR" 4
.IX Item "perl_version => $ver"
The version of perl used for profiling.  This is a string like \*(L"5.10.1\*(R".
.ie n .IP "clock_id => $num" 4
.el .IP "clock_id => \f(CW$num\fR" 4
.IX Item "clock_id => $num"
What kind of clock was used to profile the program.  Will be \f(CW\*(C`\-1\*(C'\fR for
the default clock.
.ie n .IP "ticks_per_sec => $num" 4
.el .IP "ticks_per_sec => \f(CW$num\fR" 4
.IX Item "ticks_per_sec => $num"
Divide the \f(CW$ticks\fR values in \s-1TIME_BLOCK/TIME_LINE\s0 by this number to
convert the time to seconds.
.IP "nv_size => 8" 4
.IX Item "nv_size => 8"
The \f(CW$Config\fR{nv_size} of the perl that wrote this file.  This value
must match for the perl that reads the file as well.
.ie n .IP "application => $string" 4
.el .IP "application => \f(CW$string\fR" 4
.IX Item "application => $string"
The path to the program that ran; same as \f(CW$0\fR in the program itself.
.RE
.RS 4
.RE
.ie n .IP "\s-1OPTION\s0 => $key, $value" 4
.el .IP "\s-1OPTION\s0 => \f(CW$key\fR, \f(CW$value\fR" 4
.IX Item "OPTION => $key, $value"
This chunk type is repeated at the beginning of the file and used to record the
options, e.g. set via the \s-1NYTPROF\s0 env var, that were effect during the
profiling run.
.IP "\s-1START_DEFLATE\s0" 4
.IX Item "START_DEFLATE"
This chunk just say that from now on all chunks have been compressed
in the file.
.ie n .IP "\s-1PID_START\s0 => $pid, $parent_pid, $start_time" 4
.el .IP "\s-1PID_START\s0 => \f(CW$pid\fR, \f(CW$parent_pid\fR, \f(CW$start_time\fR" 4
.IX Item "PID_START => $pid, $parent_pid, $start_time"
The process with the given \f(CW$pid\fR starts running (under the profiler).
.Sp
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.)
.ie n .IP "\s-1NEW_FID\s0 => $fid, $eval_fid, $eval_line, $flags, $size, $mtime, $name" 4
.el .IP "\s-1NEW_FID\s0 => \f(CW$fid\fR, \f(CW$eval_fid\fR, \f(CW$eval_line\fR, \f(CW$flags\fR, \f(CW$size\fR, \f(CW$mtime\fR, \f(CW$name\fR" 4
.IX Item "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.
.ie n .IP "\s-1TIME_BLOCK\s0 => $ticks, $fid, $line, $block_line, $sub_line" 4
.el .IP "\s-1TIME_BLOCK\s0 => \f(CW$ticks\fR, \f(CW$fid\fR, \f(CW$line\fR, \f(CW$block_line\fR, \f(CW$sub_line\fR" 4
.IX Item "TIME_BLOCK => $ticks, $fid, $line, $block_line, $sub_line"
.PD 0
.ie n .IP "\s-1TIME_LINE\s0 => $ticks, $fid, $line" 4
.el .IP "\s-1TIME_LINE\s0 => \f(CW$ticks\fR, \f(CW$fid\fR, \f(CW$line\fR" 4
.IX Item "TIME_LINE => $ticks, $fid, $line"
.PD
A \s-1TIME_BLOCK\s0 or \s-1TIME_LINE\s0 chunk is output each time the execution of
the program leaves a statement.
.IP "\s-1DISCOUNT\s0" 4
.IX Item "DISCOUNT"
Indicates that the next \s-1TIME_BLOCK\s0 or \s-1TIME_LINE\s0 should not increment the
\&\*(L"number of times the statement was executed\*(R". See the 'leave' option.
.ie n .IP "\s-1SUB_INFO\s0 => $fid, $first_line, $last_line, $name" 4
.el .IP "\s-1SUB_INFO\s0 => \f(CW$fid\fR, \f(CW$first_line\fR, \f(CW$last_line\fR, \f(CW$name\fR" 4
.IX Item "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 \f(CW%DB::sub\fR in perldebguts.
.ie n .IP "\s-1SUB_CALLERS\s0 => $fid, $line, $count, $incl_time, $excl_time, $reci_time, $rec_depth, $name, $caller_name" 4
.el .IP "\s-1SUB_CALLERS\s0 => \f(CW$fid\fR, \f(CW$line\fR, \f(CW$count\fR, \f(CW$incl_time\fR, \f(CW$excl_time\fR, \f(CW$reci_time\fR, \f(CW$rec_depth\fR, \f(CW$name\fR, \f(CW$caller_name\fR" 4
.IX Item "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.
.ie n .IP "\s-1SRC_LINE\s0 => $fid, $line, $text" 4
.el .IP "\s-1SRC_LINE\s0 => \f(CW$fid\fR, \f(CW$line\fR, \f(CW$text\fR" 4
.IX Item "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 \f(CW\*(C`perl \-e \*(Aq...\*(Aq\*(C'\fR and \f(CW\*(C`perl \-\*(C'\fR 'files' is available
if the \f(CW\*(C`use_db_sub=1\*(C'\fR option was used when profiling.
.ie n .IP "\s-1PID_END\s0 => $pid, $end_time" 4
.el .IP "\s-1PID_END\s0 => \f(CW$pid\fR, \f(CW$end_time\fR" 4
.IX Item "PID_END => $pid, $end_time"
The process with the given \f(CW$pid\fR is done running.  See the description
of \s-1PID_START\s0 above.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Devel::NYTProf, Devel::NYTProf::Data
.SH "AUTHOR"
.IX Header "AUTHOR"
\&\fBGisle Aas\fR
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
.Vb 3
\& 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
.Ve
.PP
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.