.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Variable::Disposition 3pm"
.TH Variable::Disposition 3pm "2019-08-02" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Variable::Disposition \- helper functions for disposing of variables
.SH "VERSION"
.IX Header "VERSION"
version 0.004
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\& use feature qw(say);
\& use Variable::Disposition;
\& my $x = [];
\& dispose $x;
\& say \*(Aq$x is no longer defined\*(Aq;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides some basic helper functions for making sure variables go away
when you want them to.
.PP
Currently provides \*(L"dispose\*(R" as a default import. To avoid this:
.PP
.Vb 1
\& use Variable::Disposition ();
.Ve
.PP
In addition, \*(L"retain\*(R" and \*(L"retain_future\*(R" are available as optional
imports.
.PP
.Vb 1
\& use Variable::Disposition qw(dispose retain retain_future);
.Ve
.PP
The \f(CW\*(C` :all \*(C'\fR tag can be used to import every available function:
.PP
.Vb 1
\& use Variable::Disposition qw(:all);
.Ve
.PP
but it would be safer to use a version instead:
.PP
.Vb 1
\& use Variable::Disposition qw(:v1);
.Ve
.PP
since these are guaranteed not to change in future.
.PP
Other functions for use with Future and IO::Async are likely to be
added later.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "dispose"
.IX Subsection "dispose"
Undefines the given variable, then checks that the original ref was destroyed.
.PP
.Vb 3
\& my $x = [1,2,3];
\& dispose $x;
\& # $x is no longer defined.
.Ve
.PP
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.
.PP
Note that this clears the \fBcaller\fR's variable.
.PP
This function is defined with a prototype of ($), since it is only intended for use
on scalar variables. To clear multiple variables, use a foreach loop:
.PP
.Vb 5
\& my ($x, $y, $z) = ...;
\& dispose $_ for $x, $y, $z;
\& is($x, undef);
\& is($y, undef);
\& is($z, undef);
.Ve
.SS "retain"
.IX Subsection "retain"
Keeps a copy of this variable until program exit or \*(L"dispose\*(R".
.PP
Returns the original variable.
.SS "retain_future"
.IX Subsection "retain_future"
Holds a copy of the given Future until it's marked ready, then releases our copy.
Does not use \*(L"dispose\*(R", since that could interfere with other callbacks attached
to the Future.
.PP
Returns the original Future.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
Devel::Refcount \- assert_oneref is almost identical to this, although it doesn't clear the variable it's called on
.IP "\(bu" 4
Closure::Explicit \- provides a sub{} wrapper that will complain if you capture a lexical without explicitly declaring that you're going to do that.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tom Molesworth <cpan@perlsite.co.uk>
.SH "LICENSE"
.IX Header "LICENSE"
Copyright Tom Molesworth 2014\-2015. Licensed under the same terms as Perl itself.