Class::Singleton(3pm)

1Singleton(3)          User Contributed Perl Documentation         Singleton(3)
2
3
4

NAME

6       Class::Singleton - Implementation of a "Singleton" class
7

SYNOPSIS

9           use Class::Singleton;
10
11           my $one = Class::Singleton->instance();   # returns a new instance
12           my $two = Class::Singleton->instance();   # returns same instance
13

DESCRIPTION

15       This is the Class::Singleton module.  A Singleton describes an object
16       class that can have only one instance in any system.  An example of a
17       Singleton might be a print spooler or system registry.  This module
18       implements a Singleton class from which other classes can be derived.
19       By itself, the Class::Singleton module does very little other than man‐
20       age the instantiation of a single object.  In deriving a class from
21       Class::Singleton, your module will inherit the Singleton instantiation
22       method and can implement whatever specific functionality is required.
23
24       For a description and discussion of the Singleton class, see "Design
25       Patterns", Gamma et al, Addison-Wesley, 1995, ISBN 0-201-63361-2.
26

PREREQUISITES

28       Class::Singleton requires Perl version 5.004 or later.  If you have an
29       older version of Perl, please upgrade to latest version.  Perl 5.004 is
30       known to be stable and includes new features and bug fixes over previ‐
31       ous versions.  Perl itself is available from your nearest CPAN site
32       (see INSTALLATION below).
33

INSTALLATION

35       The Class::Singleton module is available from CPAN. As the 'perlmod'
36       man page explains:
37
38           CPAN stands for the Comprehensive Perl Archive Network.
39           This is a globally replicated collection of all known Perl
40           materials, including hundreds of unbunded modules.
41
42           [...]
43
44           For an up-to-date listing of CPAN sites, see
45           http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ .
46
47       The module is available in the following directories:
48
49           /modules/by-module/Class/Class-Singleton-<version>.tar.gz
50           /authors/id/ABW/Class-Singleton-<version>.tar.gz
51
52       For the latest information on Class-Singleton or to download the latest
53       pre-release/beta version of the module, consult the definitive refer‐
54       ence:
55
56           http://www.kfs.org/~abw/perl/
57
58       Class::Singleton is distributed as a single gzipped tar archive file:
59
60           Class-Singleton-<version>.tar.gz
61
62       Note that "<version>" represents the current version number, of the
63       form "1.23".  See REVISION below to determine the current version num‐
64       ber for Class::Singleton.
65
66       Unpack the archive to create an installation directory:
67
68           gunzip Class-Singleton-<version>.tar.gz
69           tar xvf Class-Singleton-<version>.tar
70
71       'cd' into that directory, make, test and install the module:
72
73           cd Class-Singleton-<version>
74           perl Makefile.PL
75           make
76           make test
77           make install
78
79       The 'make install' will install the module on your system.  You may
80       need root access to perform this task.  If you install the module in a
81       local directory (for example, by executing "perl Makefile.PL LIB=~/lib"
82       in the above - see "perldoc MakeMaker" for full details), you will need
83       to ensure that the PERL5LIB environment variable is set to include the
84       location, or add a line to your scripts explicitly naming the library
85       location:
86
87           use lib '/local/path/to/lib';
88

USING THE CLASS::SINGLETON MODULE

90       To import and use the Class::Singleton module the following line should
91       appear in your Perl script:
92
93           use Class::Singleton;
94
95       The instance() method is used to create a new Class::Singleton
96       instance, or return a reference to an existing instance.  Using this
97       method, it is only possible to have a single instance of the class in
98       any system.
99
100           my $highlander = Class::Singleton->instance();
101
102       Assuming that no Class::Singleton object currently exists, this first
103       call to instance() will create a new Class::Singleton and return a ref‐
104       erence to it.  Future invocations of instance() will return the same
105       reference.
106
107           my $macleod    = Class::Singleton->instance();
108
109       In the above example, both $highlander and $macleod contain the same
110       reference to a Class::Singleton instance.  There can be only one.
111

