File Coverage

blib/lib/Variable/Disposition.pm

Criterion	Covered	Total	%
statement	25	25	100.0
branch	9	12	75.0
condition			n/a
subroutine	7	7	100.0
pod	3	3	100.0
total	44	47	93.6

package Variable::Disposition;
# ABSTRACT: dispose of variables
use strict;
use warnings;

use parent qw(Exporter);

our $VERSION = '0.005';

=head1 NAME

Variable::Disposition - helper functions for disposing of variables

=head1 SYNOPSIS

 use feature qw(say);
 use Variable::Disposition;
 my $x = [];
 dispose $x;
 say '$x is no longer defined';

=head1 DESCRIPTION

Provides some basic helper functions for making sure variables go away
when you want them to.

Currently provides L as a default import. To avoid this:

 use Variable::Disposition ();

In addition, L and L are available as optional
imports.

 use Variable::Disposition qw(dispose retain retain_future);

The C< :all > tag can be used to import every available function:

 use Variable::Disposition qw(:all);

but it would be safer to use a version instead:

 use Variable::Disposition qw(:v1);

since these are guaranteed not to change in future.

Other functions for use with L and L are likely to be
added later.

=cut

our @EXPORT_OK = qw(dispose retain retain_future);

our %EXPORT_TAGS = (
    all => [ @EXPORT_OK ],
    v1  => [ qw(dispose retain retain_future) ],
);

our @EXPORT = qw(dispose);

use Scalar::Util ();

our %RETAINED;

=head1 FUNCTIONS

=cut

=head2 dispose

Undefines the given variable, then checks that the original ref was destroyed.

 my $x = [1,2,3];
 dispose $x;
 # $x is no longer defined.

This is primarily intended for cases where you no longer need a variable, and want
to ensure that you haven't accidentally captured a strong reference to it elsewhere.

Note that this clears the B's variable.

This function is defined with a prototype of ($), since it is only intended for use
on scalar variables. To clear multiple variables, use a L loop:

 my ($x, $y, $z) = ...;
 dispose $_ for $x, $y, $z;
 is($x, undef);
 is($y, undef);
 is($z, undef);

=cut

sub dispose($) {
    die "Variable not defined" unless defined $_[0];
    die "Variable was not a ref" unless ref $_[0];
    delete $RETAINED{$_[0]}; # just in case we'd previously retained this one
    Scalar::Util::weaken(my $copy = $_[0]);
    undef $_[0];
    die "Variable was not released" if defined $copy;
}

=head2 retain

Keeps a copy of this variable until program exit or L.

Returns the original variable.

=cut

sub retain($) {
    die "Variable not defined" unless defined $_[0];
    die "Variable was not a ref" unless ref $_[0];
    $RETAINED{$_[0]} = $_[0];
    $_[0]
}

=head2 retain_future

Holds a copy of the given L until it's marked ready, then releases our copy.
Does not use L, since that could interfere with other callbacks attached
to the L.

Since Future 0.36, this behaviour is directly available via the L method,
so it is recommended to use that instead of this function.

Returns the original L.

=cut

sub retain_future {
    my ($f) = @_;
    die "Variable does not seem to be a Future, since it has no ->on_ready method" unless $f->can('on_ready');
    return $f->retain;
}

1;

__END__