++ed by:

75 PAUSE users
46 non-PAUSE users.

Tim Bunce
and 1 contributors


Devel::NYTProf::Data - Devel::NYTProf data loading and manipulation


  use Devel::NYTProf::Data;

  $profile = Devel::NYTProf::Data->new( { filename => 'nytprof.out' } );



Reads a profile data file written by Devel::NYTProf, aggregates the contents, and returns the results as a blessed data structure.

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).

XXX Currently the documentation is out of date as this module is evolving rapidly.



  $profile = Devel::NYTProf::Data->new( { filename => 'nytprof.out' } );

Reads the specified file containing profile data written by Devel::NYTProf, aggregates the contents, and returns the results as a blessed data structure.


  $profile->dump_profile_data( {
      filehandle => \*STDOUT,
      separator  => "",
  } );

Writes the profile data in a reasonably human friendly format to the sepcified filehandle (default STDOUT).

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.

The default format is a Data::Dumper style whitespace-indented tree. The types of data present can depend on the options used when profiling.

If separator is true then instead of whitespace, each item of data is indented with the path through the structure with separator used to separarate the elements of the path. This format is especially useful for grep'ing and diff'ing.



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 used, for example, by the test suite.

The data normalized is:

  • profile timing data: set to 0

  • subroutines: timings are set to 0

  • attributes, like basetime, xs_version, etc., are set to 0

  • filenames: path prefixes matching absolute paths in @INC are changed to "/.../"

  • filenames: eval sequence numbers, like "(re_eval 2)" are changed to 0


  $subs_defined_hash = $profile->subs_defined_in_file( $file, $include_lines );

Returns a reference to a hash containing information about subroutines defined in a source file. The $file argument can be an integer file id (fid) or a file path.

Returns undef if the profile contains no sub_subinfo data for the $file.

The keys of the returned hash are fully qualified subroutine names and the corresponding value is a hash reference containing Devel::NYTProf::SubInfo objects.

If $include_lines 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.


  @subname = $profile->subname_at_file_line($file, $line_number);
  $subname = $profile->subname_at_file_line($file, $line_number);


  ($file, $fid, $first, $last) = $profile->file_line_range_of_sub("main::foo");

Returns the filename, fid, and first and last line numbers for the specified subroutine (which must be fully qualified with a package name).

Returns an empty list if the subroutine name is not in the profile data.

The $fid return is the 'original' fid associated with the file the subroutine was created in.

The $file returned is the source file that defined the subroutine.

Where is a subroutine is defined within a string eval, for example, the fid will be the pseudo-fid for the eval, and the $file will be the filename that executed the eval.

Subroutines that are implemented in XS have a line range of 0,0 and currently don't have an associated file.


  $fid = $profile->resolve_fid( $file );

Returns the integer file id that corresponds to $file.

If $file can't be found and $file 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.

If $file can't be found but it uniquely matches the suffix of one of the files then that corresponding fid is returned.


  $line_calls_hash = $profile->line_calls_for_file( $file );

Returns a reference to a hash containing information about subroutine calls made at individual lines within a source file. The $file argument can be an integer file id (fid) or a file path. Returns undef if no subroutine calling information is available.

The keys of the returned hash are line numbers. The values are references to hashes with fully qualified subroutine names as keys. Each hash value is an reference to an array containing an integer call count (how many times the sub was called from that line of that file) and an inclusive time (how much time was spent inside the sub when it was called from that line of that file).

For example, if the following was line 42 of a file foo.pl:

  ++$wiggle if foo(24) == bar(42);

that line was executed once, and foo and bar were imported from pkg1, then $profile->line_calls_for_file( 'foo.pl' ) would return something like:

      42 => {
          'pkg1::foo' => [ 1, 0.02093 ],
          'pkg1::bar' => [ 1, 0.00154 ],






Adam Kaplan, <akaplan at nytimes.com> Tim Bunce, http://www.tim.bunce.name and http://blog.timbunce.org Steve Peters, <steve at fisharerojo.org>


 Copyright (C) 2008 by Adam Kaplan and The New York Times Company.
 Copyright (C) 2008 by Tim Bunce, Ireland.

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.