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.