.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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::Data 3pm"
.TH Devel::NYTProf::Data 3pm 2024-03-07 "perl v5.38.2" "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::Data \- Devel::NYTProf data loading and manipulation
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Devel::NYTProf::Data;
\&
\&  $profile = Devel::NYTProf::Data\->new( { filename => \*(Aqnytprof.out\*(Aq } );
\&
\&  $profile\->dump_profile_data();
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Reads a profile data file written by Devel::NYTProf, aggregates the
contents, and returns the results as a blessed data structure.
.PP
Access to the data should be via methods in this class to avoid breaking
encapsulation (and thus breaking your code when the data structures change in
future versions).
.PP
\&\fBNOTE\fR the documentation is out of date and may not be updated soon.
It's also likely that the API will change drastically in future.
It's possible, for example, that the data model will switch to use SQLite
and the http://metacpan.org/pod/ORLite ORM.
.PP
Let me know if you come to depend on a particular API and I'll try to preserve
it if practical.
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
.Vb 1
\&  $profile = Devel::NYTProf::Data\->new( );
\&
\&  $profile = Devel::NYTProf::Data\->new( {
\&    filename => \*(Aqnytprof.out\*(Aq, # default
\&    quiet    => 0,             # default, 1 to silence message
\&  } );
.Ve
.PP
Reads the specified file containing profile data written by Devel::NYTProf,
aggregates the contents, and returns the results as a blessed data structure.
.SS dump_profile_data
.IX Subsection "dump_profile_data"
.Vb 5
\&  $profile\->dump_profile_data;
\&  $profile\->dump_profile_data( {
\&      filehandle => \e*STDOUT,
\&      separator  => "",
\&  } );
.Ve
.PP
Writes the profile data in a reasonably human friendly format to the specified
\&\f(CW\*(C`filehandle\*(C'\fR (default STDOUT).
.PP
For non-trivial profiles the output can be very large. As a guide, there'll be
at least one line of output for each line of code executed, plus one for each
place a subroutine was called from, plus one per subroutine.
.PP
The default format is a Data::Dumper style whitespace-indented tree.
The types of data present can depend on the options used when profiling.
.PP
If \f(CW\*(C`separator\*(C'\fR is true then instead of whitespace, each item of data is
indented with the \fIpath\fR through the structure with \f(CW\*(C`separator\*(C'\fR used to
separate the elements of the path.
This format is especially useful for grep'ing and diff'ing.
.SS normalize_variables
.IX Subsection "normalize_variables"
.Vb 1
\&  $profile\->normalize_variables;
.Ve
.PP
Traverses the profile data structure and normalizes highly variable data, such
as the time, in order that the data can more easily be compared. This is mainly of
use to the test suite.
.PP
The data normalized is:
.IP \(bu 4
profile timing data: set to 0
.IP \(bu 4
subroutines: timings are set to 0
.IP \(bu 4
attributes, like basetime, xs_version, etc., are set to 0
.IP \(bu 4
filenames: path prefixes matching absolute paths in \f(CW@INC\fR are changed to "/.../"
.IP \(bu 4
filenames: eval sequence numbers, like "(re_eval 2)" are changed to 0
.SS subs_defined_in_file
.IX Subsection "subs_defined_in_file"
.Vb 1
\&  $subs_defined_hash = $profile\->subs_defined_in_file( $file, $include_lines );
.Ve
.PP
Returns a reference to a hash containing information about subroutines defined
in a source file.  The \f(CW$file\fR argument can be an integer file id (fid) or a file
path.
.PP
Returns undef if the profile contains no \f(CW\*(C`sub_subinfo\*(C'\fR data for the \f(CW$file\fR.
.PP
The keys of the returned hash are fully qualified subroutine names and the
corresponding value is a hash reference containing Devel::NYTProf::SubInfo
objects.
.PP
If \f(CW$include_lines\fR is true then the hash also contains integer keys
corresponding to the first line of the subroutine. The corresponding value is a
reference to an array. The array contains a hash ref for each of the
subroutines defined on that line, typically just one.
.SS file_line_range_of_sub
.IX Subsection "file_line_range_of_sub"
.Vb 1
\&  ($file, $fid, $first, $last, $fi) = $profile\->file_line_range_of_sub("main::foo");
.Ve
.PP
Returns the filename, fid, and first and last line numbers, and fileinfo object
for the specified subroutine (which must be fully qualified with a package name).
.PP
Returns an empty list if the subroutine name is not in the profile data.
.PP
The \f(CW$fid\fR return is the 'original' fid associated with the file the subroutine was created in.
.PP
The \f(CW$file\fR returned is the source file that defined the subroutine.
.PP
Subroutines that are implemented in XS have a line range of 0,0 and a possibly
unknown file (if NYTProf couldn't find a good match based on the package name).
.PP
Subroutines that were called but only returned via an exception may have a line
range of undef,undef if they're xsubs or were defined before NYTProf was enabled.
.SS resolve_fid
.IX Subsection "resolve_fid"
.Vb 1
\&  $fid = $profile\->resolve_fid( $file );
.Ve
.PP
Returns the integer \fIfile id\fR that corresponds to \f(CW$file\fR.
.PP
If \f(CW$file\fR can't be found and \f(CW$file\fR looks like a positive integer then it's
presumed to already be a fid and is returned. This is used to enable other
methods to work with fid or file arguments.
.PP
If \f(CW$file\fR can't be found but it uniquely matches the suffix of one of the files
then that corresponding fid is returned.
.SH "PROFILE DATA STRUTURE"
.IX Header "PROFILE DATA STRUTURE"
XXX
.SH LIMITATION
.IX Header "LIMITATION"
There's currently no way to merge profile data from multiple files.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Devel::NYTProf
.SH AUTHOR
.IX Header "AUTHOR"
\&\fBAdam Kaplan\fR, \f(CW\*(C`<akaplan at nytimes.com>\*(C'\fR
\&\fBTim Bunce\fR, <http://blog.timbunce.org>
\&\fBSteve Peters\fR, \f(CW\*(C`<steve at fisharerojo.org>\*(C'\fR
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
.Vb 2
\& Copyright (C) 2008 by Adam Kaplan and The New York Times Company.
\& Copyright (C) 2008,2009 by Tim Bunce, Ireland.
.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.