This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Devel/Carp, Next: Devel/CoreStack, Prev: Des, Up: Module List warn of errors (from perspective of caller) ******************************************* NAME ==== carp - warn of errors (from perspective of caller) cluck - warn of errors with stack backtrace (not exported by default) croak - die of errors (from perspective of caller) confess - die of errors with stack backtrace SYNOPSIS ======== use Carp; croak "We're outta here!"; use Carp qw(cluck); cluck "This is how we got here!"; DESCRIPTION =========== The Carp routines are useful in your own modules because they act like die() or warn(), but report where the error was in the code they were called from. Thus if you have a routine Foo() that has a carp() in it, then the carp() will report the error as occurring where Foo() was called, not where carp() was called. Forcing a Stack Trace --------------------- As a debugging aid, you can force Carp to treat a croak as a confess and a carp as a cluck across all modules. In other words, force a detailed stack trace to be given. This can be very helpful when trying to understand why, or from where, a warning or error is being generated. This feature is enabled by 'importing' the non-existant symbol 'verbose'. You would typically enable it by saying perl -MCarp=verbose script.pl or by including the string `MCarp=verbose' in the `PERL5OPT' in this node environment variable.  File: pm.info, Node: Devel/CoreStack, Next: Devel/Coverage, Prev: Devel/Carp, Up: Module List try to generate a stack dump from a core file ********************************************* NAME ==== Devel::CoreStack - try to generate a stack dump from a core file SYNOPSIS ======== perl -MDevel::CoreStack -e 'stack' perl -MDevel::CoreStack -e 'stack("../myperl", "./mycore", "debugger")' DESCRIPTION =========== This module attempts to generate a stack dump from a core file by locating the best available debugger (if any) and running it with the appropriate arguments and command script.  File: pm.info, Node: Devel/Coverage, Next: Devel/DProf, Prev: Devel/CoreStack, Up: Module List Perl module to perform coverage analysis **************************************** NAME ==== Devel::Coverage - Perl module to perform coverage analysis SYNOPSIS ======== perl -d:Coverage script_name [ args ] DESCRIPTION =========== This software is still very early-alpha quality. Use the tool `coverperl' to analyze the files that result from running your scripts with coverage enabled. AUTHOR ====== Randy J. Ray SEE ALSO ======== *Note Devel/DProf: Devel/DProf,  File: pm.info, Node: Devel/DProf, Next: Devel/DebugInit, Prev: Devel/Coverage, Up: Module List a Perl code profiler ******************** NAME ==== Devel::DProf - a Perl code profiler SYNOPSIS ======== perl5 -d:DProf test.pl DESCRIPTION =========== The Devel::DProf package is a Perl code profiler. This will collect information on the execution time of a Perl script and of the subs in that script. This information can be used to determine which subroutines are using the most time and which subroutines are being called most often. This information can also be used to create an execution graph of the script, showing subroutine relationships. To profile a Perl script run the perl interpreter with the -d debugging switch. The profiler uses the debugging hooks. So to profile script test.pl the following command should be used: perl5 -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 `tmon.out'. A tool like dprofpp can be used to interpret the information which is in that profile. The following command will print the top 15 subroutines which used the most time: dprofpp To print an execution graph of the subroutines in the script use the following command: dprofpp -T Consult `dprofpp' in this node for other options. PROFILE FORMAT ============== The old profile is a text file which looks like this: #fOrTyTwO $hz=100; $XS_VERSION='DProf 19970606'; # All values are given in HZ $rrun_utime=2; $rrun_stime=0; $rrun_rtime=7 PART2 + 26 28 566822884 DynaLoader::import - 26 28 566822884 DynaLoader::import + 27 28 566822885 main::bar - 27 28 566822886 main::bar + 27 28 566822886 main::baz + 27 28 566822887 main::bar - 27 28 566822888 main::bar [....] The first line is the magic number. The second line is the hertz value, or clock ticks, of the machine where the profile was collected. The third line is the name and version identifier of the tool which created the profile. The fourth line is a comment. The fifth line contains three variables holding the user time, system time, and realtime of the process while it was being profiled. The sixth line indicates the beginning of the sub entry/exit profile section. The columns in *PART2* are: sub entry(+)/exit(-) mark app's user time at sub entry/exit mark, in ticks app's system time at sub entry/exit mark, in ticks app's realtime at sub entry/exit mark, in ticks fully-qualified sub name, when possible With newer perls another format is used, which may look like this: #fOrTyTwO $hz=10000; $XS_VERSION='DProf 19971213'; # All values are given in HZ $over_utime=5917; $over_stime=0; $over_rtime=5917; $over_tests=10000; $rrun_utime=1284; $rrun_stime=0; $rrun_rtime=1284; $total_marks=6; PART2 @ 406 0 406 & 2 main bar + 2 @ 456 0 456 - 2 @ 1 0 1 & 3 main baz + 3 @ 141 0 141 + 2 @ 141 0 141 - 2 @ 1 0 1 & 4 main foo + 4 @ 142 0 142 + & Devel::DProf::write @ 5 0 5 - & Devel::DProf::write (with high value of $ENV{PERL_DPROF_TICKS}). New `$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 `@' mark time passed from the previous `@' line. The lines starting with & introduce new subroutine id and show the package and the subroutine name of this id. Lines starting with +, - and * mark entering and exit of subroutines by ids, and `goto &subr'. The *old-style* +- and -lines are used to mark the overhead related to writing to profiler-output file. AUTOLOAD ======== When Devel::DProf finds a call to an `&AUTOLOAD' subroutine it looks at the $AUTOLOAD variable to find the real name of the sub being called. See `"Autoloading"', *Note Perlsub: (perl.info)perlsub,. ENVIRONMENT =========== `PERL_DPROF_BUFFER' sets size of output buffer in words. Defaults to 2**14. `PERL_DPROF_TICKS' sets number of ticks per second on some systems where a replacement for times() is used. Defaults to the value of `HZ' macro. `PERL_DPROF_OUT_FILE_NAME' sets the name of the output file. If not set, defaults to tmon.out. BUGS ==== Builtin functions cannot be measured by Devel::DProf. With a newer Perl DProf relies on the fact that the numeric slot of $DB::sub contains an address of a subroutine. Excessive manipulation of this variable may overwrite this slot, as in $DB::sub = 'current_sub'; ... $addr = $DB::sub + 0; will set this numeric slot to numeric value of the string `current_sub', i.e., to 0. This will cause a segfault on the exit from this subroutine. Note that the first assignment above does not change the numeric slot (it will mark it as invalid, but will not write over it). Mail bug reports and feature requests to the perl5-porters mailing list at `'. SEE ALSO ======== *Note Perl: (perl.info)perl,, `dprofpp' in this node, times(2)  File: pm.info, Node: Devel/DebugInit, Next: Devel/DebugInit/GDB, Prev: Devel/DProf, Up: Module List Perl extension for creating a debugger initialization files from C header file macros ************************************************************************************* NAME ==== Devel::DebugInit - Perl extension for creating a debugger initialization files from C header file macros SYNOPSIS ======== use Devel::DebugInit::GDB; my $gdb = new Devel::DebugInit::GDB 'filenames' => ["/my/path/to/library.h"]; $gdb->write("/my/path/to/library/.gdbinit"); DESCRIPTION =========== Devel::DebugInit is aimed at C/C++ developers who want access to C macro definitions from within a debugger. It provides a simple and automated way of creating debugger initialization files for a specific project. The initialization files created contain user-defined functions built from the macro definitions in the project's header files. By calling new(), the files specified by the 'filenames' parameter are parsed by the C preprocessor, and all macros #define'd in the file (and if desired, all macros #define'd by all #include'd files as well), will be parsed and expanded. By then calling the write() method, these macros can be written to an output file in the format of user-defined functions specific for your debugger. By automating the process, a new file can be created whenever the code of a project changes, and that way there will not be antiquated copies lying around to trap the unwary. NOTES ===== This module requires the use of one of the debugger-specific backend modules, such as Devel::DebugInit::GDB which is supplied with DebugInit. The backends supply the output routines which are specific for that debugger. This module also requires both the C::Scan and Data::Flow modules and will not function without them. WHY CARE? ========= Debugger initialization files can contain user-defined functions that make doing complicated or repetitive actions easier. Normally, from within the debugger a user can evaluate any C function call. But for a number of reasons, many projects use C preprocessor macros (#define statements) in place of an actual C function call. The use of macros instead of function calls is transparent during compilation, but most debuggers do not allow access to macros, and so the user must type in the code by hand each time s/he wants to use a macro, or must build an initialization file by hand. Retyping is tedious, but hand coding the initialization file may result in antiquated code when the project changes. By automating the process, I hope to alleviate a few headaches for developers. There are two types of macros: macros with arguments, e.g: #define min(x,y) ((x) < (y) ? (x) : (y)) and macros without arguments (simple macros), e.g. #define PI 3.14 Of the two types, macros with arguments are more useful from within a debugger, and so, printing of simple macros is turned off by default (but see `INTERNALS' in this node for how to turn them on). INTERNALS ========= For the casual user the defaults, and the three lines given in the `SYNOPSIS' in this node should be enough. But for the determined user, a few details of how things happen under the hood might be useful in customizing the output of this module. How Devel::DebugInit Parses Files --------------------------------- When new() is called to create an instance of a Devel::DebugInit, the following steps occur. The C preprocessor is invoked on the file with the 'macros only' flag set (this flag defaults to '-dM' and if this does not work on your system, change the value of $C::Scan::MACROS_ONLY and let the author know, and he will try and fix it :-). This lists all macros #define'd in the file PLUS all macros #define'd in all files #include'd by that file (both the system files and the user files "mystring.h"). This may include many more macros than is desired (not everybody really wants '_LINUX_C_LIB_VERSION_MAJOR' as a user defined function in their debugger...), so there are 3 mode flags defined that allow the user to control which macros are included: MACROS_ALL, MACROS_LOCAL, and MACROS_NONE. MACROS_ALL, MACROS_LOCAL, and MACROS_NONE ----------------------------------------- These flags can be used to control what macros go into the print tables that Devel::DebugInit uses to create the output file. The MACROS_ALL flag instructs DebugInit to included all macros of that type in the output table. To avoid printing out all of the system level macros that can get #include'd you can use the MACROS_LOCAL flag. This indicates that only macros actually #define'd in that file should be stored, and macros #define'd in other files which are #include'd into the file should NOT be stored (they are, however, still made available for expansion purposes). The MACROS_LOCAL flag is the default for macros with arguments. Finally, the MACROS_NONE flag indicates that no macros of that type should be put in the output table. The MACROS_NONE flag is the default for the simple macros. Output Tables and Lookup Tables ------------------------------- Devel::DebugInit has two separate groups of tables that it uses - lookup tables for expanding macro definitions and output tables for printing the fully expanded macros. The lookup tables always include all macros that a given file has access to, but the output tables may have many fewer. Because the user-defined functions of some debuggers can be very limited, Devel::DebugInit fully expands all macros stored in the output tables before writing them to a file. In this way, any macro which utilized other macros in its body will have those expanded in place. So by the end of the expansion process, all macros will be self defined and not rely on any other macro definition. Each macro in the output tables is expanded in this manner using the definitions in the lookup tables. Using separate lookup tables and output tables allows users to print out only those macros they care about while still be able to fully expand all macros. METHODS ======= new() ----- Returns a blessed reference to an instance of a Devel::DebugInit subclass. Each Devel::DebugInit subclass takes a list of option value pairs as optional arguments to new. Currently there are three recognized options 'filenames', 'macros_args', and 'macros_no_args'. The 'filenames' option controls which file is used for creating the output. The 'macros_args' option controls the level of output support for macros with arguments. The 'macro_no_args' option controls the level of output support for simple macros. For example, to make a .gdbinit file useful for debugging perl or perl XSUBs try the following: $gdb = new Devel::DebugInit::GDB 'filenames' => ["$Config{'archlib'}/CORE/perl.h"], 'macros_args' => $Devel::DebugInit::MACROS_ALL, 'macros_no_args' => $Devel::DebugInit::MACROS_ALL; $gdb->write(); When written, this will create a file that is about 110k in size and have about 1750 user-defined functions. So it may be useful to limit it in scope somewhat. It is not clear that simple macros are useful from within a debugger, so the default value for 'macros_no_args' is MACROS_NONE, and to avoid printing all system level macros, the default for 'macros_args' is MACROS_LOCAL. NOTE that by using MACROS_LOCAL, you will inhibit printing of all macros not #define'd in the file listed, both from local header files and system headers alike. To get around this multiple files can be included in the array ref for the 'filenames' option. Each files macros are added to a common lookup table, but only the macros #defined in each file are printed. So could do the following: $gdb = new Devel::DebugInit::GDB 'filenames' => ["$Config{'archlib'}/CORE/perl.h", "$Config{'archlib'}/CORE/sv.h", "$Config{'archlib'}/CORE/XSUB.h"], 'macros_args' => $Devel::DebugInit::MACROS_LOCAL, 'macros_no_args' => $Devel::DebugInit::MACROS_NONE; $gdb->write(); This reduces the output file to only 21k and 250 or so macros. write() =head2 write($filename) ------------------------------- This function is overloaded by each of the debugger specific subclasses to produce output recognized by that debugger. If $filename is not given, it defaults to something reasonable for that debugger. All macros in the output table for each macro type (macros with arguments and simple macros) will be printed if it passes scrutiny by the `scan()' in this node method. See the `INTERNALS' in this node section for more details on controlling what macros are stored in the print tables. scan() ------ The only other method of interest to users of this module is the scan() method which is also overloaded by each backend subclass. This method is called by write() to ascertain whether or not a given macro should be written out to the output file. By default, scan() stops undefined macros, blank macros (e.g. macros such as <#define VMS> which are usually just conditional compiler flags and of no use in a debugger), and macros with names that conflict with built-in debugger commands. Users desiring a very fine grained control over the output can override the builtin scan() with their own on a per need basis. For example: package myGDB; use Devel::DebugInit::GDB; @myGDB::ISA = (Devel::DebugInit::GDB); sub scan { my ($gdb,$key,$macro) = @_; #first give the superclass scan a chance return 0 unless $gdb->SUPER::scan(@_); # dont' print out any macros with a leading '_' return 0 if $macro =~ /^_/; # print the rest return 1; } AUTHOR ====== Jason E. Stewart, jasons@cs.unm.edu SEE ALSO ======== perl(1), Devel::DebugInit::GDB(3), C::Scan(3), and Data::Flow(3).  File: pm.info, Node: Devel/DebugInit/GDB, Next: Devel/FindAmpersand, Prev: Devel/DebugInit, Up: Module List Perl extension for creating .gdbinit file from C header file macros ******************************************************************* NAME ==== Devel::DebugInit::GDB - Perl extension for creating .gdbinit file from C header file macros SYNOPSIS ======== use Devel::DebugInit::GDB; use Config; my $g = new Devel::DebugInit::GDB "filename => $Config{'archlib'}/CORE/perl.h"; $g->write("~/perl5.00403/.gdbinit"); DESCRIPTION =========== This module is a backend for the GNU debugger, gdb, that is used together with the generic Devel::DebugInit front end to produce an initialization file for gdb. This module provides the output routines that are specific for gdb. See *Note Devel/DebugInit: Devel/DebugInit, for more information. METHODS ======= write() =head2 write($filename) ------------------------------- This method outputs the macros to $filename, which defaults to "./gdbinit". It first writes out any macros without arguments (if enabled, see `INTERNALS', *Note Devel/DebugInit: Devel/DebugInit, for more info), and then it writes any macros with arguments. scan($name,$macro) ------------------ This is used by the print function to determine if $macro should be printed or not. It returns 0 if the macro should NOT be printed. Currently, the method rejects undefined macros (this is possible if the user specified printing of local macros only), empty macros (typical compiler flags like -DDEBUG, or #define linux), macros whose names begin with '_', as well as any macro whose name is a built-in GDB command. This function can be overloaded by the user to more rigidly restrict the output of print. For example: package myGDB; use Devel::DebugInit::GDB; @myGDB::ISA = (Devel::DebugInit::GDB); sub scan { my ($gdb,$key,$macro) = @_; #first give the superclass scan a chance return 0 unless $gdb->SUPER::scan(@_); # dont' print out any macros beginning with 'rfsf_' return 0 if $macro =~ /^rfsf_/; # print the rest return 1; } AUTHOR ====== Jason E. Stewart, jasons@cs.unm.edu SEE ALSO ======== perl(1), Devel::DebugInit(3).  File: pm.info, Node: Devel/FindAmpersand, Next: Devel/Leak, Prev: Devel/DebugInit/GDB, Up: Module List Report exactly where Perl sawampersand ************************************** NAME ==== Devel::FindAmpersand - Report exactly where Perl sawampersand SYNOPSIS ======== use Devel::FindAmpersand (); DESCRIPTION =========== Use this module only during development and wait for your script to finish. It will report where your script gets infected by a sawampersand operation. SEE ALSO ======== Devel::SawAmpersand, B::FindAmpersand  File: pm.info, Node: Devel/Leak, Next: Devel/Memo, Prev: Devel/FindAmpersand, Up: Module List Utility for looking for perl objects that are not reclaimed. ************************************************************ NAME ==== Devel::Leak - Utility for looking for perl objects that are not reclaimed. SYNOPSIS ======== use Devel::Leak; ... setup code my $count = Devel::Leak::NoteSV($handle); ... code that may leak Devel::Leak::CheckSV($handle); DESCRIPTION =========== Devel::Leak has two functions `NoteSV' and `CheckSV'. `NoteSV' walks the perl internal table of allocated SVs (scalar values) - (which actually contains arrays and hashes too), and records their addresses in a table. It returns a count of these "things", and stores a pointer to the table (which is obtained from the heap using malloc()) in its argument. `CheckSV' is passed argument which holds a pointer to a table created by `NoteSV'. It re-walks the perl-internals and calls sv_dump() for any "things" which did not exist when `NoteSV' was called. It returns a count of the number of "things" now allocated. CAVEATS ======= Note that you need a perl built with -DDEBUGGING for sv_dump() to print anything, but counts are valid in any perl. If new "things" *have* been created, `CheckSV' may (also) report additional "things" which are allocated by the sv_dump() code. HISTORY ======= This little utility module was part of Tk until the variable renaming in perl5.005 made it clear that Tk had no business knowing this much about the perl internals. AUTHOR ====== Nick Ing-Simmons  File: pm.info, Node: Devel/Memo, Next: Devel/Modlist, Prev: Devel/Leak, Up: Module List memoize function calls ********************** NAME ==== *Devel::Memo* - memoize function calls SYNOPSIS ======== use Devel::Memo; sub number_cruncher { local(*tough)=new Devel::Memo sub($$@) { my ($arg1, $arg2, @others)=@_; ...calculate... return $some_val, $some_other_val; }, qw(-eq -equal -rest); my @result1=tough 17, [1, 2]; my @result2=tough 15, {foo => 1}, 'bar'; my @result3=tough 15, {foo => 1}, 'bar'; # Faster! } DESCRIPTION =========== A *Devel::Memo* object is defined as a subroutine reference to do some sort of calculation, together with a simple sort of prototype. The elements of the prototype may be: *-eq*, indicating a simple scalar argument (number or string); *-equal*, indicating an argument held in a scalar but possibly containing references, which will be examined in a recursive fashion; and *-rest*, meaning that zero or more extra arguments may appear, which should be compared both in number, and individually as with *-equal*. The object is just a blessed subroutine reference, so you can call it directly or assign it to a typeglob to make it look like any other function call. The difference is that the object maintains an internal cache of previous invocations and their results, and returns a previous result directly if a set of arguments is ever duplicated (as defined by the "prototype", above). The cache is freed when the object leaves scope. The implementing function is always called in array context; if the object is called in scalar context, the last value is returned. Implementation -------------- *FreezeThaw* is used. BUGS AND RESTRICTIONS ===================== There is no way to access instance data without changing this module, as it is completely private to the code reference. Overhead in creating the hash key, etc. will make this module not worth your while unless the operations to be memoized are fairly time-consuming. An XSUB version would be nice... Any bugs in *FreezeThaw* will presumably affect this module. The use of *FreezeThaw::safeFreeze* actually oversteps *FreezeThaw*'s documented guaranteed behavior in that it assumes that *safeFreeze* will return the same result for structurally equivalent arguments. Currently (*FreezeThaw* as in `ILYAZ/etext/etext1.6.2.tar.gz') this is in fact the case, and it will probably remain so. If not, performance will suffer but the results should not be incorrect. AUTHORS ======= Jesse Glick, *jglick@sig.bsh.com* SEE ALSO ======== `FreezeThaw(3P)' in this node. REVISION ======== X<$Format: "`$Source$' last modified $Date$, release $DevelMemoRelease$. $Copyright$"$> `Devel-Memo/lib/Devel/Memo.pm' last modified Wed, 10 Dec 1997 17:58:09 -0500, release 0.004. Copyright (c) 1997 Strategic Interactive Group. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Devel/Modlist, Next: Devel/OpProf, Prev: Devel/Memo, Up: Module List Perl extension to collect module use information ************************************************ NAME ==== Devel::Modlist - Perl extension to collect module use information SYNOPSIS ======== perl -d:Modlist script.pl DESCRIPTION =========== The *Devel::Modlist* utility is provided as a means by which to get a quick run-down on which libraries and modules are being utilized by a given script. Just as compiler systems like *gcc* provide dependancy information via switches such as -M, *Devel::Modlist* is intended to assist script authors in preparing dependancy information for potential users of their scripts. USAGE ===== Usage of *Devel::Modlist* is simple. The primary method of invocation is to use the -d option of Perl: perl -d:Modlist script.pl Alternately, one could use the -M option: perl -MDevel::Modlist script.pl In the case of this module, the two are identical save for the amount of typing (and option passing, see below). It is not recommended that this module be loaded directly by a script via the use keyword, as that would cause the dependancy reporting after every invocation until it was removed from the code. OPTIONS ======= The following options may be specified to the package on the command line. Current (as of July 2000) Perl versions (release version up to 5.6.0) cannot accept options to the `-d:' flag as with the -M flag. Thus, to pass an option one must use: perl -MDevel::Modlist=option1[,option2,...] Unfortunately, this inhibits the stop option detailed below. To use this option, an invocation of: perl -d:Modlist -MDevel::Modlist=option1[,option2,...] does the trick, as the first invocation puts the interpreter in debugging mode (necessary for stop to work) while the second causes the options to be parsed and recorded by *Devel::Modlist*. cpan Reduce the resulting list of modules by using the data maintained in the local CPAN configuration area. The CPAN module (see *Note CPAN: CPAN,) maintains a very thorough representation of the contents of the archive, on a per-module basis. Using this option means that if there are two or more modules that are parts of the same distribution, only one will be reported (the one with the shortest name). This is useful for generating a minimalist dependancy set that can in turn be fed to the CPAN install command to ensure that all needed modules are in fact present. cpandist This is identical to the option above, with the exception that it causes the reported output to be the CPAN filename rather than the module name in the standard Perl syntax. This can also be fed to the CPAN shell, but it can also be used by other front-ends as a path component in fetching the requisite file from an archive site. Since the name contains the version number, this behaves as though noversion (see below) was also set. If both cpan and cpandist are set, this option (cpandist) takes precedence. If path is also specified, this option again takes precedence. nocore Suppress the display of those modules that are a part of the Perl core. This is dependant on the Perl private library area not being an exact substring of the site-dependant library. The build process checks this for you prior to install. noversion Suppress the inclusion of version information with the module names. If a module has defined its version by means of the accepted standard of declaring a variable $VERSION in the package namespace, *Devel::Modlist* finds this and includes it in the report by default. Use this option to override that default. path Display the path and filename of each module instead of the module name. Useful for producing lists for later input to tools such as *rpm*. stop Exit before the first actual program line is executed. This provides for fetching the dependancy list without actually running the full program. This has a drawback: if the program uses any of require, eval or other such mechanisms to load libraries after the compilation phase, these will not be reported. AUTHOR ====== Randy J. Ray , using idea and prototype code provided by Tim Bunce SEE ALSO ======== perl(1).  File: pm.info, Node: Devel/OpProf, Next: Devel/Peek, Prev: Devel/Modlist, Up: Module List Profile the internals of a Perl program *************************************** NAME ==== Devel::OpProf - Profile the internals of a Perl program SYNOPSIS ======== use Devel::OpProf qw(profile print_stats); ... profile(1); # turn on profiling ... # code to be profiled profile(0); # turn off profiling ... print_stats; # print out operator statistics DESCRIPTION =========== This module lets perl keep a count of each internal operation in a program so that you can profile your Perl code. The following functions are exported. profile(FLAG) Turns profiling on if FLAG is non-zero, off if FLAG is zero. The operator profile counts are only incremented whilst profiling is on. stats Returns a reference to a hash containing the current profile counts. Each key in the hash is an operator description (e.g. "constant item", "addition" or "string comparison") and the corresponding value is the associated count. print_stats Prints a formatted, sorted list of all operators with non-zero counts to stdout. zero_stats Zeroes the profile counts of all operators. op_count Returns an array of the raw profiling counts (indexed by opcode). This is mainly for internal use but may be useful for internals hackers: functions in the Opcode module may be helpful here. BUGS ==== Part of the internal operations involved in statements such as `profile(1)' and `profile(0)' affect the profiling counts themselves. This should be unimportant if the code being profiled is non-trivial. AUTHOR ====== Malcolm Beattie, mbeattie@sable.ox.ac.uk.  File: pm.info, Node: Devel/Peek, Next: Devel/PreProcessor, Prev: Devel/OpProf, Up: Module List A data debugging tool for the XS programmer ******************************************* NAME ==== Devel::Peek - A data debugging tool for the XS programmer SYNOPSIS ======== use Devel::Peek; Dump( $a ); Dump( $a, 5 ); DumpArray( 5, $a, $b, ... ); mstat "Point 5"; DESCRIPTION =========== Devel::Peek contains functions which allows raw Perl datatypes to be manipulated from a Perl script. This is used by those who do XS programming to check that the data they are sending from C to Perl looks as they think it should look. The trick, then, is to know what the raw datatype is supposed to look like when it gets to Perl. This document offers some tips and hints to describe good and bad raw data. It is very possible that this document will fall far short of being useful to the casual reader. The reader is expected to understand the material in the first few sections of *Note Perlguts: (perl.info)perlguts,. Devel::Peek supplies a `Dump()' function which can dump a raw Perl datatype, and `mstat("marker")' function to report on memory usage (if perl is compiled with corresponding option). The function DeadCode() provides statistics on the data "frozen" into inactive CV. Devel::Peek also supplies `SvREFCNT()', `SvREFCNT_inc()', and `SvREFCNT_dec()' which can query, increment, and decrement reference counts on SVs. This document will take a passive, and safe, approach to data debugging and for that it will describe only the `Dump()' function. For format of output of mstats() see `Using `$ENV{PERL_DEBUG_MSTATS}', *Note Perldebug: (perl.info)perldebug,'. Function `DumpArray()' allows dumping of multiple values (useful when you need to analize returns of functions). The global variable $Devel::Peek::pv_limit can be set to limit the number of character printed in various string values. Setting it to 0 means no limit. EXAMPLES ======== The following examples don't attempt to show everything as that would be a monumental task, and, frankly, we don't want this manpage to be an internals document for Perl. The examples do demonstrate some basics of the raw Perl datatypes, and should suffice to get most determined people on their way. There are no guidewires or safety nets, nor blazed trails, so be prepared to travel alone from this point and on and, if at all possible, don't fall into the quicksand (it's bad for business). Oh, one final bit of advice: take *Note Perlguts: (perl.info)perlguts, with you. When you return we expect to see it well-thumbed. A simple scalar string ---------------------- Let's begin by looking a simple scalar which is holding a string. use Devel::Peek; $a = "hello"; Dump $a; The output: SV = PVIV(0xbc288) REFCNT = 1 FLAGS = (POK,pPOK) IV = 0 PV = 0xb2048 "hello"\0 CUR = 5 LEN = 6 This says `$a' is an SV, a scalar. The scalar is a PVIV, a string. Its reference count is 1. It has the `POK' flag set, meaning its current PV field is valid. Because POK is set we look at the PV item to see what is in the scalar. The \0 at the end indicate that this PV is properly NUL-terminated. If the FLAGS had been IOK we would look at the IV item. CUR indicates the number of characters in the PV. LEN indicates the number of bytes requested for the PV (one more than CUR, in this case, because LEN includes an extra byte for the end-of-string marker). A simple scalar number ---------------------- If the scalar contains a number the raw SV will be leaner. use Devel::Peek; $a = 42; Dump $a; The output: SV = IV(0xbc818) REFCNT = 1 FLAGS = (IOK,pIOK) IV = 42 This says `$a' is an SV, a scalar. The scalar is an IV, a number. Its reference count is 1. It has the `IOK' flag set, meaning it is currently being evaluated as a number. Because IOK is set we look at the IV item to see what is in the scalar. A simple scalar with an extra reference --------------------------------------- If the scalar from the previous example had an extra reference: use Devel::Peek; $a = 42; $b = \$a; Dump $a; The output: SV = IV(0xbe860) REFCNT = 2 FLAGS = (IOK,pIOK) IV = 42 Notice that this example differs from the previous example only in its reference count. Compare this to the next example, where we dump $b instead of `$a'. A reference to a simple scalar ------------------------------ This shows what a reference looks like when it references a simple scalar. use Devel::Peek; $a = 42; $b = \$a; Dump $b; The output: SV = RV(0xf041c) REFCNT = 1 FLAGS = (ROK) RV = 0xbab08 SV = IV(0xbe860) REFCNT = 2 FLAGS = (IOK,pIOK) IV = 42 Starting from the top, this says $b is an SV. The scalar is an RV, a reference. It has the `ROK' flag set, meaning it is a reference. Because ROK is set we have an RV item rather than an IV or PV. Notice that Dump follows the reference and shows us what $b was referencing. We see the same `$a' that we found in the previous example. Note that the value of RV coincides with the numbers we see when we stringify $b. The addresses inside RV() and IV() are addresses of `X***' structure which holds the current state of an SV. This address may change during lifetime of an SV. A reference to an array ----------------------- This shows what a reference to an array looks like. use Devel::Peek; $a = [42]; Dump $a; The output: SV = RV(0xf041c) REFCNT = 1 FLAGS = (ROK) RV = 0xb2850 SV = PVAV(0xbd448) REFCNT = 1 FLAGS = () IV = 0 NV = 0 ARRAY = 0xb2048 ALLOC = 0xb2048 FILL = 0 MAX = 0 ARYLEN = 0x0 FLAGS = (REAL) Elt No. 0 0xb5658 SV = IV(0xbe860) REFCNT = 1 FLAGS = (IOK,pIOK) IV = 42 This says `$a' is an SV and that it is an RV. That RV points to another SV which is a PVAV, an array. The array has one element, element zero, which is another SV. The field FILL above indicates the last element in the array, similar to `$#$a'. If `$a' pointed to an array of two elements then we would see the following. use Devel::Peek 'Dump'; $a = [42,24]; Dump $a; The output: SV = RV(0xf041c) REFCNT = 1 FLAGS = (ROK) RV = 0xb2850 SV = PVAV(0xbd448) REFCNT = 1 FLAGS = () IV = 0 NV = 0 ARRAY = 0xb2048 ALLOC = 0xb2048 FILL = 0 MAX = 0 ARYLEN = 0x0 FLAGS = (REAL) Elt No. 0 0xb5658 SV = IV(0xbe860) REFCNT = 1 FLAGS = (IOK,pIOK) IV = 42 Elt No. 1 0xb5680 SV = IV(0xbe818) REFCNT = 1 FLAGS = (IOK,pIOK) IV = 24 Note that `Dump' will not report all the elements in the array, only several first (depending on how deep it already went into the report tree). A reference to a hash --------------------- The following shows the raw form of a reference to a hash. use Devel::Peek; $a = {hello=>42}; Dump $a; The output: SV = RV(0xf041c) REFCNT = 1 FLAGS = (ROK) RV = 0xb2850 SV = PVHV(0xbd448) REFCNT = 1 FLAGS = () NV = 0 ARRAY = 0xbd748 KEYS = 1 FILL = 1 MAX = 7 RITER = -1 EITER = 0x0 Elt "hello" => 0xbaaf0 SV = IV(0xbe860) REFCNT = 1 FLAGS = (IOK,pIOK) IV = 42 This shows `$a' is a reference pointing to an SV. That SV is a PVHV, a hash. Fields RITER and EITER are used by ``each' in this node'. Dumping a large array or hash ----------------------------- The `Dump()' function, by default, dumps up to 4 elements from a toplevel array or hash. This number can be increased by supplying a second argument to the function. use Devel::Peek; $a = [10,11,12,13,14]; Dump $a; Notice that `Dump()' prints only elements 10 through 13 in the above code. The following code will print all of the elements. use Devel::Peek 'Dump'; $a = [10,11,12,13,14]; Dump $a, 5; A reference to an SV which holds a C pointer -------------------------------------------- This is what you really need to know as an XS programmer, of course. When an XSUB returns a pointer to a C structure that pointer is stored in an SV and a reference to that SV is placed on the XSUB stack. So the output from an XSUB which uses something like the T_PTROBJ map might look something like this: SV = RV(0xf381c) REFCNT = 1 FLAGS = (ROK) RV = 0xb8ad8 SV = PVMG(0xbb3c8) REFCNT = 1 FLAGS = (OBJECT,IOK,pIOK) IV = 729160 NV = 0 PV = 0 STASH = 0xc1d10 "CookBookB::Opaque" This shows that we have an SV which is an RV. That RV points at another SV. In this case that second SV is a PVMG, a blessed scalar. Because it is blessed it has the OBJECT flag set. Note that an SV which holds a C pointer also has the `IOK' flag set. The STASH is set to the package name which this SV was blessed into. The output from an XSUB which uses something like the T_PTRREF map, which doesn't bless the object, might look something like this: SV = RV(0xf381c) REFCNT = 1 FLAGS = (ROK) RV = 0xb8ad8 SV = PVMG(0xbb3c8) REFCNT = 1 FLAGS = (IOK,pIOK) IV = 729160 NV = 0 PV = 0 A reference to a subroutine --------------------------- Looks like this: SV = RV(0x798ec) REFCNT = 1 FLAGS = (TEMP,ROK) RV = 0x1d453c SV = PVCV(0x1c768c) REFCNT = 2 FLAGS = () IV = 0 NV = 0 COMP_STASH = 0x31068 "main" START = 0xb20e0 ROOT = 0xbece0 XSUB = 0x0 XSUBANY = 0 GVGV::GV = 0x1d44e8 "MY" :: "top_targets" FILE = "(eval 5)" DEPTH = 0 PADLIST = 0x1c9338 This shows that * the subroutine is not an XSUB (since START and ROOT are non-zero, and XSUB is zero); * that it was compiled in the package main; * under the name `MY::top_targets'; * inside a 5th eval in the program; * it is not currently executed (see DEPTH); * it has no prototype (`PROTOTYPE' field is missing). EXPORTS ======= `Dump', `mstat', `DeadCode', `DumpArray', `DumpWithOP' and `DumpProg' by default. Additionally available SvREFCNT, SvREFCNT_inc and SvREFCNT_dec. BUGS ==== Readers have been known to skip important parts of *Note Perlguts: (perl.info)perlguts,, causing much frustration for all. AUTHOR ====== Ilya Zakharevich ilya@math.ohio-state.edu Copyright (c) 1995-98 Ilya Zakharevich. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Author of this software makes no claim whatsoever about suitability, reliability, edability, editability or usability of this product, and should not be kept liable for any damage resulting from the use of it. If you can use it, you are in luck, if not, I should not be kept responsible. Keep a handy copy of your backup tape at hand. SEE ALSO ======== *Note Perlguts: (perl.info)perlguts,, and *Note Perlguts: (perl.info)perlguts,, again.  File: pm.info, Node: Devel/PreProcessor, Next: Devel/SawAmpersand, Prev: Devel/Peek, Up: Module List Module inlining and other Perl source manipulations *************************************************** NAME ==== Devel::PreProcessor - Module inlining and other Perl source manipulations SYNOPSIS ======== From a command line, sh> perl Devel/PreProcessor.pm -Flags sourcefile > targetfile Or in a Perl script, use Devel::PreProcessor qw( Flags ); select(OUTPUTFH); Devel::PreProcessor::parse_file( $source_pathname ); DESCRIPTION =========== This package processes Perl source files and outputs a modified version acording to several user-setable option flags, as detailed below. Each of the flag names listed below can be used as above, with a hyphen on the command line, or as one of the arguments in an import statement. Each of these flags are mapped to the scalar package variable of the same name. Includes If true, parse_file will attempt to replace require, use and no statements with inline declarations containg the source of the relevant library found in the current @INC. The resulting script should operate identically and no longer be dependant on external libraries (but see compatibility note below). If the corresponding file can not be located, the statements are left unchanged in the source; numeric perl version requirements are handled the same way. If a `use libs ...' statement is encountered in the source, the library path arguments are evaluated and pushed onto @INC at run-time to enable inclusion of libraries from these paths. Unless the file explicitly use's or require's AutoLoader, information after `__END__' is not included in the resultant file. Information after `__DATA__' is also discarded, except for the first, outermost source file. ShowFileBoundaries If true, comment lines will be inserted delimiting the start and end of each inlined file. StripPods If true, parse_file will not include POD from the source files. All groups of lines resembling the following will be discarded: =(pod|head1|head2) ... =cut StripBlankLines If true, parse_file will skip lines that are empty, or that contain only whitespace. StripComments If true, parse_file will not include full-line comments from the source files. Only lines that start with a pound sign are discarded; this behaviour might not match Perl's parsing rules in some cases, such as multiline strings. Conditionals If true, parse_file will utilize a simple conditional inclusion scheme, as follows. #__CONDITIONAL__ if expr ... #__CONDITIONAL__ endif The provided Perl expression is evaluated, and unless it is true, everything up to the next endif declaration is replaced with empty lines. In order to allow the default behavour to be provided when running the raw files, comment out lines in non-default branches with the following: #__CONDITIONAL__ ... Empty lines are used in place of skipped blocks to make line numbers come out evenly, but conditional use or require statements will throw the count off, as we don't pad by the size of the file that would have been in-lined. The conditional functionality can be combined with Perl's -s switch, which allows you to set flags on the command line, such as: perl -s Devel/PreProcessor.pm -Conditionals -Switch filter.test You can use any name for your switch, and the matching scalar variable will be set true; the following code will only be used if you supply the argument as shown below. #__CONDITIONAL__ if $Switch #__CONDITIONAL__ print "you hit the switch!\n"; #__CONDITIONAL__ endif EXAMPLES ======== To inline all used modules: perl -s Devel/PreProcessor.pm -Includes foo.pl > foo_complete.pl To count the lines of Perl source in a file, run the preprocessor from a shell with the following options perl -s Devel/PreProcessor.pm -StripComments -StripPods \ -StripBlankLines foo.pl | wc -l BUGS AND CAVEATS ================ Compatibility: Includes Libraries inlined with Includes may not be appropriate on another system; for example, if Config is inlined, the script may fail if run on a platform other than that on which it was built. This problem can be minimized by adjusting the search path to not include modules in the version- or architecture-specific library trees, but you will then need to ensure that those modules are available on the execution platform. Limitation: Pragmas While some pragmas are known to work, including use vars, problems may pop up with others. In particular, use strict and no strict pragmas are removed from the resulting source, because their scoping changes in a single-file context, usually with fatal results. Bug: Multi-line use statements not handled Should support newline in import blocks for multiline use statements. Limitation: Module __DATA__ contents lost Few modules place anything other than POD in a __DATA__ section, much less ever try to read from it, so this hasn't been a priority to fix. Limitation: binary files not included There's not much we can do about XSub/SO/PLL files. PREREQUISITES AND INSTALLATION ============================== This package should run on any standard Perl 5 installation. You may retrieve this package from the below URL: http://www.evoscript.com/dist/ To install this package, download and unpack the distribution archive, then: * `perl Makefile.PL' * make test * make install STATUS AND SUPPORT ================== This release of Devel::PreProcessor is intended primarily for public review and feedback, but is stable enough for production use. It has been tested in several environments and no major problems have been discovered, but it should be considered "beta" pending further feedback. Name DSLI Description -------------- ---- --------------------------------------------- Devel:: ::PreProcessor bdpf Module inlining and other Perl source manipulations Further information and support for this module is available at . Please report bugs or other problems to . AUTHORS AND COPYRIGHT ===================== Copyright 1998, 1999 Evolution Online Systems, Inc. You may use this software for free under the terms of the Artistic License. Contributors: M. Simon Cavalletto and Del Merritt , with Win32 debugging assistance from Randy Roy. Derived from filter.pl, as provided by ActiveWare