Variable::Disposition - helper functions for disposing of variables

       Tom Molesworth <cpan@perlsite.co.uk>

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

       Currently provides "dispose" as a default import. To avoid this:

        use Variable::Disposition ();

       In addition, "retain" and "retain_future" are available as optional imports.

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

       The " :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 Future and IO::Async are likely to be added later.

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 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 foreach loop:

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

   retain
       Keeps a copy of this variable until program exit or "dispose".

       Returns the original variable.

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

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

       Returns the original Future.

       Copyright Tom Molesworth 2014-2015. Licensed under the same terms as Perl itself.

perl v5.36.0                                       2023-11-18                         Variable::Disposition(3pm)

       Variable::Disposition - helper functions for disposing of variables

       •   Devel::Refcount  -  assert_oneref is almost identical to this, although it doesn't clear the variable
           it's called on

       •   Closure::Explicit - provides a sub{} wrapper that will complain if  you  capture  a  lexical  without
           explicitly declaring that you're going to do that.

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