.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Class::Singleton 3"
.TH Class::Singleton 3 "2014-11-08" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Class::Singleton \- Implementation of a "Singleton" class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Class::Singleton;
\&    
\&    my $one = Class::Singleton\->instance();   # returns a new instance
\&    my $two = Class::Singleton\->instance();   # returns same instance
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the \f(CW\*(C`Class::Singleton\*(C'\fR 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
\&\f(CW\*(C`Class::Singleton\*(C'\fR module does very little other than manage the instantiation
of a single object.  In deriving a class from \f(CW\*(C`Class::Singleton\*(C'\fR, your module 
will inherit the Singleton instantiation method and can implement whatever
specific functionality is required.
.PP
For a description and discussion of the Singleton class, see 
\&\*(L"Design Patterns\*(R", Gamma et al, Addison-Wesley, 1995, \s-1ISBN 0\-201\-63361\-2.\s0
.SH "PREREQUISITES"
.IX Header "PREREQUISITES"
\&\f(CW\*(C`Class::Singleton\*(C'\fR requires Perl version 5.004 or later. If you have an older
version of Perl, please upgrade to latest version, available from your nearest
\&\s-1CPAN\s0 site (see \s-1INSTALLATION\s0 below).
.SH "INSTALLATION"
.IX Header "INSTALLATION"
The \f(CW\*(C`Class::Singleton\*(C'\fR module is available from \s-1CPAN.\s0 As the 'perlmod' man
page explains:
.PP
.Vb 3
\&    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/ .
.Ve
.PP
The module is available in the following directories:
.PP
.Vb 2
\&    /modules/by\-module/Class/Class\-Singleton\-<version>.tar.gz
\&    /authors/id/ABW/Class\-Singleton\-<version>.tar.gz
.Ve
.PP
\&\f(CW\*(C`Class::Singleton\*(C'\fR is distributed as a single gzipped tar archive file:
.PP
.Vb 1
\&    Class\-Singleton\-<version>.tar.gz
.Ve
.PP
Note that \*(L"<version>\*(R" represents the current version number, of the 
form "\f(CW1.23\fR".  See \s-1VERSION\s0 below to determine the current version 
number for \f(CW\*(C`Class::Singleton\*(C'\fR.
.PP
Unpack the archive to create an installation directory:
.PP
.Vb 2
\&    gunzip Class\-Singleton\-<version>.tar.gz
\&    tar xvf Class\-Singleton\-<version>.tar
.Ve
.PP
\&'cd' into that directory, make, test and install the module:
.PP
.Vb 5
\&    cd Class\-Singleton\-<version>
\&    perl Makefile.PL
\&    make
\&    make test
\&    make install
.Ve
.PP
The '\f(CW\*(C`make install\*(C'\fR' 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 "\f(CW\*(C`perl Makefile.PL LIB=~/lib\*(C'\fR" in the 
above \- see \f(CW\*(C`perldoc MakeMaker\*(C'\fR for full details), you will need to ensure 
that the \f(CW\*(C`PERL5LIB\*(C'\fR environment variable is set to include the location, or 
add a line to your scripts explicitly naming the library location:
.PP
.Vb 1
\&    use lib \*(Aq/local/path/to/lib\*(Aq;
.Ve
.SH "USING THE CLASS::SINGLETON MODULE"
.IX Header "USING THE CLASS::SINGLETON MODULE"
To import and use the \f(CW\*(C`Class::Singleton\*(C'\fR module the following line should 
appear in your Perl program:
.PP
.Vb 1
\&    use Class::Singleton;
.Ve
.PP
The \fIinstance()\fR method is used to create a new \f(CW\*(C`Class::Singleton\*(C'\fR 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.
.PP
.Vb 1
\&    my $highlander = Class::Singleton\->instance();
.Ve
.PP
Assuming that no \f(CW\*(C`Class::Singleton\*(C'\fR object currently exists, this first call
to \fIinstance()\fR will create a new \f(CW\*(C`Class::Singleton\*(C'\fR and return a reference
to it. Future invocations of \fIinstance()\fR will return the same reference.
.PP
.Vb 1
\&    my $macleod    = Class::Singleton\->instance();
.Ve
.PP
In the above example, both \f(CW$highlander\fR and \f(CW$macleod\fR contain the same
reference to a \f(CW\*(C`Class::Singleton\*(C'\fR instance.  There can be only one.
.SH "DERIVING SINGLETON CLASSES"
.IX Header "DERIVING SINGLETON CLASSES"
A module class may be derived from \f(CW\*(C`Class::Singleton\*(C'\fR and will inherit the 
\&\fIinstance()\fR method that correctly instantiates only one object.
.PP
.Vb 2
\&    package PrintSpooler;
\&    use base \*(AqClass::Singleton\*(Aq;
\&    
\&    # derived class specific code
\&    sub submit_job {
\&        ...
\&    }
\&    
\&    sub cancel_job {
\&        ...
\&    }
.Ve
.PP
The \f(CW\*(C`PrintSpooler\*(C'\fR class defined above could be used as follows:
.PP
.Vb 1
\&    use PrintSpooler;
\&    
\&    my $spooler = PrintSpooler\->instance();
\&    
\&    $spooler\->submit_job(...);
.Ve
.PP
The \fIinstance()\fR method calls the \fI_new_instance()\fR constructor method the
first and only time a new instance is created. All parameters passed to the
\&\fIinstance()\fR method are forwarded to \fI_new_instance()\fR. In the base class
the \fI_new_instance()\fR method returns a blessed reference to a hash array
containing any arguments passed as either a hash reference or list of named 
parameters.
.PP
.Vb 2
\&    package MyConfig;
\&    use base \*(AqClass::Singleton\*(Aq;
\&    
\&    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
.Ve
.PP
Derived classes may redefine the \fI_new_instance()\fR method to provide more
specific object initialisation or change the underlying object type (to a list
reference, for example).
.PP
.Vb 3
\&    package MyApp::Database;
\&    use base \*(AqClass::Singleton\*(Aq;
\&    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;
\&    }
.Ve
.PP
The above example might be used as follows:
.PP
.Vb 1
\&    use MyApp::Database;
\&    
\&    # first use \- database gets initialised
\&    my $database = MyApp::Database\->instance();
.Ve
.PP
Some time later on in a module far, far away...
.PP
.Vb 2
\&    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;
\&    }
.Ve
.PP
The \f(CW\*(C`Class::Singleton\*(C'\fR \fIinstance()\fR method uses a private hash to store
a reference to any existing instance of the object, keyed against the derived
class package name.
.PP
This allows different classes to be derived from \f(CW\*(C`Class::Singleton\*(C'\fR 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
\&'\f(CW\*(C`PrintSpooler\*(C'\fR' and '\f(CW\*(C`MyApp::Database\*(C'\fR' from \f(CW\*(C`Class::Singleton\*(C'\fR and have a
single instance of \fIeach\fR in a system, rather than a single instance of
\&\fIeither\fR.
.PP
You can use the \fIhas_instance()\fR method to find out if a particular class 
already has an instance defined.  A reference to the instance is returned or
\&\f(CW\*(C`undef\*(C'\fR if none is currently defined.
.PP
.Vb 2
\&    my $instance = MyApp::Database\->has_instance()
\&        || warn "No instance is defined yet";
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "\fIinstance()\fP"
.IX Subsection "instance()"
This method is called to return a current object instance or create a new
one by calling \fI_new_instance()\fR.
.SS "\fIhas_instance()\fP"
.IX Subsection "has_instance()"
This method returns a reference to any existing instance or \f(CW\*(C`undef\*(C'\fR if none
is defined.
.PP
.Vb 2
\&    my $testing = MySingleton1\->has_instance()
\&        || warn "No instance defined for MySingleton1";
.Ve
.SS "\fI_new_instance()\fP"
.IX Subsection "_new_instance()"
This \*(L"private\*(R" method is called by \fIinstance()\fR 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).
.PP
It creates a blessed hash reference containing any arguments passed to the
method as either a hash reference or list of named parameters.
.PP
.Vb 2
\&    # 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 );
.Ve
.PP
It is important to remember that the \fIinstance()\fR method will \fIonly\fR call
the \fI\fI_new_instance()\fI\fR method once, so any arguments you pass may be silently
ignored if an instance already exists. You can use the \fIhas_instance()\fR
method to determine if an instance is already defined.
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Wardley <abw@wardley.org> <http://wardley.org/>
.PP
Thanks to Andreas Koenig for providing some significant speedup patches and
other ideas.
.SH "VERSION"
.IX Header "VERSION"
This is version 1.5, released November 2014
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright Andy Wardley 1998\-2007.  All Rights Reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.