=head1 METHODS
-=head2 C<analyse [ %options ]>
+=head2 C<analyse>
+
+ Test::Valgrind->analyse(%options);
Run a C<valgrind> analysis configured by C<%options> :
return $status;
}
-=head2 C<import [ %options ]>
+=head2 C<import>
+
+ use Test::Valgrind %options;
In the parent process, L</import> calls L</analyse> with the arguments it received itself - except that if no C<file> option was supplied, it tries to pick the first caller context that looks like a script.
When the analysis ends, it exits with the status returned by the action (for the default TAP-generator action, it's the number of failed tests).
=head1 METHODS
-=head2 C<< new action => $action >>
+=head2 C<new>
+
+ my $tva = Test::Valgrind::Action->new(action => $action);
Creates a new action object of type C<$action> by requiring and redispatching the method call to the module named C<$action> if it contains C<'::'> or to C<Test::Valgrind::Action::$action> otherwise.
The class represented by C<$action> must inherit this class.
sub do_suppressions { 0 }
-=head2 C<start $session>
+=head2 C<start>
+
+ $tva->start($session);
Called when the C<$session> starts.
Defaults to set L<Test::Valgrind::Component/started>.
-=head2 C<report $session, $report>
+=head2 C<report>
+
+ $tva->report($session, $report);
Invoked each time the C<valgrind> process attached to the C<$session> spots an error.
C<$report> is a L<Test::Valgrind::Report> object describing the error.
return;
}
-=head2 C<abort $session, $msg>
+=head2 C<abort>
+
+ $tva->abort($session, $msg);
Triggered when the C<$session> has to interrupt the action.
sub abort { $_[0]->_croak($_[2]) }
-=head2 C<finish $session>
+=head2 C<finish>
+
+ $tva->finish($session);
Called when the C<$session> finishes.
Defaults to clear L<Test::Valgrind::Component/started>.
-=head2 C<status $session>
+=head2 C<status>
+
+ $tva->status($session);
Returns the status code corresponding to the last run of the action.
or $_[0]->_croak('open(' . fileno($_[1]) . ", '$_[2]&', $fd): $!");
}
-=head2 C<save_fh $from, $mode [, $to ]>
+=head2 C<save_fh>
+
+ $tva->save_fh($from, $mode);
+ $tva->save_fh($from, $mode, $to);
Save the original filehandle C<$from> opened with mode C<$mode>, and redirect it to C<$to> if it's defined or to F</dev/null> otherwise.
=head2 C<restore_all_fh>
+ $tva->restore_all_fh;
+
Restore all the filehandles that were saved with L</save_fh> to their original state.
The redirections aren't closed.
This class inherits L<Test::Valgrind::Action>.
-=head2 C<< new name => $name, target => $target, ... >>
+=head2 C<new>
+
+ my $tvas = Test::Valgrind::Action::Suppressions->new(
+ name => $name,
+ target => $target,
+ %extra_args,
+ );
Your usual constructor.
=head2 C<name>
+ my $name = $tvas->name;
+
Read-only accessor for the C<name> option.
=cut
=head2 C<target>
+ my $target = $tvas->target;
+
Read-only accessor for the C<target> option.
=cut
This class inherits L<Test::Valgrind::Action> and L<Test::Valgrind::Action::Captor>.
-=head2 C<< new diag => $diag, extra_tests => $extra_tests, ... >>
+=head2 C<new>
+
+ my $tvat = Test::Valgrind::Action::Test->new(
+ diag => $diag,
+ extra_tests => $extra_tests,
+ %extra_args,
+ );
Your usual constructor.
=head2 C<diag>
+ my $diag = $tvat->diag;
+
Read-only accessor for the C<diag> option.
=cut
=head2 C<kinds>
+ my @kinds = $tvat->kinds;
+
Returns the list of all the monitored report kinds.
=cut
=head1 METHODS
-=head2 C<< new command => $command, args => \@args >>
+=head2 C<new>
+
+ my $tvc = Test::Valgrind::Command->new(
+ command => $command,
+ args => \@args,
+ );
Creates a new command object of type C<$command> by requiring and redispatching the method call to the module named C<$command> if it contains C<'::'> or to C<Test::Valgrind::Command::$command> otherwise.
The class represented by C<$command> must inherit this class.
sub new_trainer { }
-=head2 C<args $session>
+=head2 C<args>
+
+ my @args = $tvc->args($session);
Returns the list of command-specific arguments that are to be passed to C<valgrind>.
sub args { @{$_[0]->{args} || []} }
-=head2 C<env $session>
+=head2 C<env>
+
+ my $env = $tvc->env($session);
This event is called in scalar context before the command is ran, and the returned value goes out of scope when the analysis ends.
It's useful for e.g. setting up C<%ENV> for the child process by returning an L<Env::Sanctify> object, hence the name.
sub env { }
-=head2 C<suppressions_tag $session>
+=head2 C<suppressions_tag>
+
+ my $tag = $tvc->suppressions_tag($session);
Returns a identifier that will be used to pick up the right suppressions for running the command, or C<undef> to indicate that no special suppressions are needed.
sub suppressions_tag;
-=head2 C<filter $session, $report>
+=head2 C<filter>
+
+ my $filtered_report = $tvc->filter($session, $report);
The C<$session> calls this method after receiving a report from the tool and before forwarding it to the action.
You can either return a mangled C<$report> (which does not need to be a clone of the original) or C<undef> if you want the action to ignore it completely.
This class inherits L<Test::Valgrind::Command>.
-=head2 C<< new commands => \@commands, ... >>
+=head2 C<new>
+
+ my $tvca = Test::Valgrind::Command::Aggregate->new(
+ commands => \@commands,
+ %extra_args,
+ );
=cut
=head2 C<commands>
+ my @commands = $tvca->commands;
+
Read-only accessor for the C<commands> option.
=cut
This class inherits L<Test::Valgrind::Command>.
-=head2 C<< new perl => $^X, inc => \@INC, taint_mode => $taint_mode, ... >>
+=head2 C<new>
+
+ my $tvcp = Test::Valgrind::Command::Perl->new(
+ perl => $^X,
+ inc => \@INC,
+ taint_mode => $taint_mode,
+ %extra_args,
+ );
The package constructor, which takes several options :
=head2 C<perl>
+ my $perl = $tvcp->perl;
+
Read-only accessor for the C<perl> option.
=cut
=head2 C<inc>
+ my @inc = $tvcp->inc;
+
Read-only accessor for the C<inc> option.
=cut
=head2 C<taint_mode>
+ my $taint_mode = $tvcp->taint_mode;
+
Read-only accessor for the C<taint_mode> option.
=cut
$self->SUPER::args(@_);
}
-=head2 C<env $session>
+=head2 C<env>
+
+ my $env = $tvcp->env($session);
Returns an L<Env::Sanctify> object that sets the environment variables C<PERL_DESTRUCT_LEVEL> to C<3> and C<PERL_DL_NONLAZY> to C<1> during the run.
This class inherits L<Test::Valgrind::Command::Perl>.
-=head2 C<< new file => $file, [ taint_mode => $taint_mode ], ... >>
+=head2 C<new>
+
+ my $tvcps = Test::Valgrind::Command::PerlScript->new(
+ file => $file,
+ taint_mode => $taint_mode,
+ %extra_args,
+ );
The package constructor, which takes several options :
=head2 C<file>
+ my $file = $tvcps->file;
+
Read-only accessor for the C<file> option.
=cut
=head2 C<new>
+ my $tvc = Test::Valgrind::Component->new;
+
Basic constructor.
=cut
}, $class;
}
-=head2 C<started [ $bool ]>
+=head2 C<started>
+
+ $tvc->started($bool);
Specifies whether the component is running (C<1>), stopped (C<0>) or was never started (C<undef>).
=head2 C<start>
+ $tvc->start;
+
Marks the component as started, and throws an exception if it was already.
Returns its self object.
=head2 C<finish>
+ $tvc->finish;
+
Marks the component as stopped, and throws an exception if it wasn't started.
Returns its self object.
=head2 C<new>
+ my $tvp = Test::Valgrind::Parser->new;
+
The parser constructor, called without arguments.
Defaults to L<Test::Valgrind::Component/new>.
-=head2 C<start $session>
+=head2 C<start>
+
+ $tvp->start($session);
Called when the C<$session> starts.
Defaults to set L<Test::Valgrind::Component/started>.
-=head2 C<args $session, $fh>
+=head2 C<args>
+
+ my @args = $tvp->args($session, $fh);
Returns the list of parser-specific arguments that are to be passed to the C<valgrind> process spawned by the session C<$session> and whose output will be captured by the filehandle C<$fh>.
sub args { }
-=head2 C<parse $session, $fh>
+=head2 C<parse>
+
+ $tvp->parse($session, $fh);
Parse the output of the C<valgrind> process attached to the session C<$session> received through the filehandle C<$fh>.
sub parse;
-=head2 C<finish $session>
+=head2 C<finish>
+
+ $tvp->finish($session);
Called when the C<$session> finishes.
=head1 METHODS
-=head2 C<args $session, $fh>
+=head2 C<args>
+
+ my @args = $tvp->args($session, $fh);
Returns the arguments needed to tell C<valgrind> to print in text to the filehandle C<$fh>.
=head1 METHODS
-=head2 C<args $session, $fh>
+=head2 C<args>
+
+ my @args = $tvp->args($session, $fh);
Returns the arguments needed to tell C<valgrind> to print in XML to the filehandle C<$fh>.
use base qw<Test::Valgrind::Carp>;
-=head2 C<< new kind => $kind, id => $id, data => $data >>
+=head2 C<new>
+
+ my $tvr = Test::Valgrind::Report->new(
+ kind => $kind,
+ id => $id,
+ data => $data,
+ );
Your usual constructor.
}, $class;
}
-=head2 C<< new_diag $data >>
+=head2 C<new_diag>
+
+ my $diag_report = Test::Valgrind::Report->new_diag($data);
Constructs a report with kind C<'Diag'>, an auto-incremented identifier and the given C<$data>.
=head2 C<kind>
+ my $kind = $tvr->kind;
+
Read-only accessor for the C<kind> option.
=cut
=head2 C<id>
+ my $id = $tvr->id;
+
Read-only accessor for the C<id> option.
=cut
=head2 C<data>
+ my $data = $tvr->data;
+
Read-only accessor for the C<data> option.
=cut
=head2 C<is_diag>
+ $tvr->is_diag;
+
Tells if a report has the C<'Diag'> kind, i.e. is a diagnostic.
=cut
=head2 C<kinds>
+ my @kinds = $tvr->kinds;
+
Returns the list of valid kinds for this report class.
Defaults to C<'Diag'>.
sub kinds { 'Diag' }
-=head2 C<valid_kind $kind>
+=head2 C<valid_kind>
+
+ $tvr->valid_kind($kind);
Tells whether C<$kind> is a valid kind for this report class.
=head1 METHODS
-=head2 C<< new search_dirs => \@search_dirs, valgrind => [ $valgrind | \@valgrind ], min_version => $min_version, no_def_supp => $no_def_supp, extra_supps => \@extra_supps >>
+=head2 C<new>
+
+ my $tvs = Test::Valgrind::Session->new(
+ search_dirs => \@search_dirs,
+ valgrind => $valgrind, # One candidate
+ valgrind => \@valgrind, # Several candidates
+ min_version => $min_version,
+ no_def_supp => $no_def_supp,
+ extra_supps => \@extra_supps,
+ );
The package constructor, which takes several options :
=head2 C<valgrind>
+ my $valgrind_path = $tvs->valgrind;
+
The path to the selected C<valgrind> executable.
=head2 C<version>
+ my $valgrind_version = $tvs->version;
+
The L<version> object associated to the selected C<valgrind>.
=cut
=head2 C<no_def_supp>
+ my $no_def_supp = $tvs->no_def_supp;
+
Read-only accessor for the C<no_def_supp> option.
=cut
=head2 C<extra_supps>
+ my @extra_supps = $tvs->extra_supps;
+
Read-only accessor for the C<extra_supps> option.
=cut
sub extra_supps { @{$_[0]->{extra_supps} || []} }
-=head2 C<< run action => $action, tool => $tool, command => $command >>
+=head2 C<run>
+
+ $tvs->run(
+ action => $action,
+ tool => $tool,
+ command => $command,
+ );
Runs the command C<$command> through C<valgrind> with the tool C<$tool>, which will report to the action C<$action>.
=head2 C<suppressions>
+ my @suppressions = $tvs->suppressions;
+
Returns the list of all the suppressions that will be passed to C<valgrind>.
Honors L</no_def_supp> and L</extra_supps>.
=head2 C<start>
+ $tvs->start(
+ action => $action,
+ tool => $tool,
+ command => $command,
+ );
+
Starts the action and tool associated to the current run.
It's automatically called at the beginning of L</run>.
return;
}
-=head2 C<abort $msg>
+=head2 C<abort>
+
+ $tvs->abort($msg);
Forwards to C<< ->action->abort >> after unshifting the session object to the argument list.
$self->action->abort($self, @_);
}
-=head2 C<report $report>
+=head2 C<report>
+
+ $tvs->report($report);
Forwards to C<< ->action->report >> after unshifting the session object to the argument list.
=head2 C<finish>
+ $tvs->finish;
+
Finishes the action and tool associated to the current run.
It's automatically called at the end of L</run>.
=head2 C<status>
+ my $status = $tvs->status;
+
Returns the status code of the last run of the session.
=cut
=head1 METHODS
-=head2 C<< generate tool => $tool, command => $command, target => $target >>
+=head2 C<generate>
+
+ Test::Valgrind::Suppressions->generate(
+ tool => $tool,
+ command => $command,
+ target => $target,
+ );
Generates suppressions for the command C<< $command->new_trainer >> and the tool C<< $tool->new_trainer >>, and writes them in the file specified by C<$target>.
The action used behind the scenes is L<Test::Valgrind::Action::Suppressions>.
return $status;
}
-=head2 C<strip_tail $session, $suppression>
+=head2 C<strip_tail>
+
+ my $mangled_suppression = Test::Valgrind::Suppressions->strip_tail(
+ $session,
+ $suppression,
+ );
Removes all wildcard frames at the end of the suppression.
Moreover, C<'...'> is appended when C<valgrind> C<3.4.0> or higher is used.
$supp;
}
-=head2 C<maybe_z_demangle $symbol>
+=head2 C<maybe_z_demangle>
+
+ my $demangled_symbol = Test::Valgrind::Suppressions->maybe_z_demangle(
+ $symbol,
+ );
If C<$symbol> is Z-encoded as described in C<valgrind>'s F<include/pub_tool_redir.h>, extract and decode its function name part.
Otherwise, C<$symbol> is returned as is.
=head2 C<requires_version>
+ my $required_version = $tvt->requires_version;
+
The minimum C<valgrind> version needed to run this tool.
Defaults to C<3.1.0>.
sub requires_version { '3.1.0' }
-=head2 C<< new tool => $tool >>
+=head2 C<new>
+
+ my $tvt = Test::Valgrind::Tool->new(tool => $tool);
Creates a new tool object of type C<$tool> by requiring and redispatching the method call to the module named C<$tool> if it contains C<'::'> or to C<Test::Valgrind::Tool::$tool> otherwise.
The class represented by C<$tool> must inherit this class.
=head2 C<new_trainer>
+ my $tvt_train = Test::Valgrind::Tool->new_trainer;
+
Creates a new tool object suitable for generating suppressions.
Defaults to return C<undef>, which skips suppression generation.
sub new_trainer { }
-=head2 C<parser_class $session>
+=head2 C<parser_class>
+
+ my $parser_class = $tvt->parser_class($session);
Returns the class from which the parser for this tool output will be instanciated.
sub parser_class;
-=head2 C<report_class $session>
+=head2 C<report_class>
+
+ my $report_class = $tvt->report_class($session);
Returns the class in which suppression reports generated by this tool will be blessed.
sub report_class;
-=head2 C<args $session>
+=head2 C<args>
+
+ my @args = $tvt->args($session);
Returns the list of tool-specific arguments that are to be passed to C<valgrind>.
All the suppression arguments are already handled by the session.
sub args { }
-=head2 C<suppressions_tag $session>
+=head2 C<suppressions_tag>
+
+ my $tag = $tvt->suppressions_tag($session);
Returns a identifier that will be used to pick up the right suppressions for running the tool, or C<undef> to indicate that no special suppressions are needed.
sub suppressions_tag;
-=head2 C<start $session>
+=head2 C<start>
+
+ $tvt->start($session);
Called when the C<$session> starts.
Defaults to set L<Test::Valgrind::Component/started>.
-=head2 C<filter $session, $report>
+=head2 C<filter>
+
+ my $filtered_report = $tvt->filter($session, $report);
The C<$session> calls this method after receiving a report from the parser and before letting the command filter it.
You can either return a mangled C<$report> (which does not need to be a clone of the original) or C<undef> if you want the action to ignore it completely.
sub filter { $_[2] }
-=head2 C<finish $session>
+=head2 C<finish>
+
+ $tvt->finish($session);
Called when the C<$session> finishes.
=head2 C<requires_version>
+ my $required_version = $tvt->requires_version;
+
This tool requires C<valgrind> C<3.1.0>.
=cut
sub requires_version { '3.1.0' }
-=head2 C<< new callers => $callers, ... >>
+=head2 C<new>
+
+ my $tvtm = Test::Valgrind::Tool::memcheck->new(
+ callers => $callers,
+ %extra_args,
+ );
Your usual constructor.
=head2 C<callers>
+ my $callers = $tvtm->callers;
+
Read-only accessor for the C<callers> option.
=cut
sub suppressions_tag { 'memcheck-' . $_[1]->version }
-=head2 C<parser_class $session>
+=head2 C<parser_class>
+
+ my $parser_class = $tvtm->parser_class($session);
This tool uses a L<Test::Valgrind::Parser::XML::Twig> parser in analysis mode, and a L<Test::Valgrind::Parser::Suppressions::Text> parser in suppressions mode.
return $class;
}
-=head2 C<report_class $session>
+=head2 C<report_class>
+
+ my $report_class = $tvtm->report_class($session);
This tool emits C<Test::Valgrind::Tool::memcheck::Report> object reports in analysis mode, and C<Test::Valgrind::Report::Suppressions> object reports in suppressions mode.
projects / perl / modules / Test-Valgrind.git / commitdiff