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.
UsingtheClass::SingletonModule
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.
DerivingSingletonClasses
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 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.
my $instance = MyApp::Database->has_instance()
|| warn "No instance is defined yet";
Methodsinstance()
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.
Install Now
PNG Icons
