use Class::Singleton;
my $one = Class::Singleton->instance(); # returns a new instance
my $two = Class::Singleton->instance(); # returns same instance
For a description and discussion of the Singleton class, see ``Design Patterns'', Gamma et al, Addison-Wesley, 1995, ISBN 0-201-63361-2.
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.
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";
my $testing = MySingleton1->has_instance()
|| warn "No instance defined for MySingleton1";
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.
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>.
<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>.
Thanks to Andreas Koenig for providing some significant speedup patches and other ideas.
Steve Hay <shay@cpan.org <mailto:shay@cpan.org>> is now maintaining Class::Singleton as of version 1.5.
Copyright (C) 1998-2008 Andy Wardley. All rights reserved.
Copyright (C) 2014, 2020 Steve Hay. All rights reserved.