Tracking and Children

    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

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.

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".

File Handles

    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

    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

"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

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

    $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.

Overview

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

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.