Devil Killer Is Here MiNi Shell
MiNi SheLL

Current Path : /proc/thread-self/root/usr/local/man/man3/
Linux boscustweb5003.eigbox.net 5.4.91 #1 SMP Wed Jan 20 18:10:28 EST 2021 x86_64
Current File : //proc/thread-self/root/usr/local/man/man3/Class::Singleton.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Singleton 3"
.TH Singleton 3 "1999-01-19" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Class::Singleton \- Implementation of a "Singleton" class 
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Class::Singleton;
.Ve
.PP
.Vb 2
\&    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 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.
.PP
For a description and discussion of the Singleton class, see 
\&\*(L"Design Patterns\*(R", Gamma et al, Addison\-Wesley, 1995, \s-1ISBN\s0 0\-201\-63361\-2.
.SH "PREREQUISITES"
.IX Header "PREREQUISITES"
Class::Singleton requires Perl version 5.004 or later.  If you have an older 
version of Perl, please upgrade to latest version.  Perl 5.004 is known 
to be stable and includes new features and bug fixes over previous
versions.  Perl itself is available from your nearest \s-1CPAN\s0 site (see
\&\s-1INSTALLATION\s0 below).
.SH "INSTALLATION"
.IX Header "INSTALLATION"
The Class::Singleton 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.
.Ve
.PP
.Vb 1
\&    [...]
.Ve
.PP
.Vb 2
\&    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
For the latest information on Class-Singleton or to download the latest
pre\-release/beta version of the module, consult the definitive reference:
.PP
.Vb 1
\&    http://www.kfs.org/~abw/perl/
.Ve
.PP
Class::Singleton 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 \*(L"1.23\*(R".  See \s-1REVISION\s0 below to determine the current version 
number for Class::Singleton.
.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 'make install' 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 \*(L"perl Makefile.PL LIB=~/lib\*(R" in the 
above \- see \f(CW\*(C`perldoc MakeMaker\*(C'\fR for full details), you will need to ensure 
that the \s-1PERL5LIB\s0 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 '/local/path/to/lib';
.Ve
.SH "USING THE CLASS::SINGLETON MODULE"
.IX Header "USING THE CLASS::SINGLETON MODULE"
To import and use the Class::Singleton module the following line should 
appear in your Perl script:
.PP
.Vb 1
\&    use Class::Singleton;
.Ve
.PP
The \fIinstance()\fR 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.
.PP
.Vb 1
\&    my $highlander = Class::Singleton->instance();
.Ve
.PP
Assuming that no Class::Singleton object currently exists, this first
call to \fIinstance()\fR will create a new Class::Singleton 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 Class::Singleton instance.  There can be only one.
.SH "DERIVING SINGLETON CLASSES"
.IX Header "DERIVING SINGLETON CLASSES"
A module class may be derived from Class::Singleton and will inherit the 
\&\fIinstance()\fR method that correctly instantiates only one object.
.PP
.Vb 3
\&    package PrintSpooler;
\&    use vars qw(@ISA);
\&    @ISA = qw(Class::Singleton);
.Ve
.PP
.Vb 4
\&    # derived class specific code
\&    sub submit_job {
\&        ...
\&    }
.Ve
.PP
.Vb 3
\&    sub cancel_job {
\&        ...
\&    }
.Ve
.PP
The PrintSpooler class defined above could be used as follows:
.PP
.Vb 1
\&    use PrintSpooler;
.Ve
.PP
.Vb 1
\&    my $spooler = PrintSpooler->instance();
.Ve
.PP
.Vb 1
\&    $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
this method returns a blessed reference to an empty hash array.  Derived 
classes may redefine it to provide specific object initialisation or change
the underlying object type (to a list reference, for example).
.PP
.Vb 4
\&    package MyApp::Database;
\&    use vars qw( $ERROR );
\&    use base qw( Class::Singleton );
\&    use DBI;
.Ve
.PP
.Vb 1
\&    $ERROR = '';
.Ve
.PP
.Vb 6
\&    # 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";
.Ve
.PP
.Vb 6
\&        unless (defined ($self->{ DB } 
\&                         = DBI->connect("DBI:mSQL:$db:$host"))) {
\&            $ERROR = "Cannot connect to database: $DBI::errstr\en";
\&            # return failure;
\&            return undef;
\&        }
.Ve
.PP
.Vb 1
\&        # any other initialisation...
.Ve
.PP
.Vb 3
\&        # return sucess
\&        $self;
\&    }
.Ve
.PP
The above example might be used as follows:
.PP
.Vb 1
\&    use MyApp::Database;
.Ve
.PP
.Vb 3
\&    # first use - database gets initialised
\&    my $database = MyApp::Database->instance();
\&    die $MyApp::Database::ERROR unless defined $database;
.Ve
.PP
Some time later on in a module far, far away...
.PP
.Vb 2
\&    package MyApp::FooBar
\&    use MyApp::Database;
.Ve
.PP
.Vb 2
\&    sub new {
\&        # usual stuff...
.Ve
.PP
.Vb 2
\&        # this FooBar object needs access to the database; the Singleton
\&        # approach gives a nice wrapper around global variables.
.Ve
.PP
.Vb 2
\&        # subsequent use - existing instance gets returned
\&        my $database = MyApp::Database->instance();
.Ve
.PP
.Vb 5
\&        # the new() isn't called if an instance already exists,
\&        # so the above constructor shouldn't fail, but we check
\&        # anyway.  One day things might change and this could be the
\&        # first call to instance()...  
\&        die $MyAppDatabase::ERROR unless defined $database;
.Ve
.PP
.Vb 2
\&        # more stuff...
\&    }
.Ve
.PP
The Class::Singleton \fIinstance()\fR method uses a package variable to store a
reference to any existing instance of the object.  This variable, 
\&\*(L"_instance\*(R", is coerced into the derived class package rather than
the base class package.
.PP
Thus, in the MyApp::Database example above, the instance variable would
be:
.PP
.Vb 1
\&    $MyApp::Database::_instance;
.Ve
.PP
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 exists.  For example, it would be possible to 
derive both 'PrintSpooler' and 'MyApp::Database' from Class::Singleton and
have a single instance of \fIeach\fR in a system, rather than a single 
instance of \fIeither\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Wardley, \f(CW\*(C`<abw@cre.canon.co.uk>\*(C'\fR
.PP
Web Technology Group, Canon Research Centre Europe Ltd.
.PP
Thanks to Andreas Koenig \f(CW\*(C`<andreas.koenig@anima.de>\*(C'\fR for providing
some significant speedup patches and other ideas.
.SH "REVISION"
.IX Header "REVISION"
$Revision: 1.3 $
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 1998 Canon Research Centre Europe Ltd.  All Rights Reserved.
.PP
This module is free software; you can redistribute it and/or modify it under 
the term of the Perl Artistic License.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "Canon Research Centre Europe Perl Pages" 4
.IX Item "Canon Research Centre Europe Perl Pages"
http://www.cre.canon.co.uk/perl/
.IP "The Author's Home Page" 4
.IX Item "The Author's Home Page"
http://www.kfs.org/~abw/
.IP "Design Patterns" 4
.IX Item "Design Patterns"
Class::Singleton is an implementation of the Singleton class described in 
\&\*(L"Design Patterns\*(R", Gamma et al, Addison\-Wesley, 1995, \s-1ISBN\s0 0\-201\-63361\-2
Creat By MiNi SheLL
Email: devilkiller@gmail.com