Debian Codegraph @

README

raw
1 NAME
2
3 Variable::Disposition - helper functions for disposing of variables
4
5 SYNOPSIS
6
7 use feature qw(say);
8 use Variable::Disposition;
9 my $x = [];
10 dispose $x;
11 say '$x is no longer defined';
12
13 DESCRIPTION
14
15 Provides some basic helper functions for making sure variables go away
16 when you want them to.
17
18 Currently provides "dispose" as a default import. To avoid this:
19
20 use Variable::Disposition ();
21
22 In addition, "retain" and "retain_future" are available as optional
23 imports.
24
25 use Variable::Disposition qw(dispose retain retain_future);
26
27 The :all tag can be used to import every available function:
28
29 use Variable::Disposition qw(:all);
30
31 but it would be safer to use a version instead:
32
33 use Variable::Disposition qw(:v1);
34
35 since these are guaranteed not to change in future.
36
37 Other functions for use with Future and IO::Async are likely to be
38 added later.
39
40 FUNCTIONS
41
42 dispose
43
44 Undefines the given variable, then checks that the original ref was
45 destroyed.
46
47 my $x = [1,2,3];
48 dispose $x;
49 # $x is no longer defined.
50
51 This is primarily intended for cases where you no longer need a
52 variable, and want to ensure that you haven't accidentally captured a
53 strong reference to it elsewhere.
54
55 Note that this clears the caller's variable.
56
57 This function is defined with a prototype of ($), since it is only
58 intended for use on scalar variables. To clear multiple variables, use
59 a foreach loop:
60
61 my ($x, $y, $z) = ...;
62 dispose $_ for $x, $y, $z;
63 is($x, undef);
64 is($y, undef);
65 is($z, undef);
66
67 retain
68
69 Keeps a copy of this variable until program exit or "dispose".
70
71 Returns the original variable.
72
73 retain_future
74
75 Holds a copy of the given Future until it's marked ready, then releases
76 our copy. Does not use "dispose", since that could interfere with other
77 callbacks attached to the Future.
78
79 Since Future 0.36, this behaviour is directly available via the
80 "retain" in Future method, so it is recommended to use that instead of
81 this function.
82
83 Returns the original Future.
84
85 SEE ALSO
86
87 * Devel::Refcount - assert_oneref is almost identical to this,
88 although it doesn't clear the variable it's called on
89
90 * Closure::Explicit - provides a sub{} wrapper that will complain if
91 you capture a lexical without explicitly declaring that you're going
92 to do that.
93
94 AUTHOR
95
96 Tom Molesworth <[email protected]>
97
98 LICENSE
99
100 Copyright Tom Molesworth 2014-2015. Licensed under the same terms as
101 Perl itself.
102