/ 
Test-Weaken-0.002002
River stage one • 1 direct dependent • 3 total dependents
/ Test::Weaken

NAME

Test::Weaken - Test for leaks after weakening of circular references

VERSION

Beta Version

This is beta software. Be careful. Note that Test::Weaken is primarily targeted to testing and debugging in any case, not to production environments.

SYNOPSIS

Frees an object and checks that the memory was freed. This module is intended for use in test scripts, to check that the programmer's strategy for weakening circular references does indeed work as expected.

use Test::Weaken qw(poof);

my $test = sub {
       my $obj1 = new Module::Test_me1;
       my $obj2 = new Module::Test_me2;
       [ $obj1, $obj2 ];
};  

my $freed_ok = Test::Weaken::poof( $test );

my ($weak_count, $strong_count, $weak_unfreed, $strong_unfreed)
    = Test::Weaken::poof( $test );

print scalar @$weak_unfreed,
    " of $weak_count weak references freed\n";
print scalar @$strong_unfreed,
    " of $strong_count strong references freed\n";

print "Weak unfreed references: ",
    join(" ", map { "".$_ } @$weak_unfreed), "\n";
print "Strong unfreed references: ",
    join(" ", map { "".$_ } @$strong_unfreed), "\n";

Test::Weaken is intended for testing and debugging, rather than use in production code.

EXPORT

By default, Test::Weaken exports nothing. Optionally, poof may be exported.

FUNCTION

poof( CLOSURE )

poof takes a subroutine reference as its only argument. The subroutine should construct the the object to be tested and return a reference to it. poof frees that object, then checks every reference in it to ensure that all references were released. In scalar context, it returns a true value if the memory was properly released, false otherwise.

In array context, poof returns counts of the references in the original object and arrays with references to the references not freed. Specifically, in an array context, poof returns a list with four elements: first, the starting count of weak references; second, the starting count of strong references; third, a reference to an array containing references to the unfreed weak references; fourth, a reference to an array containing references to the unfreed strong references.

The name poof was intended to warn the programmer that the test is destructive. I originally called the main subroutine destroy, but that choice seemed unfortunate because of similarities to DESTROY, a name reserved for object destructors.

poof's way of obtaining the reference to be tested may seem roundabout. In fact, the indirect method turns out to be easiest. The reference to be tested must not have any strong references to it from outside. One way or another, some craft is required for the calling environment to create and pass an object without holding any reference to it. Any mistake produces a false negative, one which is quite difficult to distinguish from a real negative. The direct approach turns out to cost more trouble than it saves.

LIMITATIONS

This module does not look inside code references.

This module assumes the object returned from the subroutine is self-contained, that is, that there are no references to memory outside the object to be tested. If there are, the results will be hard to interpret, because the test assumes all referenced memory to should be freed. Additionally, the unfreed memory will be altered. To distinguish undef's in the original data from those which result from freeing of memory, Test::Weaken overwrites them with the number 42.

AUTHOR

Jeffrey Kegler

BUGS

None known at present, but see LIMITATIONS.

Please report any bugs or feature requests to bug-test-weaken at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Weaken. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Test::Weaken

You can also look for information at:

SEE ALSO

Potential users will want to compare Test::Memory::Cycle and Devel::Cycle, which examine existing structures non-destructively. Devel::Leak also covers similar ground, although it requires Perl to be compiled with -DDEBUGGING in order to work. Devel::Cycle looks inside closures if PadWalker is present, a feature Test::Weaken does not have at present.

ACKNOWLEDGEMENTS

Thanks to jettero, Juerd and perrin of Perlmonks for their advice. Thanks also to Lincoln Stein (developer of Devel::Cycle) for test cases and other ideas.

COPYRIGHT & LICENSE

Copyright 2007 Jeffrey Kegler, all rights reserved.

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