Class::Singleton man page on Scientific

Printed from http://www.polarhome.com/service/man/?qf=Class%3A%3ASingleton&af=0&tf=2&of=Scientific

Class::Singleton(3)   User Contributed Perl Documentation  Class::Singleton(3)

NAME
       Class::Singleton - Implementation of a "Singleton" class

SYNOPSIS
	   use Class::Singleton;

	   my $one = Class::Singleton->instance();   # returns a new instance
	   my $two = Class::Singleton->instance();   # returns same instance

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.

       For a description and discussion of the Singleton class, see "Design
       Patterns", Gamma et al, Addison-Wesley, 1995, ISBN 0-201-63361-2.

PREREQUISITES
       "Class::Singleton" requires Perl version 5.004 or later. If you have an
       older version of Perl, please upgrade to latest version, available from
       your nearest CPAN site (see INSTALLATION below).

INSTALLATION
       The "Class::Singleton" module is available from CPAN. As the 'perlmod'
       man page explains:

	   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/ .

       The module is available in the following directories:

	   /modules/by-module/Class/Class-Singleton-<version>.tar.gz
	   /authors/id/ABW/Class-Singleton-<version>.tar.gz

       "Class::Singleton" is distributed as a single gzipped tar archive file:

	   Class-Singleton-<version>.tar.gz

       Note that "<version>" represents the current version number, of the
       form "1.23".  See VERSION below to determine the current version number
       for "Class::Singleton".

       Unpack the archive to create an installation directory:

	   gunzip Class-Singleton-<version>.tar.gz
	   tar xvf Class-Singleton-<version>.tar

       'cd' into that directory, make, test and install the module:

	   cd Class-Singleton-<version>
	   perl Makefile.PL
	   make
	   make test
	   make install

       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 ""perl Makefile.PL
       LIB=~/lib"" in the above - see "perldoc MakeMaker" for full details),
       you will need to ensure that the "PERL5LIB" environment variable is set
       to include the location, or add a line to your scripts explicitly
       naming the library location:

	   use lib '/local/path/to/lib';

USING THE CLASS::SINGLETON MODULE
       To import and use the "Class::Singleton" module the following line
       should appear in your Perl program:

	   use Class::Singleton;

       The instance() 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.

	   my $highlander = Class::Singleton->instance();

       Assuming that no "Class::Singleton" object currently exists, this first
       call to instance() will create a new "Class::Singleton" and return a
       reference to it. Future invocations of instance() will return the same
       reference.

	   my $macleod	  = Class::Singleton->instance();

       In the above example, both $highlander and $macleod contain the same
       reference to a "Class::Singleton" instance.  There can be only one.

DERIVING SINGLETON CLASSES
       A module class may be derived from "Class::Singleton" and will inherit
       the instance() method that correctly instantiates only one object.

	   package PrintSpooler;
	   use base 'Class::Singleton';

	   # derived class specific code
	   sub submit_job {
	       ...
	   }

	   sub cancel_job {
	       ...
	   }

       The "PrintSpooler" class defined above could be used as follows:

	   use PrintSpooler;

	   my $spooler = PrintSpooler->instance();

	   $spooler->submit_job(...);

       The instance() method calls the _new_instance() constructor method the
       first and only time a new instance is created. All parameters passed to
       the instance() method are forwarded to _new_instance(). In the base
       class the _new_instance() method returns a blessed reference to a hash
       array containing any arguments passed as either a hash reference or
       list of named parameters.

	   package MyConfig;
	   use base 'Class::Singleton';

	   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

       Derived classes may redefine the _new_instance() method to provide more
       specific object initialisation or change the underlying object type (to
       a list reference, for example).

	   package MyApp::Database;
	   use base 'Class::Singleton';
	   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;
	   }

       The above example might be used as follows:

	   use MyApp::Database;

	   # first use - database gets initialised
	   my $database = MyApp::Database->instance();

       Some time later on in a module far, far away...

	   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;
	   }

       The "Class::Singleton" instance() method uses a package variable to
       store a reference to any existing instance of the object. This
       variable, ""_instance"", is coerced into the derived class package
       rather than the base class package.

       Thus, in the "MyApp::Database" example above, the instance variable
       would be:

	   $MyApp::Database::_instance;

       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 each in a system,
       rather than a single instance of either.

       You can use the has_instance() method to find out if a particular class
       already has an instance defined.	 A reference to the instance is
       returned or "undef" if none is currently defined.

	   my $instance = MyApp::Database->has_instance()
	       || warn "No instance is defined yet";

METHODS
   instance()
       This method is called to return a current object instance or create a
       new one by calling _new_instance().

   has_instance()
       This method returns a reference to any existing instance or "undef" if
       none is defined.

	   my $testing = MySingleton1->has_instance()
	       || warn "No instance defined for MySingleton1";

   _new_instance()
       This "private" method is called by instance() 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).

       It creates a blessed hash reference containing any arguments passed to
       the method as either a hash reference or list of named parameters.

	   # 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 );

       It is important to remember that the instance() method will only call
       the _new_instance() method once, so any arguments you pass may be
       silently ignored if an instance already exists. You can use the
       has_instance() method to determine if an instance is already defined.

AUTHOR
       Andy Wardley <abw@wardley.org> <http://wardley.org/>

       Thanks to Andreas Koenig for providing some significant speedup patches
       and other ideas.

VERSION
       This is version 1.4, released September 2007

COPYRIGHT
       Copyright Andy Wardley 1998-2007.  All Rights Reserved.

       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.10.1			  2007-09-28		   Class::Singleton(3)
[top]

List of man pages available for Scientific

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net