NAME

SYNOPSIS

  use Object::Destroyer;
  
  ## Use a standalone destroyer to release something 
  ## when it falls out of scope
  BLOCK: 
  {
      my $tree = HTML::TreeBuilder->new_from_file('somefile.html');
      my $sentry = Object::Destroyer->new( $tree, 'delete' );
      ## Here you can safely die, return, call last BLOCK or next BLOCK.
      ## The tree will be deleted automatically
  }

  ## Use it to break circular references
  {
      my $var;
      $var = \$var;
      my $sentry =  Object::Destroyer->new( sub {undef $var} );
      ## No more memory leaks!
      ## $var will be released when $sentry leaves the block
  }

  ## Destroyer can be used as a nearly transparent wrapper
  ## that will pass on method calls normally.
  {
      my $Mess = Big::Custy::Mess->new;
      print $Mess->hello;
  }
  
  package Big::Crusty::Mess;
  sub new {
      my $self = bless {}, shift;
      $self->populate;
      return Object::Destroyer->new( $self, 'release' );
  }
  sub hello { "Hello World!" }
  sub release { ...actual code to clean-up the memory... }

DESCRIPTION

This results in a "circular" reference, where A refers to B refers to A. Unfortunately, the garbage collector perl uses during runtime is not capable of knowing whether or not something ELSE is referring to these circular references.

In practical terms, this means that object trees in lexically scoped variable ( e.g. "my $Object = Tree->new" ) will not be cleaned up when they fall out of scope, like normal variables. This results in a memory leak for the life of the process, which is a bad thing when using mod_perl or other processes that live for a long time.

Object::Destroyer allows for the creation of "Destroy" handles. The handle is "attached" to the circular relationship, but is not a part of it. When the destroy handle falls out of scope, it will be cleaned up correctly, and while being cleaned up, it will also force the data structure it is attached to to be destroyed as well. Object::Destroyer can call a specified release method on an object (or method DESTROY by default). Alternatively, it can execute an arbitrary user code passed to constructor as a code reference.

  sub plagiarise {
    # Parse in a large nested document
    my $filename = shift;
    my $document = My::XML::Tree->open($filename);
  
    # Create the Object::Destroyer to clean it up as needed
    my $sentry = Object::Destroyer->new( $document, 'release' );
  
    # Continue with the Document as normal
    if ($document->author == $me) {
        # Normally this would have leaked the document
        return new Error("You already own the Document");
    }
    
    $document->change_author($me);
    $document->save;

    # We don't have to $Document->DESTROY here
    return 1;
  }

  {
     $params{other}        = \%other_params;
     $other_params{params} = \%params;

     my $sentry = Object::Destroyer->new( sub {undef $params{other}} );
     ##
     ## From now on, memory of %params will be 
     ## safely released when block is exited.
     ##

     ... code with return, next or last ...
          
  }

  package My::Tree;
  
  use strict;
  use Object::Destroyer;
  
  sub new {
      my $self = bless {}, shift;
      $self->init; ## assume that circular references are made

      ## Return the Object::Destroyer, with ourself inside it
      my $wrapper = Object::Destroyer->new( $self, 'release' );
      return $wrapper;
  }
  
  sub release {
    my $self = shift;
    foreach (values %$self) {
        $_->DESTROY if ref $_ eq 'My::Tree::Node';
    }
    %$self = ();
  }

  sub process_file {
      # Create a new tree
      my $tree = My::Tree->new( source => shift );
  
      # Process the Tree
      if ($tree->comments) {
          $tree->remove_comments or return;
      } 
      else {
          return 1; # Nothing to do
      }
  
      my $filename = $tree->param('target') or return;
      $tree->write($filename) or return;
  
      return 1;
  }

METHODS

new

  my $sentry = Object::Destroyer->new( $object );
  my $sentry = Object::Destroyer->new( $object, 'method_name' );
  my $sentry = Object::Destroyer->new( $code_reference );
    

The "new" constructor takes as arguments either a single blessed object with an optional name of the method to be called, or a refernce to code to be executed. If the method name is not specified, the "DESTROY" method is assumed. The constructor will die if the object passed to it does not have the specified method.

DESTROY

  $sentry->DESTROY;
  undef $sentry;
    

If you wish, you may explicitly DESTROY the Destroyer at any time you wish. This will also DESTROY the encased object at the same. This can allow for legacy cases relating to Wrappers, where a user expects to have to manually DESTROY an object even though it is not needed. The DESTROY call will be accepted and dealt with as it is called on the encased object.

dismiss

  $sentry->dismiss;
    

If you have changed your mind and you don't want Destroyer object to do its job, dismiss it. You may continue to use it as a wrapper, though.

SEE ALSO

For lexically scoped resource management, see also Scope::Guard, Sub::ScopeFinalizer and Hook::Scope.

SUPPORT

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Object-Destroyer>

For other issues, or commercial enhancement or support, contact the Adam Kennedy.

AUTHORS

Igor Gariev <gariev@hotmail.com>

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.