DERIVING SINGLETON CLASSES

113       A module class may be derived from Class::Singleton and will inherit
114       the instance() method that correctly instantiates only one object.
115
116           package PrintSpooler;
117           use vars qw(@ISA);
118           @ISA = qw(Class::Singleton);
119
120           # derived class specific code
121           sub submit_job {
122               ...
123           }
124
125           sub cancel_job {
126               ...
127           }
128
129       The PrintSpooler class defined above could be used as follows:
130
131           use PrintSpooler;
132
133           my $spooler = PrintSpooler->instance();
134
135           $spooler->submit_job(...);
136
137       The instance() method calls the _new_instance() constructor method the
138       first and only time a new instance is created.  All parameters passed
139       to the instance() method are forwarded to _new_instance().  In the base
140       class this method returns a blessed reference to an empty hash array.
141       Derived classes may redefine it to provide specific object initialisa‐
142       tion or change the underlying object type (to a list reference, for
143       example).
144
145           package MyApp::Database;
146           use vars qw( $ERROR );
147           use base qw( Class::Singleton );
148           use DBI;
149
150           $ERROR = '';
151
152           # this only gets called the first time instance() is called
153           sub _new_instance {
154               my $class = shift;
155               my $self  = bless { }, $class;
156               my $db    = shift ⎪⎪ "myappdb";
157               my $host  = shift ⎪⎪ "localhost";
158
159               unless (defined ($self->{ DB }
160                                = DBI->connect("DBI:mSQL:$db:$host"))) {
161                   $ERROR = "Cannot connect to database: $DBI::errstr\n";
162                   # return failure;
163                   return undef;
164               }
165
166               # any other initialisation...
167
168               # return sucess
169               $self;
170           }
171
172       The above example might be used as follows:
173
174           use MyApp::Database;
175
176           # first use - database gets initialised
177           my $database = MyApp::Database->instance();
178           die $MyApp::Database::ERROR unless defined $database;
179
180       Some time later on in a module far, far away...
181
182           package MyApp::FooBar
183           use MyApp::Database;
184
185           sub new {
186               # usual stuff...
187
188               # this FooBar object needs access to the database; the Singleton
189               # approach gives a nice wrapper around global variables.
190
191               # subsequent use - existing instance gets returned
192               my $database = MyApp::Database->instance();
193
194               # the new() isn't called if an instance already exists,
195               # so the above constructor shouldn't fail, but we check
196               # anyway.  One day things might change and this could be the
197               # first call to instance()...
198               die $MyAppDatabase::ERROR unless defined $database;
199
200               # more stuff...
201           }
202
203       The Class::Singleton instance() method uses a package variable to store
204       a reference to any existing instance of the object.  This variable,
205       "_instance", is coerced into the derived class package rather than the
206       base class package.
207
208       Thus, in the MyApp::Database example above, the instance variable would
209       be:
210
211           $MyApp::Database::_instance;
212
213       This allows different classes to be derived from Class::Singleton that
214       can co-exist in the same system, while still allowing only one instance
215       of any one class to exists.  For example, it would be possible to
216       derive both 'PrintSpooler' and 'MyApp::Database' from Class::Singleton
217       and have a single instance of each in a system, rather than a single
218       instance of either.
219

AUTHOR

221       Andy Wardley, "<abw@cre.canon.co.uk>"
222
223       Web Technology Group, Canon Research Centre Europe Ltd.
224
225       Thanks to Andreas Koenig "<andreas.koenig@anima.de>" for providing some
226       significant speedup patches and other ideas.
227

REVISION

229       $Revision: 1.3 $
230

COPYRIGHT

232       Copyright (C) 1998 Canon Research Centre Europe Ltd.  All Rights
233       Reserved.
234
235       This module is free software; you can redistribute it and/or modify it
236       under the term of the Perl Artistic License.
237