$VERSION++ for all the non-dual life modules in ext/ that

[perl5.git] / ext / Devel / DProf / DProf.pm

diff --git a/ext/Devel/DProf/DProf.pm b/ext/Devel/DProf/DProf.pm
index 4c43f4d..7405b78 100644 (file)
--- a/ext/Devel/DProf/DProf.pm
+++ b/ext/Devel/DProf/DProf.pm
@@ -1,4 +1,4 @@
-require 5.003;
+use 5.006_001;
 
 =head1 NAME
 
@@ -6,7 +6,7 @@ Devel::DProf - a Perl code profiler
 
 =head1 SYNOPSIS
 
-       perl5 -d:DProf test.pl
+       perl -d:DProf test.pl
 
 =head1 DESCRIPTION
 
@@ -21,7 +21,7 @@ To profile a Perl script run the perl interpreter with the B<-d> debugging
 switch.  The profiler uses the debugging hooks.  So to profile script
 F<test.pl> the following command should be used:
 
-       perl5 -d:DProf test.pl
+       perl -d:DProf test.pl
 
 When the script terminates (or when the output buffer is filled) the
 profiler will dump the profile information to a file called
@@ -111,14 +111,39 @@ New C<$over_*> values show the measured overhead of making $over_tests
 calls to the profiler These values are used by the profiler to
 subtract the overhead from the runtimes.
 
-The lines starting with C<@> mark time passed from the previous C<@>
-line.  The lines starting with C<&> introduce new subroutine I<id> and
-show the package and the subroutine name of this id.  Lines starting
-with C<+>, C<-> and C<*> mark entering and exit of subroutines by
-I<id>s, and C<goto &subr>.
+Lines starting with C<@> mark the amount of time passed since the
+previous C<@> line.  The numbers following the C<@> are integer tick
+counts representing user, system, and real time.  Divide these numbers
+by the $hz value in the header to get seconds.
 
-The I<old-style> C<+>- and C<->-lines are used to mark the overhead
-related to writing to profiler-output file.
+Lines starting with C<&> map subroutine identifiers (an integer) to
+subroutine packages and names.  These should only occur once per
+subroutine.
+
+Lines starting with C<+> or C<-> mark normal entering and exit of
+subroutines.  The number following is a reference to a subroutine
+identifier.
+
+Lines starting with C<*> mark where subroutines are entered by C<goto
+&subr>, but note that the return will still be marked as coming from
+the original sub.  The sequence might look like this:
+
+       + 5
+       * 6
+       - 5
+
+Lines starting with C</> is like C<-> but mark where subroutines are
+exited by dying.  Example:
+
+       + 5
+       + 6
+       / 6
+       / 5
+
+Finally you might find C<@> time stamp marks surrounded by C<+ &
+Devel::DProf::write> and C<- & Devel::DProf::write> lines.  These 3
+lines are outputted when printing of the mark above actually consumed
+measurable time.
 
 =head1 AUTOLOAD
 
@@ -133,6 +158,9 @@ C<PERL_DPROF_BUFFER> sets size of output buffer in words.  Defaults to 2**14.
 C<PERL_DPROF_TICKS> sets number of ticks per second on some systems where
 a replacement for times() is used.  Defaults to the value of C<HZ> macro.
 
+C<PERL_DPROF_OUT_FILE_NAME> sets the name of the output file.  If not set,
+defaults to tmon.out.
+
 =head1 BUGS
 
 Builtin functions cannot be measured by Devel::DProf.
@@ -151,6 +179,24 @@ from this subroutine.  Note that the first assignment above does not
 change the numeric slot (it will I<mark> it as invalid, but will not
 write over it).
 
+Another problem is that if a subroutine exits using goto(LABEL),
+last(LABEL) or next(LABEL) then perl may crash or Devel::DProf will die
+with the error:
+
+   panic: Devel::DProf inconsistent subroutine return
+
+For example, this code will break under Devel::DProf:
+
+   sub foo {
+     last FOO;
+   }
+   FOO: {
+     foo();
+   }
+
+A pattern like this is used by Test::More's skip() function, for
+example.  See L<perldiag> for more details.
+
 Mail bug reports and feature requests to the perl5-porters mailing list at
 F<E<lt>perl5-porters@perl.orgE<gt>>.
 
@@ -182,11 +228,11 @@ sub DB {
 #      print "nonXS DBDB\n";
 }
 
-require DynaLoader;
-@Devel::DProf::ISA = 'DynaLoader';
-$Devel::DProf::VERSION = '19990108'; # this version not authorized by
-                                    # Dean Roehrich. See "Changes" file.
+use XSLoader ();
+
+$Devel::DProf::VERSION = '20080331.00';  # this version not authorized by
+                                        # Dean Roehrich. See "Changes" file.
 
-bootstrap Devel::DProf $Devel::DProf::VERSION;
+XSLoader::load 'Devel::DProf', $Devel::DProf::VERSION;
 
 1;