Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Class::Singleton(3)   User Contributed Perl Documentation  Class::Singleton(3)

       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.

   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

	   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();


       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";

	   This	method is called to return a current object instance or	create
	   a new one by	calling	_new_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";

	   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

	       # 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



       Patches,	bug reports, suggestions or any	other feedback is welcome.

       Patches can be sent as GitHub pull requests at

       Bug reports and suggestions can be made on the CPAN Request Tracker at

       Currently active	requests on the	CPAN Request Tracker can be viewed at

       Please test this	distribution.  See CPAN	Testers	Reports	at
       <> for details of how to get	involved.

       Previous	test results on	CPAN Testers Reports can be viewed at

       Please rate this	distribution on	CPAN Ratings at

       The latest version of this module is available from CPAN	(see "CPAN" in
       perlmodlib for details) at

       <> or

       <> or


       The latest source code is available from	GitHub at

       See the INSTALL file.

       Andy Wardley < <>>

       Thanks to Andreas Koenig	for providing some significant speedup patches
       and other ideas.

       Steve Hay <	<>>	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.

perl v5.32.1			  2020-12-02		   Class::Singleton(3)


Want to link to this manual page? Use this URL:

home | help