NAME¶
Test::Weaken - Test that freed memory objects were, indeed, freed
SYNOPSIS¶
use Test::Weaken qw(leaks);
# basic leaks detection
my $leaks = leaks(sub {
my $obj = { one => 1,
two => [],
three => [3,3,3] };
return $obj;
});
if ($leaks) {
print "There were memory leaks from test 1!\n";
printf "%d of %d original references were not freed\n",
$leaks->unfreed_count(), $leaks->probe_count();
} else {
print "No leaks in test 1\n";
}
# or with various options
$leaks = Test::Weaken::leaks(
{ constructor => sub {
my @array = (42, 711);
push @array, \@array; # circular reference
return \@array;
},
destructor => sub {
print "This could invoke an object destructor\n";
},
ignore => sub {
my ($ref) = @_;
if (some_condition($ref)) {
return 1; # ignore
}
return 0; # don't ignore
},
contents => sub {
my ($ref) = @_;
return extract_more_from($ref);
},
});
if ($leaks) {
print "There were memory leaks from test 2!\n";
my $unfreed_proberefs = $leaks->unfreed_proberefs();
print "These are the probe references to the unfreed objects:\n";
require Data::Dumper;
foreach my $ref (@$unfreed_proberefs) {
print "ref $ref\n";
print Data::Dumper->Dump([$ref], ['unfreed']);
}
}
DESCRIPTION¶
"Test::Weaken" helps detect unfreed Perl data in arrays, hashes,
scalars, objects, etc, by descending recursively through structures and
watching that everything is freed. Unfreed data is a useless overhead and may
cause an application to abend due to lack of memory.
Normally if the last reference to something is discarded then it and anything in
it is freed automatically. But this might not occur due to circular
references, unexpected global variables or closures, or reference counting
mistakes in XSUBs.
"Test::Weaken" is named for the strategy used to detect leaks.
References are taken to the test objects and all their contents, then those
references are weakened and expected to be then freed.
There's options to ignore intentional globals, or include extra associated data
held elsewhere, or invoke an explicit destructor. Unfreed parts are reported
and can be passed to other modules such as Devel::FindRef to try to discover
why they weren't freed.
"Test::Weaken" examines structures to an unlimited depth and is safe
on circular structures.
Tracking and Children¶
"Test::Weaken" determines the contents of a data structure by the
contents of the top object of the test data structure, and recursively into
the contents of those sub-parts. The following data types are tracked and
their contents examined,
ARRAY each of its values
HASH each of its values
SCALAR if a reference then the target thing
CODE no contents as yet
tie ANY the associated tie object from tied()
In an array or hash each scalar value has an independent existence and
"Test::Weaken" tracks each individually (see "Array and Hash
Keys and Values" below).
"CODE" objects, ie. subroutines, are not examined for children. This
is a limitation, because closures do hold internal references to data objects.
Future versions of "Test::Weaken" might descend into CODE objects.
The following types are not tracked by default and not examined for contents,
GLOB
IO underlying a file handle
FORMAT always global
LVALUE
GLOBs are usually either an entry in the Perl symbol table or a filehandle. An
IO is the file object underlying a filehandle. Perl symbol tables are usually
permanent and shouldn't be tracked, but see "File Handles" below for
tracking open files.
Builtin types added to Perl in the future and not known to
"Test::Weaken" will not be tracked by default but could be requested
with "tracked_types" below.
A variable of builtin type GLOB may be a scalar which was assigned a GLOB value
(a scalar-GLOB) or it may simply be a GLOB (a pure-GLOB). The issue that
arises for "Test::Weaken" is that, in the case of a scalar-GLOB, the
scalar and the GLOB may be tied separately. At present, the underlying tied
variable of the scalar side of a scalar-GLOB is ignored. Only the underlying
tied variable of the GLOB is a child for "Test::Weaken"'s purposes.
Returns and Exceptions¶
The methods of "Test::Weaken" do not return errors. Errors are always
thrown as exceptions.
EXPORTS¶
By default, "Test::Weaken" exports nothing. Optionally,
"leaks()" may be requested in usual "Exporter" style (see
Exporter). (And "poof()" from "OLD FUNCTIONS" too if
desired.)
use Test::Weaken 'leaks'; # import
my $tester = leaks (...);
PORCELAIN METHODS¶
leaks¶
my $leaks = Test::Weaken::leaks(
{ constructor => sub { Buggy_Object->new() },
destructor => \&destroy_buggy_object,
}
);
if ($leaks) {
print "There are leaks\n";
}
Check for leaks in the object created by the constructor function and return
either an evaluated "Test::Weaken" object instance if there are
leaks, or Perl false if there are no leaks.
Instances of the "Test::Weaken" class are called
testers. An
evaluated tester is one on which the tests have been run and for which
results are available.
Users who only want to know if there were unfreed data objects can check the
return value of "leaks()" for Perl true or false. Arguments to
"leaks()" are passed as a hashref of named arguments.
"leaks()" can also be called in a "short form", where the
constructor and destructor are passed directly as code references.
- "constructor => $coderef"
- The "constructor" argument is required. Its value must be a
coderef returning a reference to the test data structure.
my $leaks = leaks ({ constructor => sub {
return Some::Object->new(123);
},
});
For "short form" the constructor coderef is the first argument,
leaks (sub {
return Some::Object->new(123);
});
If the constructor returns a list of objects then all are checked.
leaks (sub {
return (Foo->new(), Bar->new());
});
Usually this is when two objects are somehow inter-related and should weaken
away together, or perhaps sub-parts of an object not reached by the
contents tracing (or see "contents" below for a more general way
to reach such sub-parts.)
- "destructor => $coderef"
- "destructor_method => $methodname"
- An optional destructor is called just before "Test::Weaken"
tries to free everything. Some test objects or structures might require
explicit destruction when they're to be freed.
"destructor" is called with the objects returned by the
constructor
&$destructor ($obj, ...)
For example,
leaks ({ constructor => sub { return make_some_thing() },
destructor => sub {
my ($thing) = @_;
delete $thing->{'circular_ref'};
},
});
For "short form" the destructor is an optional second argument,
leaks (sub { Foo->new },
sub {
my ($foo) = @_;
$foo->destroy;
});
"destructor_method" is called as a method on each object returned
by the constructor,
$obj->$methodname();
For example if the constructed object (or objects) require an explicit
"$foo->destroy()" then
leaks ({ constructor => sub { Foo->new },
destructor_method => 'destroy' });
If both "destructor" and "destructor_method" are given
then "destructor_method" calls are first, then
"destructor".
An explicit destructor may be needed for things like toplevel windows in GUI
toolkits such as Wx and Gtk (and perhaps also some main loop iterations if
actual destruction is delayed). Some object-oriented tree structures may
need explicit destruction too if parent and child nodes keep hard
references to each other, though it's usually more convenient if
child->parent is only a weak reference. (See also
Object::Destroyer.)
- "ignore => $coderef"
- "ignore_preds => [ $coderef, $coderef, ...]"
- "ignore_class => $classname"
- "ignore_classes => [ $classname, $classname, ... ]"
- "ignore_object => $ref"
- "ignore_objects => [ $ref, $ref, ... ]"
- Ignore some things. When a thing is ignored it's not tracked for leaks and
its contents are not examined.
"ignore" and "ignore_preds" take predicate functions. If
any of them return true then the thing $ref refers to is ignored.
$bool = &$coderef ($ref);
For example
sub ignore_all_tied_hashes {
my ($ref) = @_;
return (ref $ref eq 'HASH'
&& defined (tied %$ref));
}
my $tester = Test::Weaken::leaks(
{ constructor => sub { MyObject->new() },
ignore => \&ignore_all_tied_hashes,
});
"ignore_class" and "ignore_classes" ignore blessed
objects which are of the given class or classes. For example,
my $leaks = Test::Weaken::leaks(
{ constructor => sub { MyObject->new() },
ignore_class => 'My::Singleton',
}
my $leaks = Test::Weaken::leaks(
{ constructor => sub { MyObject->new() },
ignore_classes => [ 'My::Singleton',
'My::PrinterDriver' ],
}
Objects are checked with
blessed($ref) && $ref->isa($classname)
which reaches any class-specific "isa()" in the object in the
usual way. That allows classes to masquerade or have a dynamic
"isa". That's normally fine and can be highly desirable in
things like lazy loaders.
"ignore_object" and "ignore_objects" ignore the
particular things referred to by the each given $ref. For example,
my $leaks = Test::Weaken::leaks(
{ constructor => sub { MyObject->new() },
ignore_object => \%global_data,
}
my $leaks = Test::Weaken::leaks(
{ constructor => sub { MyObject->new() },
ignore_objects => [ $obj1, $obj2 ],
}
For both "ignore_object" and "ignore_objects" any
"undef"s among the refs are ignored. This is handy if a global
might or might not have been initialized yet. These options are called
"object" because they're most often used with blessed objects,
but unblessed things are fine too.
"ignore" callbacks should not change the contents of $ref. Doing
so might cause an exception, an infinite loop, or erroneous results. See
"Debugging Ignore Subroutines" for a little help against bad
"ignore".
When comparing references in a predicate it's good to use
"Scalar::Util::refaddr()". Plain "$ref==$something"
can be tricked if $ref is an object with overloaded numize or
"==" (see overload).
Another way to ignore is let globals etc go through as leaks and then filter
them from the "$leaks->unfreed_proberefs()" afterwards. The
benefit of "ignore" is that it excludes object contents
too.
- contents
- An optional "contents" function can tell
"Test::Weaken" about additional Perl data objects which should
be checked.
sub my_extra_contents {
my ($ref) = @_;
if (blessed($ref) && $ref->isa('MyObject')) {
return $ref->data, $ref->moredata;
} else {
return;
}
}
my $leaks = Test::Weaken::leaks(
{ constructor => sub { return MyObject->new },
contents => \&my_extra_contents
});
The given $coderef is called for each Perl data object. It should return a
list of additional Perl data objects, or an empty list if no extra
contents.
@extra_contents = &$coderef ($ref);
"contents" allows OOPery such as "inside-out" where
object contents are held separately. It can also be used on wrappers for
C-code objects where some of the contents of a widget etc are not in Perl
level structures but only available through object method calls etc.
"contents" and "ignore" can be used together.
"ignore" is called first and if not ignored then
"contents" is called.
- tracked_types
- Optional "tracked_types" is an arrayref of additional builtin
types to track.
my $test = Test::Weaken::leaks(
{ constructor => sub {
my $obj = MyObject->new;
return $obj;
},
tracked_types => ['GLOB'],
}
);
The default tracking is per "Tracking and Children" above. The
additional types which may be tracked are
GLOB
IO
FORMAT
LVALUE
These names are per "reftype()" of Scalar::Util. See "File
Handles" below for setting up to track GLOBs as filehandles.
unfreed_proberefs¶
my $tester = Test::Weaken::leaks( sub { Buggy_Object->new() } );
if ($tester) {
my $unfreed_proberefs = $tester->unfreed_proberefs();
foreach my $ref (@$unfreed_proberefs) {
print "unfreed: $ref\n";
}
}
Return an arrayref of references to unfreed data objects. Throws an exception if
there is a problem, for example if the tester has not yet been evaluated.
The return value can be examined to pinpoint the source of a leak or produce
statistics about unfreed data objects.
unfreed_count¶
my $tester = Test::Weaken::leaks( sub { Buggy_Object->new() } );
if ($tester) {
printf "%d objects were not freed\n",
$tester->unfreed_count();
}
Return the count of unfreed data objects. This is the length of the
"unfreed_proberefs()" arrayref. Throws an exception if there is a
problem, for example if the tester has not yet been evaluated.
probe_count¶
my $tester = Test::Weaken::leaks(
{ constructor => sub { Buggy_Object->new() },
destructor => \&destroy_buggy_object,
}
);
next TEST if not $tester;
printf "%d of %d objects were not freed\n",
$tester->unfreed_count(), $tester->probe_count();
Return the total number of probe references in the test, including references to
freed data objects. This is the count of probe references after
"Test::Weaken" was finished finding the descendants of the test
structure reference, but before "Test::Weaken" called the test
structure destructor or reset the test structure reference to
"undef". Throws an exception if there is a problem, for example if
the tester has not yet been evaluated.
PLUMBING METHODS¶
Most users can skip this section. The plumbing methods exist to satisfy
object-oriented purists, and to accommodate the rare user who wants to access
the probe counts even when the test did find any unfreed data objects.
new¶
my $tester = Test::Weaken->new( sub { My_Object->new() } );
my $unfreed_count = $tester->test();
my $proberefs = $tester->unfreed_proberefs();
printf "%d of %d objects freed\n",
$unfreed_count,
$tester->probe_count();
The "new" method takes the same arguments as the "leaks"
method, described above. Unlike the "leaks" method, it always
returns an
unevaluated tester. An
unevaluated tester is one on
which the test has not yet been run and for which results are not yet
available. If there are any problems, the "new" method throws an
exception.
The "test" method is the only method that can be called successfully
on an unevaluated tester. Calling any other method on an unevaluated tester
causes an exception to be thrown.
test¶
my $tester = Test::Weaken->new(
{ constructor => sub { My_Object->new() },
destructor => \&destroy_my_object,
}
);
printf "There are %s\n", ( $tester->test() ? 'leaks' : 'no leaks' );
Converts an unevaluated tester into an evaluated tester. It does this by
performing the test specified by the arguments to the "new"
constructor and recording the results. Throws an exception if there is a
problem, for example if the tester had already been evaluated.
The "test" method returns the count of unfreed data objects. This will
be identical to the length of the array returned by
"unfreed_proberefs" and the count returned by
"unfreed_count".
ADVANCED TECHNIQUES¶
File Handles¶
File handles are references to GLOBs and by default are not tracked. If a handle
is a package global like "open FH, "</file/name"" then
that's probably what you want. But if you use anonymous handles either from
the Symbol module or Perl 5.6 autovivified then it's good to check the handle
is freed. This can be done by asking for GLOB and IO in
"tracked_types", and extracting the IO from any GLOB encountered,
sub contents_glob_IO {
my ($ref) = @_;
if (ref($ref) eq 'GLOB') {
return *$ref{IO};
} else {
return;
}
}
my $leaks = Test::Weaken::leaks
({ constructor => sub { return MyFileObject->new },
contents => \&contents_glob_IO,
tracked_types => [ 'GLOB', 'IO' ],
});
It's good to check the IO too since it's possible for a reference elsewhere to
keep it alive, in particular a Perl-level "dup" can make another
handle GLOB pointing to that same IO,
open my $dupfh, '<', $fh;
# $dupfh holds and uses *$fh{IO}
See Test::Weaken::ExtraBits for such a "contents_glob_IO()", if you
want to use a module rather than copying couple of lines for that function.
Array and Hash Keys and Values¶
As noted above each value in a hash or array is a separate scalar and is tracked
separately. Usually such scalars are only used in their containing hash or
array, but it's possible to hold a reference to a particular element and
"leaks()" can notice if that causes it to be unfreed.
my %hash = (foo => 123);
my $ref = \$hash{'foo'}; # ref to hash value
It's possible to put specific scalars as the values in a hash or array. They
might be globals or whatever. Usually that would arise from XSUB code, but
Array::RefElem can do the same from Perl code,
use Array::RefElem 'av_store';
my $global;
my @array;
av_store (@array, 0, $global);
In XSUB code a little care is needed that refcounts are correct after
"av_store()" or "hv_store()" takes ownership of one count
etc. In all cases "Test::Weaken" can notice when an array or hash
element doesn't destroy with its container. "ignore" etc will be
needed for those which are intentionally persistent.
Hash keys are not separate scalars. They're strings managed entirely by the hash
and there's nothing separate for "Test::Weaken" to track.
Tie::RefHash and similar which allow arbitrary objects as keys of a hash do so
by using the object "refaddr()" internally as the string key but
presenting objects in "keys()", "each()", etc. As of
Tie::RefHash 1.39 and Tie::RefHash::Weak 0.09 those two modules hold the key
objects within their tie object and therefore those key objects are
successfully reached by "Test::Weaken" for leak checking in the
usual way.
Tracing Leaks¶
Avoidance
"Test::Weaken" makes tracing leaks easier, but avoidance is still by
far the best way, and "Test::Weaken" helps with that. You need to
use test-driven development, Test::More, modular tests in a "t/"
subdirectory, and revision control. These are all very good ideas for many
other reasons.
Make "Test::Weaken" part of your test suite. Test frequently, so that
when a leak occurs, you'll have a good idea of what changes were made since
the last successful test. Often, examining these changes is enough to tell
where the leak was introduced.
Adding Tags
The "unfreed_proberefs" method returns an array containing probes to
the unfreed data objects. This can be used to find the source of leaks. If
circumstances allow it, you might find it useful to add "tag"
elements to arrays and hashes to aid in identifying the source of a leak.
Using Referent Addresses
You can quasi-uniquely identify data objects using the referent addresses of the
probe references. A referent address can be determined by using
"refaddr()" from Scalar::Util. You can also obtain the referent
address of a reference by adding 0 to the reference.
Note that in other Perl documentation, the term "reference address" is
often used when a referent address is meant. Any given reference has both a
reference address and a referent address. The
reference address is the
reference's own location in memory. The
referent address is the address
of the Perl data object to which the reference refers. It is the referent
address that interests us here and, happily, it is the referent address that
both zero addition and refaddr return.
Other Techniques
Sometimes, when you are interested in why an object is not being freed, you want
to seek out the reference that keeps the object's refcount above 0.
Devel::FindRef can be useful for this.
More About Quasi-Unique Addresses¶
I call referent addresses "quasi-unique", because they are only unique
at a specific point in time. Once an object is freed, its address can be
reused. Absent other evidence, a data object with a given referent address is
not 100% certain to be the same data object as the object that had the same
address earlier. This can bite you if you're not careful.
To be sure an earlier data object and a later object with the same address are
actually the same object, you need to know that the earlier object will be
persistent, or to compare the two objects. If you want to be really pedantic,
even an exact match from a comparison doesn't settle the issue. It is possible
that two indiscernable (that is, completely identical) objects with the same
referent address are different in the following sense: the first data object
might have been destroyed and a second, identical, object created at the same
address. But for most practical programming purposes, two indiscernable data
objects can be regarded as the same object.
Debugging Ignore Subroutines¶
check_ignore
$tester = Test::Weaken::leaks(
{ constructor => sub { MyObject->new() },
ignore => Test::Weaken::check_ignore( \&ignore_my_global ),
}
);
$tester = Test::Weaken::leaks(
{ constructor => sub { DeepObject->new() },
ignore => Test::Weaken::check_ignore(
\&cause_deep_problem, 99, 0, $reporting_depth
),
}
);
It can be hard to determine if "ignore" callback subroutines are
inadvertently modifying the test structure. The Test::Weaken::check_ignore
static method is provided to make this task easier. Test::Weaken::check_ignore
constructs a debugging wrapper from four arguments, three of which are
optional. The first argument must be the ignore callback that you are trying
to debug. This callback is called the test subject, or
lab rat.
The second, optional argument, is the maximum error count. Below this count,
errors are reported as warnings using Carp::carp. When the maximum error count
is reached, an exception is thrown using Carp::croak. The maximum error count,
if defined, must be an number greater than or equal to 0. By default the
maximum error count is 1, which means that the first error will be thrown as
an exception.
If the maximum error count is 0, all errors will be reported as warnings and no
exception will ever be thrown. Infinite loops are a common behavior of buggy
lab rats, and setting the maximum error count to 0 will usually not be
something you want to do.
The third, optional, argument is the
compare depth. It is the depth to
which the probe referents will be checked, as described below. It must be a
number greater than or equal to 0. If the compare depth is 0, the probe
referent is checked to unlimited depth. By default the compare depth is 0.
This fourth, optional, argument is the
reporting depth. It is the depth
to which the probe referents are dumped in check_ignore's error messages. It
must be a number greater than or equal to -1. If the reporting depth is 0, the
object is dumped to unlimited depth. If the reporting depth is -1, there is no
dump in the error message. By default, the reporting depth is -1.
Test::Weaken::check_ignore returns a reference to the wrapper callback. If no
problems are detected, the wrapper callback behaves exactly like the lab rat
callback, except that the wrapper is slower.
To discover when and if the lab rat callback is altering its arguments,
Test::Weaken::check_ignore compares the test structure before the lab rat is
called, to the test structure after the lab rat returns.
Test::Weaken::check_ignore compares the before and after test structures in
two ways. First, it dumps the contents of each test structure using
Data::Dumper. For comparison purposes, the dump using Data::Dumper is
performed with "Maxdepth" set to the compare depth as described
above. Second, if the immediate probe referent has builtin type REF,
Test::Weaken::check_ignore determines whether the immediate probe referent is
a weak reference or a strong one.
If either comparison shows a difference, the wrapper treats it as a problem, and
produces an error message. This error message is either a Carp::carp warning
or a Carp::croak exception, depending on the number of error messages already
reported and the setting of the maximum error count. If the reporting depth is
a non-negative number, the error message includes a dump from Data::Dumper of
the test structure. "Data::Dumper"'s "Maxdepth" for
reporting purposes is the reporting depth as described above.
A user who wants other features, such as deep checking of the test structure for
strengthened references, can easily copy "check_ignore()" from the
"Test::Weaken" source and hack it up. "check_ignore()" is
a static method that does not use any "Test::Weaken" package
resources. The hacked version can reside anywhere, and does not need to be
part of the "Test::Weaken" package.
XSUB Mortalizing¶
When a C code XSUB returns a newly created scalar it should
"mortalize" so the scalar is freed once the caller has finished with
it. See "Reference Counts and Mortality" in perlguts. Failing to do
so leaks memory.
SV *ret = newSViv(123);
sv_2mortal (ret); /* must mortalize */
XPUSHs (ret);
"Test::Weaken" can check this by taking a reference to the returned
scalar,
my $leaks = leaks (sub {
return \( somexsub() );
});
if ($leaks) ...
Don't store to a new local scalar and then return that since doing so will only
check the local scalar, not the one made by "somexsub()".
If you want the value for further calculations then first take a reference to
the return and then look through that for the value.
leaks (sub {
my $ref = \( somexsub() );
my $value = $$ref;
# ... do something with $value
return $ref;
});
If an XSUB returns a list of values then take a reference to each as follows.
This works because "map" and "for" make the loop variable
($_ or named) an alias to each value successively (see "map" in
perlfunc and "Foreach Loops" in perlsyn).
leaks (sub {
return [ map {\$_} somexsub() ];
});
# or with a for loop
leaks (sub {
my @refs;
foreach my $value (somexsub()) {
push @refs, \$value;
}
return \@refs;
});
Don't store a returned list to an array (named or anonymous) since this copies
into new scalars in that array and the returned ones from
"somexsub()" then aren't checked.
If you want the returned values for extra calculations then take the references
first and look through them for the values, as in the single case above. For
example,
leaks (sub {
my @refs = map {\$_} somexsub();
my $first_ref = $refs[0]
my $value = $$first_ref;
# ... do something with $value
return \@refs;
});
An XSUB might deliberately return the same scalar each time, perhaps a
pre-calculated constant or a global variable it maintains. In that case the
scalar intentionally won't weaken away and this "leaks()" checking
is not applicable.
Returning the same scalar every time occurs in pure Perl too with an anonymous
constant subr such as created by the "constant" module (see
constant). This is unlikely to arise directly, but might be seen through a
scalar ref within an object etc.
# FOO() returns same scalar every time
*FOO = sub () { 123 };
# same from the constant module
use constant BAR => 456;
It's up to an XSUB etc how long return values are supposed to live. But
generally if the code has any sort of "newSV()" or
"sv_newmortal()" etc to make a new scalar as its return then that
ought to weaken away.
The details of an XSUB return are often hidden in a
typemap file for
brevity and consistency (see "The Typemap" in perlxs). The standard
typemap conversions of
Extutils/typemap are easy to use correctly. But
code with explicit "PUSHs()" etc is worth checking. The reference
counting rules for "av_push()" etc are slightly subtle too if
building nested structures in XS. Usually missing mortalizing or ref count
sinking will leak objects which "Test::Weaken" can detect. Too much
mortalizing or ref count sinking will cause negative refcounts and probable
segfaults.
OLD FUNCTIONS¶
The following "poof()" was from "Test::Weaken" 1.0 and has
been superseded in 2.0 by "leaks()" which is easier to use.
- "my $unfreed_count = Test::Weaken::poof(sub { return $obj
});"
- "my ($weak_count, $strong_count, $weak_unfreed_aref,
$strong_unfreed_aref) = Test::Weaken::poof(sub { return $obj });"
- Check that $obj returned by the given constructor subroutine is freed when
weakened. This is the same as "leaks()" except for the style of
the return values.
In scalar context the return is a count of unfreed references. If everything
is freed then this is 0.
my $unfreed_count = Test::Weaken::poof(sub { return [1,2,3] });
if ($unfreed_count == 0 {
print "No leaks\n";
} else {
print "There were leaks\n";
}
In array context the return is four values
my ($weak_count, $strong_count,
$weak_unfreed_aref, $strong_unfreed_aref)
= Test::Weaken::poof (sub { return $obj });
$weak_count count of weak refs examined
$strong_count count of strong refs examined
$weak_unfreed_aref arrayref of unfreed weak refs
$strong_unfreed_aref arrayref of unfreed strong refs
The counts are total references examined. The arrayrefs give the unfreed
ones. A distinction is made between strong references and weak references
in the test structure. If there's no leaks then both $weak_unfreed_aref
and $strong_unfreed_aref are empty arrays.
There's usually not much interest in whether an unfreed thing was from a
weak or strong reference. In the new "leaks()" the
"unfreed_proberefs()" gives both together. The could be
separated there by checking "isweak()" on each if desired.
IMPLEMENTATION DETAILS¶
Overview¶
"Test::Weaken" first recurses through the test structure. Starting
from the test structure reference, it examines data objects for children
recursively, until it has found the complete contents of the test structure.
The test structure is explored to unlimited depth. For each tracked Perl data
object, a probe reference is created. Tracked data objects are recorded. In
the recursion, no object is visited twice, and infinite loops will not occur,
even in the presence of cycles.
Once recursion through the test structure is complete, the probe references are
weakened. This prevents the probe references from interfering with the normal
deallocation of memory. Next, the test structure destructor is called, if
there is one.
Finally, the test structure reference is set to "undef". This should
trigger the deallocation of the entire contents of the test structure. To
check that this happened, "Test::Weaken" dereferences the probe
references. If the referent of a probe reference was deallocated, the value of
that probe reference will be "undef". If a probe reference is still
defined at this point, it refers to an unfreed Perl data object.
Why the Test Structure is Passed Via a Closure¶
"Test::Weaken" gets its test structure reference indirectly, as the
return value from a
test structure constructor. Why so roundabout?
Because the indirect way is the easiest. When you create the test structure in
"Test::Weaken"'s calling environment, it takes a lot of craft to
avoid leaving unintended references to the test structure in that calling
environment. It is easy to get this wrong. Those unintended references will
create memory leaks that are artifacts of the test environment. Leaks that are
artifacts of the test environment are very difficult to sort out from the real
thing.
The
closure-local strategy is the easiest way to avoid leaving unintended
references to the contents of Perl data objects. Using the closure-local
strategy means working entirely within a closure, using only data objects
local to that closure. Data objects local to a closure will be destroyed when
the closure returns, and any references they held will be released. The
closure-local strategy makes it relatively easy to be sure that nothing is
left behind that will hold an unintended reference to any of the contents of
the test structure.
Nothing prevents a user from subverting the closure-local strategy. A test
structure constructor can return a reference to a test structure created from
Perl data objects in any scope the user desires.
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
SUPPORT¶
You can find documentation for this module with the perldoc command.
perldoc Test::Weaken
You can also look for information at:
- •
- AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Test-Weaken
<http://annocpan.org/dist/Test-Weaken>
- •
- CPAN Ratings
http://cpanratings.perl.org/d/Test-Weaken
<http://cpanratings.perl.org/d/Test-Weaken>
- •
- RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Weaken
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Weaken>
- •
- Search CPAN
http://search.cpan.org/dist/Test-Weaken
<http://search.cpan.org/dist/Test-Weaken>
SEE ALSO¶
Test::Weaken::ExtraBits, miscellaneous extras
Test::Weaken::Gtk2, extras for use with Gtk2-Perl
Scalar::Util, Scalar::Util::Instance
"Test::Weaken" at this point is robust and has seen extensive use. Its
tracking of memory is careful enough that it has even stumbled upon a bug in
perl itself <
http://rt.perl.org/rt3/Public/Bug/Display.html?id=67838>.
ACKNOWLEDGEMENTS¶
Thanks to jettero, Juerd, morgon and perrin of Perlmonks for their advice.
Thanks to Lincoln Stein (developer of Devel::Cycle) for test cases and other
ideas. Kevin Ryde made many important suggestions and provided the test cases
which provided the impetus for the versions 2.000000 and after. For version
3.000000, Kevin also provided patches.
LICENSE AND COPYRIGHT¶
Copyright 2012 Jeffrey Kegler, all rights reserved.
Copyright 2012 Kevin Ryde
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl 5.10.