README
1NAME
2 Class::Singleton - Implementation of a "Singleton" class
3
4SYNOPSIS
5 use Class::Singleton;
6
7 my $one = Class::Singleton->instance(); # returns a new instance
8 my $two = Class::Singleton->instance(); # returns same instance
9
10DESCRIPTION
11 This is the Class::Singleton module. A Singleton describes an
12 object class that can have only one instance in any system. An
13 example of a Singleton might be a print spooler or system
14 registry. This module implements a Singleton class from which
15 other classes can be derived. By itself, the Class::Singleton
16 module does very little other than manage the instantiation of a
17 single object. In deriving a class from Class::Singleton, your
18 module will inherit the Singleton instantiation method and can
19 implement whatever specific functionality is required.
20
21 For a description and discussion of the Singleton class, see
22 "Design Patterns", Gamma et al, Addison-Wesley, 1995, ISBN 0-
23 201-63361-2.
24
25PREREQUISITES
26 Class::Singleton requires Perl version 5.004 or later. If you
27 have an older version of Perl, please upgrade to latest version.
28 Perl 5.004 is known to be stable and includes new features and
29 bug fixes over previous versions. Perl itself is available from
30 your nearest CPAN site (see INSTALLATION below).
31
32INSTALLATION
33 The Class::Singleton module is available from CPAN. As the
34 'perlmod' man page explains:
35
36 CPAN stands for the Comprehensive Perl Archive Network.
37 This is a globally replicated collection of all known Perl
38 materials, including hundreds of unbunded modules.
39
40 [...]
41
42 For an up-to-date listing of CPAN sites, see
43 http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ .
44
45 The module is available in the following directories:
46
47 /modules/by-module/Class/Class-Singleton-<version>.tar.gz
48 /authors/id/ABW/Class-Singleton-<version>.tar.gz
49
50 For the latest information on Class-Singleton or to download the
51 latest pre-release/beta version of the module, consult the
52 definitive reference:
53
54 http://www.kfs.org/~abw/perl/
55
56 Class::Singleton is distributed as a single gzipped tar archive
57 file:
58
59 Class-Singleton-<version>.tar.gz
60
61 Note that "<version>" represents the current version number, of
62 the form "1.23". See the REVISION manpage below to determine the
63 current version number for Class::Singleton.
64
65 Unpack the archive to create an installation directory:
66
67 gunzip Class-Singleton-<version>.tar.gz
68 tar xvf Class-Singleton-<version>.tar
69
70 'cd' into that directory, make, test and install the module:
71
72 cd Class-Singleton-<version>
73 perl Makefile.PL
74 make
75 make test
76 make install
77
78 The 'make install' will install the module on your system. You
79 may need root access to perform this task. If you install the
80 module in a local directory (for example, by executing "perl
81 Makefile.PL LIB=~/lib" in the above - see `perldoc MakeMaker'
82 for full details), you will need to ensure that the PERL5LIB
83 environment variable is set to include the location, or add a
84 line to your scripts explicitly naming the library location:
85
86 use lib '/local/path/to/lib';
87
88USING THE CLASS::SINGLETON MODULE
89 To import and use the Class::Singleton module the following line
90 should appear in your Perl script:
91
92 use Class::Singleton;
93
94 The instance() method is used to create a new Class::Singleton
95 instance, or return a reference to an existing instance. Using
96 this method, it is only possible to have a single instance of
97 the class in any system.
98
99 my $highlander = Class::Singleton->instance();
100
101 Assuming that no Class::Singleton object currently exists, this
102 first call to instance() will create a new Class::Singleton and
103 return a reference to it. Future invocations of instance() will
104 return the same reference.
105
106 my $macleod = Class::Singleton->instance();
107
108 In the above example, both $highlander and $macleod contain the
109 same reference to a Class::Singleton instance. There can be only
110 one.
111
112DERIVING SINGLETON CLASSES
113 A module class may be derived from Class::Singleton and will
114 inherit the instance() method that correctly instantiates only
115 one object.
116
117 package PrintSpooler;
118 use vars qw(@ISA);
119 @ISA = qw(Class::Singleton);
120
121 # derived class specific code
122 sub submit_job {
123 ...
124 }
125
126 sub cancel_job {
127 ...
128 }
129
130 The PrintSpooler class defined above could be used as follows:
131
132 use PrintSpooler;
133
134 my $spooler = PrintSpooler->instance();
135
136 $spooler->submit_job(...);
137
138 The instance() method calls the _new_instance() constructor
139 method the first and only time a new instance is created. All
140 parameters passed to the instance() method are forwarded to
141 _new_instance(). In the base class this method returns a blessed
142 reference to an empty hash array. Derived classes may redefine
143 it to provide specific object initialisation or change the
144 underlying object type (to a list reference, for example).
145
146 package MyApp::Database;
147 use vars qw( $ERROR );
148 use base qw( Class::Singleton );
149 use DBI;
150
151 $ERROR = '';
152
153 # this only gets called the first time instance() is called
154 sub _new_instance {
155 my $class = shift;
156 my $self = bless { }, $class;
157 my $db = shift || "myappdb";
158 my $host = shift || "localhost";
159
160 unless (defined ($self->{ DB }
161 = DBI->connect("DBI:mSQL:$db:$host"))) {
162 $ERROR = "Cannot connect to database: $DBI::errstr\n";
163 # return failure;
164 return undef;
165 }
166
167 # any other initialisation...
168
169 # return sucess
170 $self;
171 }
172
173 The above example might be used as follows:
174
175 use MyApp::Database;
176
177 # first use - database gets initialised
178 my $database = MyApp::Database->instance();
179 die $MyApp::Database::ERROR unless defined $database;
180
181 Some time later on in a module far, far away...
182
183 package MyApp::FooBar
184 use MyApp::Database;
185
186 sub new {
187 # usual stuff...
188
189 # this FooBar object needs access to the database; the Singleton
190 # approach gives a nice wrapper around global variables.
191
192 # subsequent use - existing instance gets returned
193 my $database = MyApp::Database->instance();
194
195 # the new() isn't called if an instance already exists,
196 # so the above constructor shouldn't fail, but we check
197 # anyway. One day things might change and this could be the
198 # first call to instance()...
199 die $MyAppDatabase::ERROR unless defined $database;
200
201 # more stuff...
202 }
203
204 The Class::Singleton instance() method uses a package variable
205 to store a reference to any existing instance of the object.
206 This variable, "_instance", is coerced into the derived class
207 package rather than the base class package.
208
209 Thus, in the MyApp::Database example above, the instance
210 variable would be:
211
212 $MyApp::Database::_instance;
213
214 This allows different classes to be derived from
215 Class::Singleton that can co-exist in the same system, while
216 still allowing only one instance of any one class to exists. For
217 example, it would be possible to derive both 'PrintSpooler' and
218 'MyApp::Database' from Class::Singleton and have a single
219 instance of *each* in a system, rather than a single instance of
220 *either*.
221
222AUTHOR
223 Andy Wardley, `<abw@cre.canon.co.uk>'
224
225 Web Technology Group, Canon Research Centre Europe Ltd.
226
227 Thanks to Andreas Koenig `<andreas.koenig@anima.de>' for
228 providing some significant speedup patches and other ideas.
229
230REVISION
231 $Revision: 1.3 $
232
233COPYRIGHT
234 Copyright (C) 1998 Canon Research Centre Europe Ltd. All Rights
235 Reserved.
236
237 This module is free software; you can redistribute it and/or
238 modify it under the term of the Perl Artistic License.
239
240SEE ALSO
241 Canon Research Centre Europe Perl Pages
242 http://www.cre.canon.co.uk/perl/
243
244 The Author's Home Page
245 http://www.kfs.org/~abw/
246
247 Design Patterns
248 Class::Singleton is an implementation of the Singleton class
249 described in "Design Patterns", Gamma et al, Addison-Wesley,
250 1995, ISBN 0-201-63361-2
251
252