Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Devel::NYTProf::ReadStUser(Contributed Perl DocumDevel::NYTProf::ReadStream(3)

NAME
       Devel::NYTProf::ReadStream - Read Devel::NYTProf	data file as a stream

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
       This module provide a low level interface for reading the contents of
       nytprof.out files (Devel::NYTProf data files) as	a stream of chunks.

       Currently the module only provide a single function:

       for_chunks( \&callback, %opts )
	   This	function will read the nytprof.out file	and invoke the given
	   callback function for each chunk in the file.

	   The first argument passed to	the callback is	the chunk tag.	The
	   rest	of the arguments passed	depend on the tag.  See	"Chunks" for
	   the details.	 The return value of the callback function is ignored.

	   The for_chunks() function will croak	if the file can't be opened or
	   if the file format isn't recognized.	 The global $. variable	is
	   made	to track the chunk sequence numbers and	can be inspected in
	   the callback.

	   The behaviour of the	function can be	modified by passing key/value
	   pairs after the callback. The contents of %opts are passed to "new"
	   in Devel::NYTProf::Data.

	   The function	is prototyped as "(&%)"	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:

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

   Chunks
       The nytprof.out 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
       for_chunks() function for version 4.0 of	the file format.

       Note that the chunks and	their arguments	are liable to change between
       versions	as NYTProf evolves.

       VERSION => $major, $minor
	   The first chunk in the file declare what version of the file	format
	   was used for	the current file.

       COMMENT => $text
	   This	chunk is just some textual content that	can be ignored.

       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	"ticks_per_sec"	that tell 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.

	   application => $string
	       The path	to the program that ran; same as $0 in the program
	       itself.

       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 NYTPROF env var, that were
	   effect during the profiling run.

       START_DEFLATE
	   This	chunk just say that from now on	all chunks have	been
	   compressed in the file.

       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.

       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.

       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.

SEE ALSO
       Devel::NYTProf, Devel::NYTProf::Data

AUTHOR
       Gisle Aas

COPYRIGHT AND LICENSE
	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.

perl v5.32.0			  2013-04-06	 Devel::NYTProf::ReadStream(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Devel::NYTProf::ReadStream&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help