NAME

Devel::Probe - Quick & dirty code probes for Perl

VERSION

Version 0.000003

SYNOPSIS

    use Devel::Probe;
    # or
    use Devel::Probe (check_config_file => 0);
    # or
    use Devel::Probe (check_config_file => 1);
    # or
    use Devel::Probe (skip_install => 0);
    # or
    use Devel::Probe (skip_install => 1);
    ...

    Devel::Probe::trigger(sub {
        my ($file, $line) = @_;
        # probe logic
    });

DESCRIPTION

Use this module to allow the possibility of creating probes for some lines in your code.

By default the probing code is installed when you import the module, but if you import it with skip_install => 1 the code is not installed at all (useful for benchmarking the impact of loading the module with no active probes).

By default the probing is disabled, but if you import the module with check_config_file => 1, it will immediately check for a configuration file, as when reacting to a signal (see below).

When your process receives a specific signal (SIGHUP by default), this module will check for the existence of a configuration file (/tmp/devel-probe-config.cfg by default). If that file exists, it must contain a list of directives for the probing. If the configuration file enables probing, after sending a signal to the process it will start checking for probes.

The directives allowed in the configuration file are:

• enable

  Enable probing.

• disable

  Disable probing.

• clear

  Clear current list of probes.

• dump

  Dump current list of probes to stderr.

• probe file line line...

  Add a probe for the given file in each of the given lines.

EXAMPLE

This will invoke the trigger callback whenever line 14 executes, and use PadWalker to dump the local variables.

    # in my_cool_script.pl
    use Data::Dumper qw(Dumper);
    use PadWalker qw(peek_my);
    use Devel::Probe (check_config_file => 1);

    Devel::Probe::trigger(sub {
        my ($file, $line) = @_;
        say Dumper(peek_my(1)); # 1 to jump up one level in the stack;
    });

    my $count;
    while (1) {
        $count++;
        my $something_inside_the_loop = $count * 2;
        sleep 5;
    }

    # /tmp/devel-probe-config.cfg
    enable
    probe my_cool_script.pl 13

TODO

• Probes are stored in a hash of file names; per file name, there is a hash of line numbers (with 1 or 0 as a value). It is likely this can be made more performant with a better data structure, but that needs profiling.

AUTHORS

• Gonzalo Diethelm gonzus AT cpan DOT org

• Ben Tyler btyler AT cpan DOT org