- This module lets you run some code through the valgrind memory debugger,
- to test it for memory errors and leaks. Just add "use Test::Valgrind" at
- the beginning of the code you want to test. Behind the hood,
- "Test::Valgrind::import" forks so that the child can basically "exec
- 'valgrind', $^X, $0" (except that of course $0 isn't right there). The
- parent then parses the report output by valgrind and pass or fail tests
- accordingly.
+ This module is a front-end to the "Test::Valgrind::*" API that lets you
+ run Perl code through the "memcheck" tool of the "valgrind" memory
+ debugger, to test for memory errors and leaks. If they aren't available
+ yet, it will first generate suppressions for the current "perl"
+ interpreter and store them in the portable flavour of
+ ~/.perl/Test-Valgrind/suppressions/$VERSION. The actual run will then
+ take place, and tests will be passed or failed according to the result
+ of the analysis.
+
+ The complete API is much more versatile than this. By declaring an
+ appropriate Test::Valgrind::Command class, you can run any executable
+ (that is, not only Perl scripts) under valgrind, generate the
+ corresponding suppressions on-the-fly and convert the analysis result to
+ TAP output so that it can be incorporated into your project's testsuite.
+ If you're not interested in producing TAP, you can output the results in
+ whatever format you like (for example HTML pages) by defining your own
+ Test::Valgrind::Action class.
+
+ Due to the nature of perl's memory allocator, this module can't track
+ leaks of Perl objects. This includes non-mortalized scalars and memory
+ cycles. However, it can track leaks of chunks of memory allocated in XS
+ extensions with "Newx" and friends or "malloc". As such, it's
+ complementary to the other very good leak detectors listed in the "SEE
+ ALSO" section.
+
+METHODS
+ "analyse"
+ Test::Valgrind->analyse(%options);
+
+ Run a "valgrind" analysis configured by %options :
+
+ * "command => $command"
+
+ The Test::Valgrind::Command object (or class name) to use.
+
+ Defaults to Test::Valgrind::Command::PerlScript.
+
+ * "tool => $tool"
+
+ The Test::Valgrind::Tool object (or class name) to use.
+
+ Defaults to Test::Valgrind::Tool::memcheck.