Provided by: libclass-singleton-perl_1.4-1_all bug

NAME

       Class::Singleton - Implementation of a "Singleton" class

SYNOPSIS

           use Class::Singleton;

           my $one = Class::Singleton->instance();   # returns a new instance
           my $two = Class::Singleton->instance();   # returns same instance

DESCRIPTION

       This is the "Class::Singleton" 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
       or system registry.  This module implements a Singleton class from which other classes can
       be derived.  By itself, the "Class::Singleton" module does very little other than manage
       the instantiation of a single object.  In deriving a class from "Class::Singleton", 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 "Design Patterns", Gamma et
       al, Addison-Wesley, 1995, ISBN 0-201-63361-2.

PREREQUISITES

       "Class::Singleton" requires Perl version 5.004 or later. If you have an older version of
       Perl, please upgrade to latest version, available from your nearest CPAN site (see
       INSTALLATION below).

INSTALLATION

       The "Class::Singleton" module is available from CPAN. As the 'perlmod' man page explains:

           CPAN stands for the Comprehensive Perl Archive Network.
           This is a globally replicated collection of all known Perl
           materials, including hundreds of unbunded modules.

           [...]

           For an up-to-date listing of CPAN sites, see
           http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ .

       The module is available in the following directories:

           /modules/by-module/Class/Class-Singleton-<version>.tar.gz
           /authors/id/ABW/Class-Singleton-<version>.tar.gz

       "Class::Singleton" is distributed as a single gzipped tar archive file:

           Class-Singleton-<version>.tar.gz

       Note that "<version>" represents the current version number, of the form "1.23".  See
       VERSION below to determine the current version number for "Class::Singleton".

       Unpack the archive to create an installation directory:

           gunzip Class-Singleton-<version>.tar.gz
           tar xvf Class-Singleton-<version>.tar

       'cd' into that directory, make, test and install the module:

           cd Class-Singleton-<version>
           perl Makefile.PL
           make
           make test
           make install

       The '"make install"' will install the module on your system.  You may need root access to
       perform this task.  If you install the module in a local directory (for example, by
       executing ""perl Makefile.PL LIB=~/lib"" in the above - see "perldoc MakeMaker" for full
       details), you will need to ensure that the "PERL5LIB" environment variable is set to
       include the location, or add a line to your scripts explicitly naming the library
       location:

           use lib '/local/path/to/lib';

USING THE CLASS::SINGLETON MODULE

       To import and use the "Class::Singleton" module the following line should appear in your
       Perl program:

           use Class::Singleton;

       The instance() method is used to create a new "Class::Singleton" 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.

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

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

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

       In the above example, both $highlander and $macleod contain the same reference to a
       "Class::Singleton" instance.  There can be only one.

DERIVING SINGLETON CLASSES

       A module class may be derived from "Class::Singleton" and will inherit the instance()
       method that correctly instantiates only one object.

           package PrintSpooler;
           use base 'Class::Singleton';

           # derived class specific code
           sub submit_job {
               ...
           }

           sub cancel_job {
               ...
           }

       The "PrintSpooler" class defined above could be used as follows:

           use PrintSpooler;

           my $spooler = PrintSpooler->instance();

           $spooler->submit_job(...);

       The instance() method calls the _new_instance() constructor method the first and only time
       a new instance is created. All parameters passed to the instance() method are forwarded to
       _new_instance(). In the base class the _new_instance() method returns a blessed reference
       to a hash array containing any arguments passed as either a hash reference or list of
       named parameters.

           package MyConfig;
           use base 'Class::Singleton';

           sub foo {
               shift->{ foo };
           }

           sub bar {
               shift->{ bar };
           }

           package main;

           # either: hash reference of named parameters
           my $config = MyConfig->instance({ foo => 10, bar => 20 });

           # or: list of named parameters
           my $config = MyConfig->instance( foo => 10, bar => 20 );

           print $config->foo();   # 10
           print $config->bar();   # 20

       Derived classes may redefine the _new_instance() method to provide more specific object
       initialisation or change the underlying object type (to a list reference, for example).

           package MyApp::Database;
           use base 'Class::Singleton';
           use DBI;

           # this only gets called the first time instance() is called
           sub _new_instance {
               my $class = shift;
               my $self  = bless { }, $class;
               my $db    = shift || "myappdb";
               my $host  = shift || "localhost";

               $self->{ DB } = DBI->connect("DBI:mSQL:$db:$host")
                   || die "Cannot connect to database: $DBI::errstr";

               # any other initialisation...

               return $self;
           }

       The above example might be used as follows:

           use MyApp::Database;

           # first use - database gets initialised
           my $database = MyApp::Database->instance();

       Some time later on in a module far, far away...

           package MyApp::FooBar
           use MyApp::Database;

           # this FooBar object needs access to the database; the Singleton
           # approach gives a nice wrapper around global variables.

           sub new {
               my $class = shift;
               bless {
                   database => MyApp::Database->instance(),
               }, $class;
           }

       The "Class::Singleton" instance() method uses a package variable to store a reference to
       any existing instance of the object. This variable, ""_instance"", is coerced into the
       derived class package rather than the base class package.

       Thus, in the "MyApp::Database" example above, the instance variable would be:

           $MyApp::Database::_instance;

       This allows different classes to be derived from "Class::Singleton" that can co-exist in
       the same system, while still allowing only one instance of any one class to exists. For
       example, it would be possible to derive both '"PrintSpooler"' and '"MyApp::Database"' from
       "Class::Singleton" and have a single instance of each in a system, rather than a single
       instance of either.

       You can use the has_instance() method to find out if a particular class already has an
       instance defined.  A reference to the instance is returned or "undef" if none is currently
       defined.

           my $instance = MyApp::Database->has_instance()
               || warn "No instance is defined yet";

METHODS

   instance()
       This method is called to return a current object instance or create a new one by calling
       _new_instance().

   has_instance()
       This method returns a reference to any existing instance or "undef" if none is defined.

           my $testing = MySingleton1->has_instance()
               || warn "No instance defined for MySingleton1";

   _new_instance()
       This "private" method is called by instance() to create a new object instance if one
       doesn't already exist. It is not intended to be called directly (although there's nothing
       to stop you from calling it if you're really determined to do so).

       It creates a blessed hash reference containing any arguments passed to the method as
       either a hash reference or list of named parameters.

           # either: hash reference of named parameters
           my $example1 = MySingleton1->new({ pi => 3.14, e => 2.718 });

           # or: list of named parameters
           my $example2 = MySingleton2->new( pi => 3.14, e => 2.718 );

       It is important to remember that the instance() method will only call the _new_instance()
       method once, so any arguments you pass may be silently ignored if an instance already
       exists. You can use the has_instance() method to determine if an instance is already
       defined.

AUTHOR

       Andy Wardley <abw@wardley.org> <http://wardley.org/>

       Thanks to Andreas Koenig for providing some significant speedup patches and other ideas.

VERSION

       This is version 1.4, released September 2007

COPYRIGHT

       Copyright Andy Wardley 1998-2007.  All Rights Reserved.

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