phpman > perldoc > Class::Singleton(3pm)

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.

  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 private hash to store a reference to any
    existing instance of the object, keyed against the derived class package name.

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

EXPORTS
    *None*.

KNOWN BUGS
    *None*.

FEEDBACK
    Patches, bug reports, suggestions or any other feedback is welcome.

    Patches can be sent as GitHub pull requests at
    <https://github.com/steve-m-hay/Class-Singleton/pulls>.

    Bug reports and suggestions can be made on the CPAN Request Tracker at
    <https://rt.cpan.org/Public/Bug/Report.html?Queue=Class-Singleton>.

    Currently active requests on the CPAN Request Tracker can be viewed at
    <https://rt.cpan.org/Public/Dist/Display.html?Status=Active;Queue=Class-Singleton>.

    Please test this distribution. See CPAN Testers Reports at <https://www.cpantesters.org/> for
    details of how to get involved.

    Previous test results on CPAN Testers Reports can be viewed at
    <https://www.cpantesters.org/distro/C/Class-Singleton.html>.

    Please rate this distribution on CPAN Ratings at
    <https://cpanratings.perl.org/rate/?distribution=Class-Singleton>.

AVAILABILITY
    The latest version of this module is available from CPAN (see "CPAN" in perlmodlib for details)
    at

    <https://metacpan.org/release/Class-Singleton> or

    <https://www.cpan.org/authors/id/S/SH/SHAY/> or

    <https://www.cpan.org/modules/by-module/Class/>.

    The latest source code is available from GitHub at
    <https://github.com/steve-m-hay/Class-Singleton>.

INSTALLATION
    See the INSTALL file.

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

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

    Steve Hay <shay AT cpan.org <mailto:shay AT cpan.org>> is now maintaining Class::Singleton as of
    version 1.5.

COPYRIGHT
    Copyright (C) 1998 Canon Research Centre Europe Ltd.

    Copyright (C) 1998-2008 Andy Wardley. All rights reserved.

    Copyright (C) 2014, 2020 Steve Hay. All rights reserved.

LICENCE
    This module is free software; you can redistribute it and/or modify it under the same terms as
    Perl itself, i.e. under the terms of either the GNU General Public License or the Artistic
    License, as specified in the LICENCE file.

VERSION
    Version 1.6

DATE
    02 Dec 2020

HISTORY
    See the Changes file.