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

FreeBSD Manual Pages

  
 
  

home | help
Devel::SmallProf(3)   User Contributed Perl Documentation  Devel::SmallProf(3)

NAME
       Devel::SmallProf	- per-line Perl	profiler

SYNOPSIS
	       perl5 -d:SmallProf test.pl

DESCRIPTION
       The Devel::SmallProf profiler is	focused	on the time taken for a
       program run on a	line-by-line basis.  It	is intended to be as "small"
       in terms	of impact on the speed and memory usage	of the profiled
       program as possible and also in terms of	being simple to	use.  Those
       statistics are placed in	the file smallprof.out in the following
       format:

	       <num> <time> <ctime> <line>:<text>

       where <num> is the number of times that the line	was executed, <time>
       is the amount of	"wall time" (time according the	the clock on the wall
       vs. cpu time) spent executing it, <ctime> is the	amount of cpu time
       expended	on it and <line> and <text> are	the line number	and the	actual
       text of the executed line (read from the	file).

       The package uses	the debugging hooks in Perl and	thus needs the -d
       switch, so to profile test.pl, use the command:

	       perl5 -d:SmallProf test.pl

       Once the	script is done,	the statistics in smallprof.out	can be sorted
       to show which lines took	the most time.	The output can be sorted to
       find which lines	take the longest, either with the sort command:

	       sort -k 2nr,2 smallprof.out | less

       or a perl script:

	       open(PROF,"smallprof.out");
	       @sorted = sort {(split(/\s+/,$b))[2] <=>
			       (split(/\s+/,$a))[2]} <PROF>;
	       close PROF;
	       print join('',@sorted);

NOTES
       o   The "wall time" readings come from Time::HiRes and are reasonably
	   useful, at least on my system.  The cpu times come from the 'times'
	   built-in and	the granularity	is not necessarily as small as with
	   the wall time.  On some systems this	column may be useful.  On
	   others it may not.

       o   SmallProf does attempt to make up for its shortcomings by
	   subtracting a small amount from each	timing (null time
	   compensation).  This	should help somewhat with the accuracy.

       o   SmallProf depends on	the Time::HiRes	package	to do its timings.  It
	   claims to require version 1.20, but may work	with earlier versions,
	   depending on	your platform.

OPTIONS
       SmallProf has 4 variables which can be used during your script to
       affect what gets	profiled.

       $DB::drop_zeros (z)
	   If you do not wish to see lines which were never called, set	the
	   variable "$DB::drop_zeros = 1".  With "drop_zeros" set, SmallProf
	   can be used for basic coverage analysis.

       $DB::profile (p)
	   To turn off profiling for a time, insert a "$DB::profile = 0" into
	   your	code (profiling	may be turned back on with "$DB::profile =
	   1").	 All of	the time between profiling being turned	off and	back
	   on again will be lumped together and	reported on the	"$DB::profile
	   = 0"	line.  This can	be used	to summarize a subroutine call or a
	   chunk of code.

       %DB::packages
	   To only profile code	in a certain package, set the %DB::packages
	   array.  For example,	to see only the	code in	packages "main"	and
	   "Test1", do this:

		   %DB::packages = ( 'main' => 1, 'Test1' => 1 );

       $DB::grep_format	(g)
	   Generates output on a format	similar	to grep	easily parseable from
	   tools like Emacs (see below).

	   grep	format output appears as:

	     file name : line num : count : time : ctime : source

	   or

	     file name : line num : count : time : ctime : (eval n: line num) source

	   for code inside evals.

	   Times appear	in miliseconds.

       These variables can be put in a file called .smallprof in the current
       directory.  For example,	a .smallprof containing

	       $DB::drop_zeros = 1;
	       $DB::profile = 0;

       will set	SmallProf to not report	lines which are	never touched for any
       file profiled in	that directory and will	set profiling off initially
       (presumably to be turned	on only	for a small portion of code).

       Environment variable "SMALLPROF_CONFIG" can be also used	to set those
       flags, i.e:

	  SMALLPROF_CONFIG=zg perl -d:SmallProf	my_script.plx

       activates "drop_zeros" and "grep_format"	modes.

INSTALLATION
       Just the	usual

	       perl Makefile.PL
	       make
	       make test
	       make install

       and should install fine via the CPAN module.

BUGS
       Subroutine calls	are currently not under	the control of %DB::packages.
       This should not be a great inconvenience	in general.

       The handling of evals is	bad news.  This	is due to Perl's handling of
       evals under the -d flag.	 For certain evals, caller() returns '(eval
       n)' for the filename and	for others it doesn't.	For some of those
       which it	does, the array	"@{'_<filename'}" contains the code of the
       eval.  For others it doesn't.  Sometime,	when I've an extra tuit	or
       two, I'll figure	out why	and how	I can compensate for this.  (Note:
       5.6.0 made some debugging changes.  This	may now	be fixed, I'm not
       sure).

       SmallProf must be invoked from the command line.	 If it is included on
       the shebang line, the file in which it is included will not be visible
       in the symbol table.  Profiling will continue as	expected, but the
       contents	of the source lines will not be	listed.	 This is new as	of
       5.6.0.

       Comments, advice	and questions are welcome.  If you see inefficent
       stuff in	this module and	have a better way, please let me know.

EMACS/XEMACS HACK
       1.  Use the "DB::grep_format" flag to turn on grep like format, i.e.

	     SMALLPROF_CONFIG=g	perl -d:SmallProf myscript.pl

       2.  Tell	Emacs/XEmacs to	read smallprof.out as grep output:

	     M-x grep RET C-a C-k cat smallprof.out RET

       3.  Point and click to go to the	script hot spots!

AUTHOR
       Devel::SmallProf	was developed by Ted Ashton <ashted@cpan.org>. It is
       currently being maintained by Salvador FandiA+-o	<sfandino@yahoo.com>.

       SmallProf was developed from code originally posted to usenet by
       Philippe	Verdret	<philippe.verdret@sonovision-itep.fr>.	Special	thanks
       to Geoffrey Broadwell <habusan2@sprynet.com> for	his assistance on the
       Win32 platform and to Philippe for his patient assistance in testing
       and debugging.

COPYRIGHT AND LICENSE
       Copyright (c) 1997-2000 Ted Ashton

       Copyright (c) 2003-2007 Salvador	FandiA+-o

       This module is free software and	can be redistributed and/or modified
       under the same terms as Perl itself.

SEE ALSO
       Devel::FastProf is a simplified and much	faster version of this module.

       Devel::DProf, Time::HiRes.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 386:
	   Non-ASCII character seen before =encoding in	'FandiA+-o'. Assuming
	   CP1252

perl v5.32.0			  2007-05-11		   Devel::SmallProf(3)

NAME | SYNOPSIS | DESCRIPTION | NOTES | OPTIONS | INSTALLATION | BUGS | EMACS/XEMACS HACK | AUTHOR | COPYRIGHT AND LICENSE | SEE ALSO | POD ERRORS

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

home | help