Devel:...Stream(3pm)

📦
version 6.15 · 9 versions
, in ubuntu stonking

💖 Devel::NYTProf::ReadStream 💖

okay bestie, so this is a page from the User Contributed Perl Documentation crew, and it's all about Devel::NYTProf::ReadStream — the lil' module that lets you slurp up Devel::NYTProf data files as a stream of chunks. it's giving low-level plumbing and honestly? iconic. ✨

🌈 NAME 🌈

Devel::NYTProf::ReadStream — read a Devel::NYTProf data file as a stream. that's it, that's the whole vibe. 🦋

✨ SYNOPSIS ✨

use Devel::NYTProf::ReadStream qw(for_chunks);

for_chunks {
    my $tag = shift;
    print "$tag\n";
    # examine @_
    ....
}

# quickly dump content of a file
use Data::Dump;
for_chunks(\&dd);

🎀 DESCRIPTION 🎀

so this module hands you a low level interface for reading what's inside nytprof.out files (aka Devel::NYTProf data files), and it feeds them to you as a stream of chunks. no cap. 🫶

as of right now, the module only provides a single function:

  • for_chunks( \&callback, %opts ) — this function reads the nytprof.out file and invokes the callback function you gave it, once for every chunk in the file.

the first argument passed to the callback is the chunk tag. the rest of the arguments depend on the tag. go peek at "Chunks" for the deets. the return value of the callback function is ignored — it does not care, it does not want to know. 💅

for_chunks() will croak if the file can't be opened, or if the file format isn't recognized. also! the global $. variable is made to track the chunk sequence numbers, so you can inspect it inside your callback. cute, right? 😌

you can modify the behaviour of the function by passing key/value pairs after the callback. the contents of %opts get passed to "new" in Devel::NYTProf::Data.

the function is prototyped as "(&%)", which means you can invoke it with a bare block standing in for the callback function. in that case there should be no comma before any options. example time bestie:

for_chunk { say $_[0] } filename => "myprof.out";

👑 Chunks 👑

the nytprof.out file contains a sequence of tagged chunks that get streamed out while the profiled program runs. this here documents how the chunks show up when they're presented to the callback function of for_chunks(), for version 4.0 of the file format. 📼

⚠️ heads up queen — the chunks and their arguments are liable to change between versions as NYTProf evolves. so don't go building a forever home on top of them without checking. 💀
  • VERSION => $major, $minor — this is the first chunk in the file, and it declares what version of the file format was used for the current file. first chunk gets the mic. 🎤
  • COMMENT => $text — this chunk is just some textual content that you can totally ignore. it's the filler episode. 🙈
  • ATTRIBUTE => $key, $value — this chunk type repeats at the beginning of the file and is used to declare various facts about the profiling run. the only one that's really interesting is "ticks_per_sec", which tells 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. no mismatches bestie, fr fr.
  • application => $string — the path to the program that ran; same as $0 in the program itself.
  • OPTION => $key, $value — this chunk type also repeats at the beginning of the file, and it records the options that were in effect during the profiling run, e.g. the ones set via the NYTPROF env var. 📝
  • START_DEFLATE — this chunk just says that from now on, all chunks have been compressed in the file. zipped up, no takebacks. 🗜️
  • 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. every single departure, she logs it. 💅

  • 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. the receipts, basically. 🧾
  • 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. bye bye process 👋

🌸 SEE ALSO 🌸

  • Devel::NYTProf
  • Devel::NYTProf::Data

💜 AUTHOR 💜

Gisle Aas

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. open source royalty, periodt. 👑

okay that's the whole page bestie!! this one's from perl v5.42.3, dated 2026-08-20, and it's a User Contributed Perl Documentation page for the Devel::NYTProf::ReadStream (3pm) section. go read some chunks, you got this 💖✨🎀

📦 where this page comes from