-When the last reference to an object goes away, the object is
-automatically destroyed. (This may even be after you exit, if you've
-stored references in global variables.) If you want to capture control
-just before the object is freed, you may define a DESTROY method in
-your class. It will automatically be called at the appropriate moment,
-and you can do any extra cleanup you need to do. Perl passes a reference
-to the object under destruction as the first (and only) argument. Beware
-that the reference is a read-only value, and cannot be modified by
-manipulating C<$_[0]> within the destructor. The object itself (i.e.
-the thingy the reference points to, namely C<${$_[0]}>, C<@{$_[0]}>,
-C<%{$_[0]}> etc.) is not similarly constrained.
-
-Since DESTROY methods can be called at unpredictable times, it is
-important that you localise any global variables that the method may
-update. In particular, localise C<$@> if you use C<eval {}> and
-localise C<$?> if you use C<system> or backticks.
-
-If you arrange to re-bless the reference before the destructor returns,
-perl will again call the DESTROY method for the re-blessed object after
-the current one returns. This can be used for clean delegation of
-object destruction, or for ensuring that destructors in the base classes
-of your choosing get called. Explicitly calling DESTROY is also possible,
-but is usually never needed.
-
-DESTROY is subject to AUTOLOAD lookup, just like any other method. Hence, if
-your class has an AUTOLOAD method, but does not need any DESTROY actions,
-you probably want to provide a DESTROY method anyway, to prevent an
-expensive call to AUTOLOAD each time an object is freed. As this technique
-makes empty DESTROY methods common, the implementation is optimised so that
-a DESTROY method that is an empty or constant subroutine, and hence could
-have no side effects anyway, is not actually called.
-X<AUTOLOAD> X<DESTROY>
-
-Do not confuse the previous discussion with how objects I<CONTAINED> in the current
-one are destroyed. Such objects will be freed and destroyed automatically
-when the current object is freed, provided no other references to them exist
-elsewhere.
-
-=head2 Summary
-
-That's about all there is to it. Now you need just to go off and buy a
-book about object-oriented design methodology, and bang your forehead
-with it for the next six months or so.
-
-=head2 Two-Phased Garbage Collection
-X<garbage collection> X<GC> X<circular reference>
-X<reference, circular> X<DESTROY> X<destructor>
-
-For most purposes, Perl uses a fast and simple, reference-based
-garbage collection system. That means there's an extra
-dereference going on at some level, so if you haven't built
-your Perl executable using your C compiler's C<-O> flag, performance
-will suffer. If you I<have> built Perl with C<cc -O>, then this
-probably won't matter.
-
-A more serious concern is that unreachable memory with a non-zero
-reference count will not normally get freed. Therefore, this is a bad
-idea:
-
- {
- my $a;
- $a = \$a;
- }
-
-Even thought $a I<should> go away, it can't. When building recursive data
-structures, you'll have to break the self-reference yourself explicitly
-if you don't care to leak. For example, here's a self-referential
-node such as one might use in a sophisticated tree structure:
-
- sub new_node {
- my $class = shift;
- my $node = {};
- $node->{LEFT} = $node->{RIGHT} = $node;
- $node->{DATA} = [ @_ ];
- return bless $node => $class;
- }
-
-If you create nodes like that, they (currently) won't go away unless you
-break their self reference yourself. (In other words, this is not to be
-construed as a feature, and you shouldn't depend on it.)
-
-Almost.
-
-When an interpreter thread finally shuts down (usually when your program
-exits), then a rather costly but complete mark-and-sweep style of garbage
-collection is performed, and everything allocated by that thread gets
-destroyed. This is essential to support Perl as an embedded or a
-multithreadable language. For example, this program demonstrates Perl's
-two-phased garbage collection:
-
- #!/usr/bin/perl
- package Subtle;
-
- sub new {
- my $test;
- $test = \$test;
- warn "CREATING " . \$test;
- return bless \$test;
- }
-
- sub DESTROY {
- my $self = shift;
- warn "DESTROYING $self";
- }
-
- package main;
-
- warn "starting program";
- {
- my $a = Subtle->new;
- my $b = Subtle->new;
- $$a = 0; # break selfref
- warn "leaving block";
- }
-
- warn "just exited block";
- warn "time to die...";
- exit;
-
-When run as F</foo/test>, the following output is produced:
-
- starting program at /foo/test line 18.
- CREATING SCALAR(0x8e5b8) at /foo/test line 7.
- CREATING SCALAR(0x8e57c) at /foo/test line 7.
- leaving block at /foo/test line 23.
- DESTROYING Subtle=SCALAR(0x8e5b8) at /foo/test line 13.
- just exited block at /foo/test line 26.
- time to die... at /foo/test line 27.
- DESTROYING Subtle=SCALAR(0x8e57c) during global destruction.
-
-Notice that "global destruction" bit there? That's the thread
-garbage collector reaching the unreachable.
-
-Objects are always destructed, even when regular refs aren't. Objects
-are destructed in a separate pass before ordinary refs just to
-prevent object destructors from using refs that have been themselves
-destructed. Plain refs are only garbage-collected if the destruct level
-is greater than 0. You can test the higher levels of global destruction
-by setting the PERL_DESTRUCT_LEVEL environment variable, presuming
-C<-DDEBUGGING> was enabled during perl build time.
-See L<perlhack/PERL_DESTRUCT_LEVEL> for more information.
-
-A more complete garbage collection strategy will be implemented
-at a future date.
-
-In the meantime, the best solution is to create a non-recursive container
-class that holds a pointer to the self-referential data structure.
-Define a DESTROY method for the containing object's class that manually
-breaks the circularities in the self-referential structure.
+When the last refernce to an object goes away, the object is destroyed.
+If you only have one reference to an object stored in a lexical scalar,
+the object is destroyed when that lexical goes out of scope. If you
+store the object in a global, that object may not go out of scope until
+the program exits.
+
+If you want to do something when the object is destroyed, you can
+defined a C<DESTROY> method in your class. This method will always be
+called by Perl at the appropriate time.
+
+This is called just like any other method, with the object as the first
+argument. It does not receive any additional arguments.
+
+Because C<DESTROY> methods can be called at any time, you should
+localize any global variables you might update in your C<DESTROY>. In
+particular, if you use C<eval {}> you should localize C<$@>, and if you
+use C<system> or backticks, you should localize C<$?>.
+
+As we saw in the C<AUTOLOAD> example, if you define an C<AUTOLOAD>
+method, this will be called for the C<DESTROY> method, so you need to
+handle this case in your C<AUTOLOAD>.
+
+The order in which objects are destroyed when the program exits is
+unpredictable. This means that any objects contained by your object may
+already have been destroyed. This means you should check that they are
+defined before calling methods on them:
+
+ sub DESTROY {
+ my $self = shift;
+
+ $self->{handle}->close() if $self->{handle};
+ }
+
+You can use the C<${^GLOBAL_PHASE}> variable to detect if you are
+currently in the program exit phase:
+
+ sub DESTROY {
+ my $self = shift;
+
+ return if ${^GLOBAL_PHASE} eq 'DESTRUCT';
+
+ $self->{handle}->close();
+ }
+
+Note that this variable was added in Perl 5.14.0. If you want to detect
+program exit on older versions of Perl, you can use the
+C<Devel::GlobalDestruction> module on CPAN.
+
+=head2 Non-Hashref Objects
+
+All the examples so far have shown objects based on a blessed hash
+reference. However, it's possible to bless any type of reference,
+including scalar refs, glob refs, and code refs. You may see this sort
+of thing when looking at code in the wild.
+
+Here's an example of a module as a blessed scalar:
+
+ package Time;
+
+ sub new {
+ my $class = shift;
+
+ my $time = time;
+ return bless \$time, $class;
+ }
+
+ sub epoch {
+ my $self = shift;
+ return ${ $self };
+ }
+
+ my $time = Time->new();
+ print $time->epoch();
+
+=head2 Inside-Out objects
+
+The Perl community in the past has experimented with a technique
+referred to as "inside-out objects". Without going into the details,
+this was a method of enforcing data hiding for an object. An inside-out
+object stores its data in a lexical class variable rather than in the
+object itself.
+
+This technique was popular for a while, and was recommended in Damian
+Conway's Perl Best Practices. The L<Object::InsideOut> module on CPAN
+provides a comprehensive implementation of this technique, and you may
+see it or other inside-out modules in the wild.
+
+=head2 Pseudo-hashes
+
+The pseudo-hash feature was an experimental feature introduced in
+earlier versions of Perl and removed in 5.10.0. A pseudo-hash is an
+array reference which can be accessed using named keys like a hash. You
+may run in to some code in the wild which uses it. See the L<fields>
+pragma for more information.