Benchmark::Harness

WARNING!

Connecting Benchmark::Harness to your Perl application can pose a serious security/privacy risk to your application and the host computer it is running on.

See CAVEAT, below

DO NOT MAINTAIN A PERMANENT HOOK FOR Benchmark::Harness IN YOUR PERL APPLICATION FOR ANY REASON!

SYNOPSIS

Benchmark::Harness will invoke subroutines at specific, parametizable points during the execution of your Perl program. These subroutines may be standard Benchmark::Harness tracing routines, or routines composed by you. The setup involves just a one line addition to your test or driver program, and is easily parameterized and turned on or off from the outside.

To activate Benchmark::Harness on your program, add to your test or driver program the following:

use Benchmark::Harness;
Benchmark::Harness:new(userPsw, 'MyHarness(reportFilename, ...)', @parameters );

userPsw is the required user authentication to make Benchmark::Harness work. After authentication, new() loads your specified sub-harness (e.g., 'Benchmark::Harness::MyHarness') and executes the initialize() method on it, giving it the parameters specified in parantheses here. reportFilename specifies how to report the results from your harness, and @parameter is a list of 'module::sub' strings, each of which specifies a point in your target program to be monitored.

userPsw

The first parameter must be the userid and password (in the form "userid:password"). There is no default for this, and until you make an adjustment in the Authenticate() subroutine of Benchmark::Harness, the Benchmark::Harness will not function.

The base class will handle basic authentication in a standard manner for you, and you may override this functionality by coding your own Authenticate() subroutine in your sub-harness.

'MyHarness'

The second parameter causes your harness module to be loaded (you do not need to 'use' it to have it effective). See the documentation for Benchmark::Harness::Trace for how you would write your sub-harness.

Each sub-harness will be handed an array consisting of the parameters given in this new() statement (as in the "(userPsw,...)" illustrated above).

reportFilename

Filename specifies the disposition (or not) of the output report. Note that this is given to the sub-harness to handle as it pleases; the base class Benchmark::Harness will handle it in the following manner:

The harness report is written to a temporary file. You can get the string contained in this file with the Benchmark::Harness::old() method. The temporary file is then deleted.

This is a convenient way to turn the harness off. Since it can be done by parameterization from the outside, it is especially adaptable to external toggling of the harness. If '0' is specified, no action is performed by Benchmark::Harness or by your sub-harness.

If not '1' or '0', then this parameter is interpreted as a filename into which the report is written. Benchmark::Harness::old() will now return this filename rather than the content of the file. The report file will not be deleted by Benchmark::Harness::old().

Parameters

Benchmark::Harness handles subsequent parameters by calling SetupHandler() with them. Your sub-harness may perform specialized operations with these parameters; Benchmark::Harness's default behavior is as follows.

Each parameter after the filename specifies a sub() in your target program. Methods in your sub-harness are called at the entry, exit, or both of the sub()s specified here. These are strings; that is, you name the module and sub() in a string, not by a CODE reference.

my @parms = qw(-MyProgram::start +MyProgram::finish MyProgram::run)
new Benchmark::Harness(userPsw, 'Benchmark::MyHarness(reportFilename)', @parms);

Each parameter is preceded by a special character to specify the type of monitoring to be performed on that sub().

'-'

Your sub-harness is called at the entry of the target sub(), with @_ equal to the input parameters of that sub().

'+'

Your sub-harness is called when the sub() exits, with @_ or $_[0] (depending on wantarray) equal to the return value of that sub().

none

Performs both '-' and '+'.

You may select subroutines from your target module by some simple wildcards (which are actually Perl regular expressions). Thus,

new Benchmark::Harness(qw(user:psw Trace(1) -TestServer::M.* TestServer::Loop) )

traces the entry of every subroutine in TestServer whose name begins with an 'M', and the entry and exit of the subroutine Loop().

Example

use Benchmark::Harness;
my @traceParameters = qw(Trace(1) -TestServer::M.* TestServer::Loop);
my $traceHarness = new Benchmark::Harness(userPsw, @traceParameters);

TestServer::new(5,10,15,3,4);   # Fire the module under test,

my $result = $traceHarness->old(); # and here's our result (ref to a string).

See Benchmark::Harness::Trace and Benchmark::Harness::MemoryUsage for examples of how to build your own harness operations.

More generalization

Use the following construction to generalize your harness cababilites even more. It is especially adaptable to supplying harness parameters in an XML attribute (as an xsd:list type, which is a space delimited string).

my @harnessParameters = split /\s/, $myParameterString;
if ( @harnessParameters ) {
  eval "use Benchmark::Harness";
  my $harness = Benchmark::Harness::new(\@harnessParameters);
}

CAVEAT

Under certain circumstances, the Harness allows an outside user to interject any Perl process at any point in your host application. This can be done without access to any of your source code or programs, tunnelling through any enveloping security or privacy protections. The hacker can subvert any programmed security feature and, with a little more effort, insert any Perl script into the context of your program, and onto your host computer, at any point in your program.

No matter how innocuous your application is, through Benchmark::Harness it can be made into a gateway to compromise the integrity of your entire host computer.

For this reason, basic authentication is built into Benchmark::Harness by default. There is no default password. You must activate a user id and password in order to make Benchmark::Harness work straight out of the box. See the Authenticate() subroutine here in Benchmark::Harness to set up your initial userid/password.

DO NOT MAINTAIN A PERMANENT HOOK FOR Benchmark::Harness IN YOUR PERL APPLICATION FOR ANY REASON!

AUTHOR

Glenn Wood, <glennwood@cpan.org>

COPYRIGHT

Copyright (C) 2004 Glenn Wood. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Benchmark::Harness

perl -MCPAN -e shell
install Benchmark::Harness