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

NAME

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

VERSION

Alpha Version

This is alpha software, not at present suitable for any purpose except reading and experimentation. Among other issues, this documentation is still very inadequate.

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;

    my $freed_ok = Test::Weaken::poof(
        sub {
	   my $obj1 = new Module::Test_me1;
	   my $obj2 = new Module::Test_me2;
	   [ $obj1, $obj2 ];
	}
    );

FUNCTION

poof

sub poof { }

poof is named in order to emphasize that the test is destructive. poof takes a subroutine reference as its only argument. The subroutine should return a reference to an object. poof frees that object, then checks each reference to ensure it has been released. In scalar context, it returns a true value if the memory was properly released, false otherwise.

In array context, poof returns a list containing the references counts from 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.

AUTHOR

Jeffrey Kegler

BUGS

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:

LIMITATIONS

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.

This module does not look inside code references. Devel::Cycle does so if PadWalker is present, and I may enhance this module to do likewise.

This module assumes the object returned from the subroutine is self-contained, that is, that there are no references to outside memory. If there are, bad things will happen. Most seriously, to distinguish undef's in the original data from those which result from freeing of memory, Test::Weaken overwrites them with the number 42. Less, the results reported by Test::Weaken will include the outside memory, probably not be what you wanted.

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.

NAME