Devel::Probe - Quick & dirty code probes for Perl
Version 0.000005
use Devel::Probe; ... Devel::Probe::trigger(sub { my ($file, $line) = @_; # probe logic }); Devel::Probe::config(%config); ... Devel::Probe::enable(); ... Devel::Probe::disable();
Use this module to allow the possibility of creating probes for some lines in your code.
The probing code is installed when you import the module, but it is disabled. In these conditions, the probe code is light enough that it should cause no impact at all in your CPU usage; an impact might be noticed when you enable the module and configure some probes, particularly depending on the frequency with which those probes will be triggered, and how heavy the trigger callback turns out to be.
trigger(\&coderef)
Specify a piece of Perl code that will be called for every probe that triggers.
config(\%config)
Specify a configuration for the module, including what lines in your code will cause probes to be triggered. This call will always disable the module as a first action, so you always need to explicitly enable it again, either from the configuration itself or in a further call to enable().
enable()
add_probe(file, line, type)
Manually add a probe. This is what gets called from config() when adding probes; please see the CONFIGURATION example for more information.
config()
enable() / disable() / is_enabled()
disable()
is_enabled()
Dynamically activate and deactivate probing, and check this status.
install() / remove() / is_installed()
install()
remove()
is_installed()
Install or remove the probe handling code, and check this status. When you import the module, install() is called automatically for you.
clear()
Remove all probes.
dump()
Print all probes to stderr.
An example configuration hash looks like this:
my %config = ( actions => [ { action => 'disable' }, { action => 'clear' }, { action => 'define' ... }, { action => 'dump' }, { action => 'enable' }, ], );
Possible actions are:
disable: disable probing.
disable
clear: clear current list of probes.
clear
dump: dump current list of probes to stderr.
dump
enable: enable probing.
enable
define: define a new probe. A full define action looks like:
define
my %define = ( action => 'define', type => PROBE_TYPE, file => 'file_name', lines => [ 10, 245, 333 ], );
The type field is optional and its default value is once. Possible values are:
once
once: the probe will trigger once and then will be destroyed right after that. This default makes it more difficult to overwhelm your system with too much probing, unless you explicitly request a different type of probe.
permanent: the probe will trigger every time that line of code is executed.
permanent
This will invoke the callback defined with the call to trigger(), the first time line 21 executes, taking advantage of PadWalker to dump the local variables. After that first execution, that particular probe will not be triggered anymore. For line 22, every time that line is executed the probe will be triggered.
trigger()
PadWalker
# line 1 of s.pl use Data::Dumper qw(Dumper); use PadWalker qw(peek_my); use Devel::Probe; Devel::Probe::trigger(sub { my ($file, $line) = @_; say Dumper(peek_my(1)); # 1 to jump up one level in the stack; }); my %config = ( actions => [ { action => 'define', file => 's.pl', lines => [ 21 ] }, { action => 'define', file => 's.pl', type = 'permanent', lines => [ 22 ] }, ], ); Devel::Probe::config(\%config); Devel::Probe::enable(); my $count; while (1) { $count++; # line 21 my $something_inside_the_loop = $count * 2; # line 22 sleep 5; } Devel::Probe::disable();
For files found directly by the Perl interpreter, the file name in the probe definition will usually be a relative path name; for files that are found through the PERL5LIB environment variable, the file name in the probe definition will usually be a full path name.
One typical use case would be to have a signal handler associated with a specific signal, which when triggered would disable the module, read the configuration from a given place, reconfigure the module accordingly and then enable it. Similarly, this kind of control can be implemented using remote endpoints to deal with reconfiguring, disabling and enabling the module.
Probes are stored in a hash of file names; per file name, there is a hash of line numbers (with the probe type as a value). It is likely this can be made more performant with a better data structure, but that needs profiling.
Gonzalo Diethelm gonzus AT cpan DOT org
gonzus AT cpan DOT org
Ben Tyler btyler AT cpan DOT org
btyler AT cpan DOT org
To install Devel::Probe, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Devel::Probe
CPAN shell
perl -MCPAN -e shell install Devel::Probe
For more information on module installation, please visit the detailed CPAN module installation guide.