NAME

Runops::Trace - Trace your program's execution

VERSION

version 0.14

SYNOPSIS

Per function tracing:

  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;

Global tracing

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 )

ARRAY = 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.

If called in list context will return the list of B::OP objects.

set_tracer( FUNCTION )

This sets the tracer function globally.

trace uses this.

The code reference will be called once per op. The first argument is the B::OP object for PL_op. The second argument is the operator's arity. This might later be changed if arity methods are included in B::OP itself. The remaining arguments are the arguments for the operator taken from the stack, depending on the operator arity.

CODEREF = get_tracer()

Get the tracing sub (if any).

clear_tracer()

Remove the tracing sub.

enable_tracing()

disable_tracing()

Controls tracing globally.

tracing_enabled()

Returns whether or not tracing is enabled.

set_trace_threshold( INT )

INT = get_trace_threshold()

HASHREF = get_op_counters()

If set to a nonzero value then every opcode will be counted in a hash (get_op_counters returns that hash).

The trace function would only be triggerred after the counter for that opcode has reached a certain number.

This is useful for when you only want to trace a certain hot path.

mask_all()

Disable tracing of all ops.

mask_none()

unmask_all()

Enable tracing of all ops.

mask_op( OPTYPE )

unmask_op( OPTYPE )

Change the masking of a specific op.

Takes a B::OP object, an op type, or an op name.

clear_mask()

Like mask_none was called, but removes the mask entirely.

ARITY_NULL

ARITY_UNARY

ARITY_BINARY

ARITY_LIST

ARITY_LIST_UNARY

ARITY_LIST_BINARY

ARITY_UNKNOWN

These constants can be used to inspect the arity paramter.

Note that for ARITY_LIST_UNARY (entersub) and ARITY_LIST_BINARY (aassign) the arity value is the binary or of ARITY_LIST and ARITY_UNARY or ARITY_BINARY. Test with & or with == according to what you are really interested in.

ARITY_NULL means no arguments (e.g. an SVOP).

Some operators do not have their arity figured out yet. Patches welcome.

This should ideally become a method of B::OP later.

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.

Merged with Runops::Hook by Chia-Liang Kao and Yuval Kogman.

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

AUTHOR

Josh Jore <jjore@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Josh Jore.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.