local-lib5/man/man3/Class::Singleton.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Class::Singleton 3"
 127 .TH Class::Singleton 3 "2007-09-28" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Class::Singleton \- Implementation of a "Singleton" class
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    use Class::Singleton;
 138 \&
 139 \&    my $one = Class::Singleton\->instance();   # returns a new instance
 140 \&    my $two = Class::Singleton\->instance();   # returns same instance
 141 .Ve
 142 .SH "DESCRIPTION"
 143 .IX Header "DESCRIPTION"
 144 This is the \f(CW\*(C`Class::Singleton\*(C'\fR module.  A Singleton describes an object class
 145 that can have only one instance in any system.  An example of a Singleton
 146 might be a print spooler or system registry.  This module implements a
 147 Singleton class from which other classes can be derived.  By itself, the
 148 \&\f(CW\*(C`Class::Singleton\*(C'\fR module does very little other than manage the instantiation
 149 of a single object.  In deriving a class from \f(CW\*(C`Class::Singleton\*(C'\fR, your module
 150 will inherit the Singleton instantiation method and can implement whatever
 151 specific functionality is required.
 152 .PP
 153 For a description and discussion of the Singleton class, see
 154 \&\*(L"Design Patterns\*(R", Gamma et al, Addison-Wesley, 1995, \s-1ISBN\s0 0\-201\-63361\-2.
 155 .SH "PREREQUISITES"
 156 .IX Header "PREREQUISITES"
 157 \&\f(CW\*(C`Class::Singleton\*(C'\fR requires Perl version 5.004 or later. If you have an older
 158 version of Perl, please upgrade to latest version, available from your nearest
 159 \&\s-1CPAN\s0 site (see \s-1INSTALLATION\s0 below).
 160 .SH "INSTALLATION"
 161 .IX Header "INSTALLATION"
 162 The \f(CW\*(C`Class::Singleton\*(C'\fR module is available from \s-1CPAN\s0. As the 'perlmod' man
 163 page explains:
 164 .PP
 165 .Vb 3
 166 \&    CPAN stands for the Comprehensive Perl Archive Network.
 167 \&    This is a globally replicated collection of all known Perl
 168 \&    materials, including hundreds of unbunded modules.
 169 \&
 170 \&    [...]
 171 \&
 172 \&    For an up\-to\-date listing of CPAN sites, see
 173 \&    http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ .
 174 .Ve
 175 .PP
 176 The module is available in the following directories:
 177 .PP
 178 .Vb 2
 179 \&    /modules/by\-module/Class/Class\-Singleton\-<version>.tar.gz
 180 \&    /authors/id/ABW/Class\-Singleton\-<version>.tar.gz
 181 .Ve
 182 .PP
 183 \&\f(CW\*(C`Class::Singleton\*(C'\fR is distributed as a single gzipped tar archive file:
 184 .PP
 185 .Vb 1
 186 \&    Class\-Singleton\-<version>.tar.gz
 187 .Ve
 188 .PP
 189 Note that \*(L"<version>\*(R" represents the current version number, of the
 190 form "\f(CW1.23\fR".  See \s-1VERSION\s0 below to determine the current version
 191 number for \f(CW\*(C`Class::Singleton\*(C'\fR.
 192 .PP
 193 Unpack the archive to create an installation directory:
 194 .PP
 195 .Vb 2
 196 \&    gunzip Class\-Singleton\-<version>.tar.gz
 197 \&    tar xvf Class\-Singleton\-<version>.tar
 198 .Ve
 199 .PP
 200 \&'cd' into that directory, make, test and install the module:
 201 .PP
 202 .Vb 5
 203 \&    cd Class\-Singleton\-<version>
 204 \&    perl Makefile.PL
 205 \&    make
 206 \&    make test
 207 \&    make install
 208 .Ve
 209 .PP
 210 The '\f(CW\*(C`make install\*(C'\fR' will install the module on your system.  You may need
 211 root access to perform this task.  If you install the module in a local
 212 directory (for example, by executing "\f(CW\*(C`perl Makefile.PL LIB=~/lib\*(C'\fR" in the
 213 above \- see \f(CW\*(C`perldoc MakeMaker\*(C'\fR for full details), you will need to ensure
 214 that the \f(CW\*(C`PERL5LIB\*(C'\fR environment variable is set to include the location, or
 215 add a line to your scripts explicitly naming the library location:
 216 .PP
 217 .Vb 1
 218 \&    use lib \*(Aq/local/path/to/lib\*(Aq;
 219 .Ve
 220 .SH "USING THE CLASS::SINGLETON MODULE"
 221 .IX Header "USING THE CLASS::SINGLETON MODULE"
 222 To import and use the \f(CW\*(C`Class::Singleton\*(C'\fR module the following line should
 223 appear in your Perl program:
 224 .PP
 225 .Vb 1
 226 \&    use Class::Singleton;
 227 .Ve
 228 .PP
 229 The \fIinstance()\fR method is used to create a new \f(CW\*(C`Class::Singleton\*(C'\fR instance,
 230 or return a reference to an existing instance. Using this method, it is only
 231 possible to have a single instance of the class in any system.
 232 .PP
 233 .Vb 1
 234 \&    my $highlander = Class::Singleton\->instance();
 235 .Ve
 236 .PP
 237 Assuming that no \f(CW\*(C`Class::Singleton\*(C'\fR object currently exists, this first call
 238 to \fIinstance()\fR will create a new \f(CW\*(C`Class::Singleton\*(C'\fR and return a reference
 239 to it. Future invocations of \fIinstance()\fR will return the same reference.
 240 .PP
 241 .Vb 1
 242 \&    my $macleod    = Class::Singleton\->instance();
 243 .Ve
 244 .PP
 245 In the above example, both \f(CW$highlander\fR and \f(CW$macleod\fR contain the same
 246 reference to a \f(CW\*(C`Class::Singleton\*(C'\fR instance.  There can be only one.
 247 .SH "DERIVING SINGLETON CLASSES"
 248 .IX Header "DERIVING SINGLETON CLASSES"
 249 A module class may be derived from \f(CW\*(C`Class::Singleton\*(C'\fR and will inherit the
 250 \&\fIinstance()\fR method that correctly instantiates only one object.
 251 .PP
 252 .Vb 2
 253 \&    package PrintSpooler;
 254 \&    use base \*(AqClass::Singleton\*(Aq;
 255 \&
 256 \&    # derived class specific code
 257 \&    sub submit_job {
 258 \&        ...
 259 \&    }
 260 \&
 261 \&    sub cancel_job {
 262 \&        ...
 263 \&    }
 264 .Ve
 265 .PP
 266 The \f(CW\*(C`PrintSpooler\*(C'\fR class defined above could be used as follows:
 267 .PP
 268 .Vb 1
 269 \&    use PrintSpooler;
 270 \&
 271 \&    my $spooler = PrintSpooler\->instance();
 272 \&
 273 \&    $spooler\->submit_job(...);
 274 .Ve
 275 .PP
 276 The \fIinstance()\fR method calls the \fI_new_instance()\fR constructor method the
 277 first and only time a new instance is created. All parameters passed to the
 278 \&\fIinstance()\fR method are forwarded to \fI_new_instance()\fR. In the base class
 279 the \fI_new_instance()\fR method returns a blessed reference to a hash array
 280 containing any arguments passed as either a hash reference or list of named
 281 parameters.
 282 .PP
 283 .Vb 2
 284 \&    package MyConfig;
 285 \&    use base \*(AqClass::Singleton\*(Aq;
 286 \&
 287 \&    sub foo {
 288 \&        shift\->{ foo };
 289 \&    }
 290 \&
 291 \&    sub bar {
 292 \&        shift\->{ bar };
 293 \&    }
 294 \&
 295 \&    package main;
 296 \&
 297 \&    # either: hash reference of named parameters
 298 \&    my $config = MyConfig\->instance({ foo => 10, bar => 20 });
 299 \&
 300 \&    # or: list of named parameters
 301 \&    my $config = MyConfig\->instance( foo => 10, bar => 20 );
 302 \&
 303 \&    print $config\->foo();   # 10
 304 \&    print $config\->bar();   # 20
 305 .Ve
 306 .PP
 307 Derived classes may redefine the \fI_new_instance()\fR method to provide more
 308 specific object initialisation or change the underlying object type (to a list
 309 reference, for example).
 310 .PP
 311 .Vb 3
 312 \&    package MyApp::Database;
 313 \&    use base \*(AqClass::Singleton\*(Aq;
 314 \&    use DBI;
 315 \&
 316 \&    # this only gets called the first time instance() is called
 317 \&    sub _new_instance {
 318 \&        my $class = shift;
 319 \&        my $self  = bless { }, $class;
 320 \&        my $db    = shift || "myappdb";
 321 \&        my $host  = shift || "localhost";
 322 \&
 323 \&        $self\->{ DB } = DBI\->connect("DBI:mSQL:$db:$host")
 324 \&            || die "Cannot connect to database: $DBI::errstr";
 325 \&
 326 \&        # any other initialisation...
 327 \&
 328 \&        return $self;
 329 \&    }
 330 .Ve
 331 .PP
 332 The above example might be used as follows:
 333 .PP
 334 .Vb 1
 335 \&    use MyApp::Database;
 336 \&
 337 \&    # first use \- database gets initialised
 338 \&    my $database = MyApp::Database\->instance();
 339 .Ve
 340 .PP
 341 Some time later on in a module far, far away...
 342 .PP
 343 .Vb 2
 344 \&    package MyApp::FooBar
 345 \&    use MyApp::Database;
 346 \&
 347 \&    # this FooBar object needs access to the database; the Singleton
 348 \&    # approach gives a nice wrapper around global variables.
 349 \&
 350 \&    sub new {
 351 \&        my $class = shift;
 352 \&        bless {
 353 \&            database => MyApp::Database\->instance(),
 354 \&        }, $class;
 355 \&    }
 356 .Ve
 357 .PP
 358 The \f(CW\*(C`Class::Singleton\*(C'\fR \fIinstance()\fR method uses a package variable to store
 359 a reference to any existing instance of the object. This variable,
 360 "\f(CW\*(C`_instance\*(C'\fR", is coerced into the derived class package rather than the base
 361 class package.
 362 .PP
 363 Thus, in the \f(CW\*(C`MyApp::Database\*(C'\fR example above, the instance variable would
 364 be:
 365 .PP
 366 .Vb 1
 367 \&    $MyApp::Database::_instance;
 368 .Ve
 369 .PP
 370 This allows different classes to be derived from \f(CW\*(C`Class::Singleton\*(C'\fR that can
 371 co-exist in the same system, while still allowing only one instance of any one
 372 class to exists. For example, it would be possible to derive both
 373 \&'\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
 374 single instance of \fIeach\fR in a system, rather than a single instance of
 375 \&\fIeither\fR.
 376 .PP
 377 You can use the \fIhas_instance()\fR method to find out if a particular class
 378 already has an instance defined.  A reference to the instance is returned or
 379 \&\f(CW\*(C`undef\*(C'\fR if none is currently defined.
 380 .PP
 381 .Vb 2
 382 \&    my $instance = MyApp::Database\->has_instance()
 383 \&        || warn "No instance is defined yet";
 384 .Ve
 385 .SH "METHODS"
 386 .IX Header "METHODS"
 387 .SS "\fIinstance()\fP"
 388 .IX Subsection "instance()"
 389 This method is called to return a current object instance or create a new
 390 one by calling \fI_new_instance()\fR.
 391 .SS "\fIhas_instance()\fP"
 392 .IX Subsection "has_instance()"
 393 This method returns a reference to any existing instance or \f(CW\*(C`undef\*(C'\fR if none
 394 is defined.
 395 .PP
 396 .Vb 2
 397 \&    my $testing = MySingleton1\->has_instance()
 398 \&        || warn "No instance defined for MySingleton1";
 399 .Ve
 400 .SS "\fI_new_instance()\fP"
 401 .IX Subsection "_new_instance()"
 402 This \*(L"private\*(R" method is called by \fIinstance()\fR to create a new object
 403 instance if one doesn't already exist. It is not intended to be called
 404 directly (although there's nothing to stop you from calling it if you're
 405 really determined to do so).
 406 .PP
 407 It creates a blessed hash reference containing any arguments passed to the
 408 method as either a hash reference or list of named parameters.
 409 .PP
 410 .Vb 2
 411 \&    # either: hash reference of named parameters
 412 \&    my $example1 = MySingleton1\->new({ pi => 3.14, e => 2.718 });
 413 \&
 414 \&    # or: list of named parameters
 415 \&    my $example2 = MySingleton2\->new( pi => 3.14, e => 2.718 );
 416 .Ve
 417 .PP
 418 It is important to remember that the \fIinstance()\fR method will \fIonly\fR call
 419 the \fI\fI_new_instance()\fI\fR method once, so any arguments you pass may be silently
 420 ignored if an instance already exists. You can use the \fIhas_instance()\fR
 421 method to determine if an instance is already defined.
 422 .SH "AUTHOR"
 423 .IX Header "AUTHOR"
 424 Andy Wardley <abw@wardley.org> <http://wardley.org/>
 425 .PP
 426 Thanks to Andreas Koenig for providing some significant speedup patches and
 427 other ideas.
 428 .SH "VERSION"
 429 .IX Header "VERSION"
 430 This is version 1.4, released September 2007
 431 .SH "COPYRIGHT"
 432 .IX Header "COPYRIGHT"
 433 Copyright Andy Wardley 1998\-2007.  All Rights Reserved.
 434 .PP
 435 This module is free software; you can redistribute it and/or
 436 modify it under the same terms as Perl itself.