1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
=encoding utf8
=for comment POD_DERIVED_INDEX_GENERATED
The following documentation is automatically generated. Please do not edit
this file, but rather the original, inline with Variable::Disposition
at lib/Variable/Disposition.pm
(on the system that originally ran this).
If you do edit this file, and don't want your changes to be removed, make
sure you change the first line.
=cut
=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</dispose> as a default import. To avoid this:
use Variable::Disposition ();
In addition, L</retain> and L</retain_future> 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<Future> and L<IO::Async> are likely to be
added later.
=head1 FUNCTIONS
=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<caller>'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<foreach> loop:
my ($x, $y, $z) = ...;
dispose $_ for $x, $y, $z;
is($x, undef);
is($y, undef);
is($z, undef);
=head2 retain
Keeps a copy of this variable until program exit or L</dispose>.
Returns the original variable.
=head2 retain_future
Holds a copy of the given L<Future> until it's marked ready, then releases our copy.
Does not use L</dispose>, since that could interfere with other callbacks attached
to the L<Future>.
Since Future 0.36, this behaviour is directly available via the L<Future/retain> method,
so it is recommended to use that instead of this function.
Returns the original L<Future>.
=head1 SEE ALSO
=over 4
=item * L<Devel::Refcount> - assert_oneref is almost identical to this, although it doesn't clear the variable it's called on
=item * L<Closure::Explicit> - provides a sub{} wrapper that will complain if you capture a lexical without explicitly declaring that you're going to do that.
=back
=head1 INHERITED METHODS
=over 4
=item L<Exporter>
L<as_heavy|Exporter/as_heavy>, L<export|Exporter/export>, L<export_fail|Exporter/export_fail>, L<export_ok_tags|Exporter/export_ok_tags>, L<export_tags|Exporter/export_tags>, L<export_to_level|Exporter/export_to_level>, L<import|Exporter/import>, L<require_version|Exporter/require_version>
=back
=head1 AUTHOR
Tom Molesworth <cpan@perlsite.co.uk>
=head1 LICENSE
Copyright Tom Molesworth 2014-2015. Licensed under the same terms as Perl itself.
|
