Devel:...::Data(3pm)

📦
version 6.15 · 9 versions
, in ubuntu stonking

🌸 Devel::NYTProf::Data — the manual page, but make it a vibe ✨

okay bestie, so this is Devel::NYTProf::Data(3pm) — part of the User Contributed Perl Documentation, and it's literally the lil data-loading + data-manipulation bestie for Devel::NYTProf. let's get into it 🫶

💖 NAME 💖

Devel::NYTProf::Data — Devel::NYTProf data loading and manipulation. that's it, that's the whole name. iconic.

✨ SYNOPSIS ✨

use Devel::NYTProf::Data;

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

$profile->dump_profile_data();

like… you load it, you dump it, you go live your life. simple as that 💅

🦋 DESCRIPTION 🦋

So what this thing does is read a profile data file that was written by Devel::NYTProf, aggregates all the contents, and hands the results back to you as a blessed data structure. yes, blessed. it's giving holy. 🎀

You should access the data through the methods in this class, okay? like, please. that's how you avoid breaking encapsulation — and also how you avoid breaking your own code when these data structures change in future versions. future-proofing, no cap.

NOTE: the documentation is out of date and may not be updated soon 😭 and it's also likely that the API will change drastically in future. Like, it's possible the data model will switch to use SQLite and the http://metacpan.org/pod/ORLite ORM. so… heads up. fr fr.

Let the author know if you come to depend on a particular API and they'll try to preserve it if practical. so speak up, bestie 🗣️

👑 METHODS 👑

🌟 new

$profile = Devel::NYTProf::Data->new( );

$profile = Devel::NYTProf::Data->new( {
  filename => 'nytprof.out', # default
  quiet    => 0,             # default, 1 to silence message
} );

Reads the specified file containing profile data written by Devel::NYTProf, aggregates the contents, and gives you back the results as a blessed data structure. the main character constructor energy 🌈

🌟 dump_profile_data

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

Writes the profile data out in a reasonably human friendly format to the specified "filehandle" (defaults to STDOUT). cute and readable, we love that 🍓

⚠️ real talk: 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. that's a LOT of lines. hydrate before you dump 💀

The default format is a Data::Dumper style whitespace-indented tree. The types of data present can depend on the options used when profiling — so it's a lil build-your-own-situation.

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

🌟 normalize_variables

$profile->normalize_variables;

Traverses the profile data structure and normalizes highly variable data — like the time — so that the data can more easily be compared. This is mainly of use to the test suite. basically it's the "make the chaos comparable" button ✨

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

periodt. everything normalized, everything calm 🧘

🌟 subs_defined_in_file

$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. flexible, love that for us 💜

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. nested hashes upon nested hashes, it's giving onion 🧅

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. That array contains a hash ref for each of the subroutines defined on that line — typically just one. usually just the one lil guy, but sometimes more 👯

🌟 file_line_range_of_sub

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

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 — so main::foo, not just foo, okay bestie?).

Returns an empty list if the subroutine name is not in the profile data. nothing there? nothing back. fair. 🙈

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.

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). XS said "no location for you" 💅

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. chaotic lil edge case, noted. 😭

🌟 resolve_fid

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

Returns the integer file id that corresponds to $file. number go brrr 🔢

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 — so it just accepts both and figures it out. versatile icon.

If $file can't be found but it uniquely matches the suffix of one of the files then that corresponding fid is returned. suffix matching, she's clever like that 🌸

🌈 PROFILE DATA STRUTURE 🌈

XXX

(no literally, the page just says XXX. the docs are underselling it. mysterious. we respect the mystery though 🕵️)

💀 LIMITATION 💀

There's currently no way to merge profile data from multiple files. so if you wanted to smoosh them together… you can't. tragic. maybe one day. 😔

📚 SEE ALSO 📚

  • Devel::NYTProf

💜 AUTHOR 💜

Adam Kaplan, "<akaplan at nytimes.com>" — Tim Bunce, http://blog.timbunce.org — Steve Peters, "<steve at fisharerojo.org>"

three absolute legends, no notes 👑

 Copyright (C) 2008 by Adam Kaplan and The New York Times Company.
 Copyright (C) 2008,2009 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. free as in, go wild, but read the license bestie 🫶

and that's the whole page! slay 💖 this was Devel:...::Data(3pm) from the perl v5.42.3 docs, dated 2026-08-20 — see you in the next manpage, mwah 😘✨

📦 where this page comes from