NAME

Runops::Trace - Trace your program's execution

SYNOPSIS

use Runops::Trace 'checksum_code_path';
sub is_even { shift() % 2 == 0 ? 1 : 0 }

my %sufficient;
for my $number ( 0 .. 10 ) {
    # Get a signature for the code 
    my $codepath = checksum_code_path(
        sub { is_even( $number ) }
    );

    if ( not exists $sufficient{$codepath} ) {
        $sufficient{$codepath} = $number;
    }
}
print join ' ', keys %sufficient;

DESCRIPTION

This module traces opcodes as they are executed by the perl VM. The trace function can be turned on globally or just during the execution of a single function.

INTERFACE

trace( TRACE, FUNCTION )

This is a generic way of tracing a function. It ensures that your TRACE function is called before every operation in the FUNCTION function.

The TRACE function will be given the pointer of the opnode that is about to be run. This is an interim API. The desired result is that a B::OP object is passed instead of just the pointer. Also, it is always the same scalar - only the value is changing. References taken to this value will mutate. The TRACE function will be called in void context.

The FUNCTION function will be called in void context and will not be given any parameters.

There is no useful return value from this function.

MD5SUM = checksum_code_path( FUNCTION )

This returns a hex MD5 checksum of the ops that were visited. This is a nice, concise way of representing a unique path through code.

STRING = trace_code( FUNCTION )

This returns a string representing the ops that were executed. Each op is represented as its name and hex address in memory.

PERL HACKS COMPATIBILITY

This module does not currently implement the interface as described in the O'Reilly book Perl Hacks.

ADVANCED NOTES

THREAD-UNSAFE

I made no attempt at thread safety. Do not use this module in a multi-threaded process.

WRITE YOUR OWN SUGAR

The trace( TRACE, FUNCTION ) function is sufficient to allow any arbitrary kind of access to running code. This module is included with two simple functions to return useful values. Consider looking at their source code and writing your own.

ON THE FLY CODE MODIFICATION

If the B::Generate module is loaded, the B:: object that is passed to the tracing function may also be modified. This would allow you to modify the perl program as it is running. Thi

AUTHOR

Rewritten by Joshua ben Jore, originally written by chromatic, based on Runops::Switch by Rafael Garcia-Suarez.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl 5.8.x itself.