יובל קוג'מן (Yuval Kogman) > Tie-RefHash-Weak-0.09 > Tie::RefHash::Weak

Download:
Tie-RefHash-Weak-0.09.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.09   Source  

NAME ^

Tie::RefHash::Weak - A Tie::RefHash subclass with weakened references in the keys.

SYNOPSIS ^

        use Tie::RefHash::Weak;
        tie my %h, 'Tie::RefHash::Weak';

        # OR:

        use Tie::RefHash::Weak 'fieldhash';
        fieldhash my %h;

        { # new scope
                my $val = "foo";

                $h{\$val} = "bar"; # key is weak ref
        
                print join(", ", keys %h); # contains \$val, returns regular reference
        }
        # $val goes out of scope, refcount goes to zero
        # weak references to \$val are now undefined

        keys %h; # no longer contains \$val

        # see also Tie::RefHash

DESCRIPTION ^

The Tie::RefHash module can be used to access hashes by reference. This is useful when you index by object, for example.

The problem with Tie::RefHash, and cross indexing, is that sometimes the index should not contain strong references to the objecs. Tie::RefHash's internal structures contain strong references to the key, and provide no convenient means to make those references weak.

This subclass of Tie::RefHash has weak keys, instead of strong ones. The values are left unaltered, and you'll have to make sure there are no strong references there yourself.

FUNCTIONS ^

For compatibility with Hash::Util::FieldHash, this module will, upon request, export the following two functions. You may also write use Tie::RefHash::Weak ':all'.

fieldhash %hash

This ties the hash and returns a reference to it.

fieldhashes \%hash1, \%hash2 ...

This ties each hash that is passed to it as a reference. It returns the list of references in list context, or the number of hashes in scalar context.

THREAD SAFETY ^

Tie::RefHash version 1.32 and above have correct handling of threads (with respect to changing reference addresses). If your module requires Tie::RefHash::Weak to be thread aware you need to depend on both Tie::RefHash::Weak and Tie::RefHash version 1.32 (or later).

Version 0.02 and later of Tie::RefHash::Weak depend on a thread-safe version of Tie::RefHash anyway, so if you are using the latest version this should already be taken care of for you.

5.10.0 COMPATIBILITY ^

Due to a minor change in Perl 5.10.0 a bug in the handling of magic freeing was uncovered causing segmentation faults.

This has been patched but not released yet, as of 0.08.

CAVEAT ^

You can use an LVALUE reference (such as \substr ...) as a hash key, but due to a bug in perl (see http://rt.perl.org/rt3/Public/Bug/Display.html?id=46943) it might not be possible to weaken a reference to it, in which case the hash element will never be deleted automatically.

AUTHORS ^

Yuval Kogman <nothingmuch@woobling.org>

some maintenance by Hans Dieter Pearcey <hdp@pobox.com>

COPYRIGHT & LICENSE ^

        Copyright (c) 2004 Yuval Kogman. All rights reserved
        This program is free software; you can redistribute
        it and/or modify it under the same terms as Perl itself.

SEE ALSO ^

Tie::RefHash, Class::DBI (the live object cache), "Perl_magic_killbackrefs" in mg.c

syntax highlighting: