view release on metacpan or  search on metacpan

lib/Class/WeakSingleton.pm  view on Meta::CPAN

This is the Class::WeakSingleton module. A Singleton describes an
object class that can have only one instance in any system. An example
of a Singleton might be a print spooler, system registry or database
connection. A "weak" Singleton is not immortal and expires when all
other references to the original instance have expired. This module
implements a Singleton class from which other classes can be derived,
just like L<Class::Singleton>. By itself, the Class::WeakSingleton
module does very little other than manage the instantiation of a
single object. In deriving a class from Class::WeakSingleton, your
module will inherit the Singleton instantiation method and can
implement whatever specific functionality is required.

For a description and discussion of the Singleton class, see
L<Class::Singleton> and "Design Patterns", Gamma et al,
Addison-Wesley, 1995, ISBN 0-201-63361-2.

=head1 SYNOPSIS

  use Class::WeakSingleton;
 
  {
      my $c = Class::WeakSingleton->instance;
      my $d = Class::WeakSingleton->instance;
      die "Mismatch" if $c != $d;
  }   # Class::WeakSingleton->instance expires
  {
      my $e = Class::WeakSingleton->instance;
      {
          my $f = Class::WeakSingleton->instance;
          die "Mismatch" if $e != $f;
      }
  }   # Class::WeakSingleton->instance expires

=head1 OVERRIDABLE CLASS METHODS

=over

=item $singleton = YourClass->instance(...)

Module constructor. Creates an Class::WeakSingleton (or derivative)
instance if one doesn't already exist. A weak reference is stored in
the C<$_instance> variable of the parent package. This means that
classes derived from Class::WeakSingleton will have the variables
defined in *THEIR* package, rather than the Class::WeakSingleton
package. Also, because the stored reference is weak it will be deleted
when all other references to the returned object have been
deleted. The first time the instance is created, the C<<
YourClass->_new_instance(...) >> constructor is called which simply
returns a reference to a blessed hash. This can be overloaded for
custom constructors. Any additional parameters passed to C<<
YourClass->instance(...) >> are forwarded to C<<
YourClass->_new_instance(...) >>.

Returns a normal reference to the existing, or a newly created
Class::WeakSingleton object. If the C<< ->_new_instance(...) >> method
returns an undefined value then the constructer is deemed to have
failed.

=cut

use Scalar::Util 'weaken';

sub instance {

    # instance()

    my $class = shift;

    # get a reference to the _instance variable in the $class package
    my $instance = do {
        ## no critic
        no strict 'refs';
        \${ $class . "::_instance" };
    };

    return $$instance if defined $$instance;

    my $new_instance = $$instance = $class->_new_instance(@_);

    weaken $$instance;

    return $new_instance;
}

=item $singleton = YourClass->_new_instance(...)

Simple constructor which returns a hash reference blessed into the
current class. May be overloaded to create non-hash objects or handle
any specific initialisation required.

Returns a reference to the blessed hash.

=cut

sub _new_instance {
    my $class = shift;

    return bless {}, $class;
}

=back

=head1 USING THE Class::WeakSingleton MODULE

To import and use the Class::WeakSingleton module the following line
should appear in your Perl script:

  use Class::WeakSingleton;

The C<< Class::WeakSingleton->instance(...) >> method is used to
create a new Class::WeakSingleton instance, or return a reference to
an existing instance. Using this method, it is only possible to have a
single instance of the class in any system at any given time. The
instance expires when all references to it also expire.

  {
      my $highlander = Class::WeakSingleton->instance();

Assuming that no Class::WeakSingleton object currently exists, this
first call to C<< Class::WeakSingleton->instance(...) >> will create a
new Class::WeakSingleton object and return a reference to it.  Future
invocations of C<< Class::WeakSingleton->instance(...)  >> will return
the same reference.

      my $macleod    = Class::WeakSingleton->instance();
  }

In the above example, both C<$highlander> and C<$macleod> contain the
same reference to a Class::WeakSingleton instance. There can be only
one.  Except that now that both C<$highlander> and C<$macleod> went
out of scope the singleton did also. So MacLeod is now dead. Boo hoo.

=head1 DERIVING Class::WeakSingleton CLASSES

A module class may be derived from Class::WeakSingleton and will
inherit the C<< ->instance(...) >> method that correctly instantiates
only one object.

  package Database;
  use base 'Class::WeakSingleton';