Class::Singleton - Implementation of a ``Singleton'' class
use Class::Singleton;
my $one = Class::Singleton->instance(); # returns a new instance
my $two = Class::Singleton->instance(); # returns same instance
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.
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.
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";
- 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.
None.
None.
Patches, bug reports, suggestions or any other feedback is welcome.
Patches can be sent as GitHub pull requests at
https://github.com/steve-m-hay/Class-Singleton/pulls.
Bug reports and suggestions can be made on the CPAN Request Tracker at
https://rt.cpan.org/Public/Bug/Report.html?Queue=Class-Singleton.
Currently active requests on the CPAN Request Tracker can be viewed at
https://rt.cpan.org/Public/Dist/Display.html?Status=Active;Queue=Class-Singleton.
Please test this distribution. See CPAN Testers Reports at
https://www.cpantesters.org/ for details of how to get involved.
Previous test results on CPAN Testers Reports can be viewed at
https://www.cpantesters.org/distro/C/Class-Singleton.html.
Please rate this distribution on CPAN Ratings at
https://cpanratings.perl.org/rate/?distribution=Class-Singleton.
The latest version of this module is available from CPAN (see
perlmodlib/``CPAN'' for details) at
https://metacpan.org/release/Class-Singleton or
https://www.cpan.org/authors/id/S/SH/SHAY/ or
https://www.cpan.org/modules/by-module/Class/.
The latest source code is available from GitHub at
https://github.com/steve-m-hay/Class-Singleton.
See the INSTALL file.
Andy Wardley <abw@wardley.org>
http://wardley.org/.
Thanks to Andreas Koenig for providing some significant speedup patches and
other ideas.
Steve Hay <shay@cpan.org> is now maintaining
Class::Singleton as of version 1.5.
Copyright (C) 1998 Canon Research Centre Europe Ltd.
Copyright (C) 1998-2008 Andy Wardley. All rights reserved.
Copyright (C) 2014, 2020 Steve Hay. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself, i.e. under the terms of either the GNU General Public
License or the Artistic License, as specified in the LICENCE file.
Version 1.6
02 Dec 2020
See the Changes file.
|