SYNOPSIS

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/ .

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.

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.

The Class::Singletoninstance() method uses a private hash to store a reference to any existing instance of the object, keyed against the derived class package name.

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 exist. 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.

has_instance()

_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.

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.