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

FreeBSD Manual Pages

  
 
  

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

NAME
       Devel::Timer - Track and	report execution time for parts	of code

SYNOPSIS
	 use Devel::Timer;

	 my $t = Devel::Timer->new();

	 $t->mark("first db query");

	 ## do some work

	 $t->mark("second db query");

	 ## do some more work

	 $t->mark("end of second db query");

	 $t->report();

DESCRIPTION
       Devel::Timer allows developers to accurately time how long a specific
       piece of	code takes to execute.	This can be helpful in locating	the
       slowest parts of	an existing application.

       First, the Devel::Timer module is used and instantiated.

	 use Devel::Timer;

	 my $t = Devel::Timer->new();

       Second, markers are placed before and after pieces of code that need to
       be timed.  For this example, we are profiling the methods
       get_user_score()	and get_average_user_score().

	 $t->mark("first db query");
	 &get_user_score($user);

	 $t->mark("second db query");
	 &get_average_user_score();

       Finally,	at the end of the code that you	want to	profile, and end
       marker is place,	and a report is	generated on stderr.

	 $t->mark("END");
	 $t->report();

       Sample report:

	 Devel::Timer Report --	Total time: 0.3464 secs
	 Interval  Time	   Percent
	 ----------------------------------------------
	 02 -> 03  0.3001  86.63%  second db query -> END
	 01 -> 02  0.0461  13.30%  first db query -> second db query
	 00 -> 01  0.0002   0.07%  INIT	-> first db query

       The report is output using the method Devel::Timer::print() which
       currently just prints to	stderr.	 If you	want to	send the output	to a
       custom location you can override	the print() method.  The initialize()
       and shutdown() methods can also overridden if you want to open and
       close log files or database connections.

METHODS
   new
       Create a	new instance. No parameters are	processed.

   initialize
       Empty method. Can be implemented	in the subclass.

   mark(NAME)
       Set a timestamp with a NAME.

   print
       Prints to STDERR. Can be	overridden in the subclass.

   report
       Prints the report to STDOUT.  By	default	report() looks like this:

	 $t->report;

	 Devel::Timer Report --	Total time: 7.0028 secs
	 Interval  Time	   Percent
	 ----------------------------------------------
	 05 -> 06  3.0006  42.85%  something begin -> something	end
	 03 -> 04  2.0007  28.57%  something begin -> something	end
	 06 -> 07  1.0009  14.29%  something end -> END
	 01 -> 02  1.0004  14.29%  something begin -> something	end
	 00 -> 01  0.0000   0.00%  INIT	-> something begin
	 04 -> 05  0.0000   0.00%  something end -> something begin
	 02 -> 03  0.0000   0.00%  something end -> something begin

       Which is	great for small	or non-iterative programs, but if there's
       hundreds	of loops of "something begin ->	something end" the report gets
       very painful very quickly. :)

       In that scenario	you might find collapse	useful:

	 $t->report(collapse =>	1);

	 Devel::Timer Report --	Total time: 7.0028 secs
	 Count	   Time	   Percent
	 ----------------------------------------------
		3  6.0018  85.71%  something begin -> something	end
		1  1.0009  14.29%  something end -> END
		2  0.0001   0.00%  something end -> something begin
		1  0.0000   0.00%  INIT	-> something begin

       The stats for all combinations of labels	are added together.

       We also accept a	sort_by	parameter. By default the report is sorted by
       total time spent	descending (like the default report()),	but you	can
       sort by count descending	instead	if you want:

	 $t->report(collapse =>	1, sort_by => 'count');

	 Devel::Timer Report --	Total time: 7.0028 secs
	 Count	   Time	   Percent
	 ----------------------------------------------
		3  6.0018  85.71%  something begin -> something	end
		2  0.0001   0.00%  something end -> something begin
		1  0.0000   0.00%  INIT	-> something begin
		1  1.0009  14.29%  something end -> END

   get_stats
       Returns the accumulated statistics for a	specific a combination of
       mark()'s	that have occurred while your program ran.  These values are
       the exact same statistics that report() prints. get_stats() simply
       returns them to you so you can do something creative with them.

       For example, to get the cumulative stats	for every time your program
       has specifically	moved from mark("X") to	mark("Y"), you can run this:

	 my ($time, $percent, $count) =	$t->get_stats("X", "Y");

       $time is	the total number of seconds elapsed between "X"	and "Y".

       $percent	is the percentage of total program run time that you have
       spent between "X" and "Y".

       $count is the number of times your program has moved from "X" to	"Y".

   shutdown
       Empty method. Can be implemented	in subclass.

SUBCLASSING
       e.g.

       package MyTimer;

       use strict; use Devel::Timer; use vars qw(@ISA);

       @ISA = ("Devel::Timer");

       sub initialize {
	   my $log = "/tmp/timer.log";
	   open(LOG, ">>$log") or die("Unable to open [$log] for writing."); }

       sub print {
	   my($self, $msg) = @_;
	   print LOG $msg . "\n"; }

       sub shutdown {
	   close LOG; }

       You would then use the new module MyTimer exactly as you	would use
       Devel::Timer.

	 use MyTimer;
	 my $t = MyTimer->new();
	 $t->mark("about to do x");
	 $t->mark("about to do y");
	 $t->mark("done	y");
	 $t->report();

TO DO
       Devel::Timer does not currently do any reporting	or statistics of any
       kind based on nested trees of mark() calls. So if your program runs
       these mark() calls:

	 A
	   B, C
	   B, C
	 D
	 E

       Devel::Timer never tells	you anything about how much time you spent
       moving from A to	D. Depth aware reporting might be an interesting
       project to tackle.

SEE ALSO
       Time::HiRes

COPYRIGHT
       Jason Moore

       This is free software.  It is licensed under the	same terms as Perl
       itself.

AUTHOR
	 Author:      Jason Moore - jmoore@sober.com (no longer	valid)
	 Maintainer:  Gabor Szabo - gabor@pti.co.il
	 Contributor: Jay Hannah  - jay@jays.net

perl v5.32.0			  2007-08-12		       Devel::Timer(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SUBCLASSING | TO DO | SEE ALSO | COPYRIGHT | AUTHOR

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

home | help