NAME
     Class::WeakSingleton - A Singleton that expires when all the references to it expire

SYNOPSIS
     use Class::WeakSingleton;

     {
         my $c = Class::WeakSingleton->instance;
         my $d = Class::WeakSingleton->instance;
         die "Mismatch" if $c != $d;
     }   # Class::WeakSingleton->instance expires
     {
         my $e = Class::WeakSingleton->instance;
         {
             my $f = Class::WeakSingleton->instance;
             die "Mismatch" if $e != $f;
         }
     }   # Class::WeakSingleton->instance expires

DESCRIPTION
    This is the Class::WeakSingleton 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, system registry or database
    connection. A "weak" Singleton is not immortal and expires when all
    other references to the original instance have expired. This module
    implements a Singleton class from which other classes can be derived,
    just like Class::Singleton. By itself, the Class::WeakSingleton module
    does very little other than manage the instantiation of a single object.
    In deriving a class from Class::WeakSingleton, 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 the
    Class::Singleton manpage and "Design Patterns", Gamma et al,
    Addison-Wesley, 1995, ISBN 0-201-63361-2.

PREREQUISITES
    Class::WeakSingleton requires Scalar::Util with the weaken() function.

USING THE CLASS::WEAKSINGLETON MODULE
    To import and use the Class::WeakSingleton module the following line
    should appear in your Perl script:

        use Class::WeakSingleton;

    The instance() method is used to create a new Class::WeakSingleton
    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 at any given time. The instance expires when all references
    to it also expire.

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

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

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

    In the above example, both $highlander and $macleod contain the same
    reference to a Class::Weakingleton instance. There can be only one.
    Except that now that both $highlander and $macleod went out of scope the
    singleton did also. So MacLeod is now dead. Boo hoo.

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

        package Database;
        use vars qw(@ISA);
        @ISA = qw(Class::WeakSingleton);

        # derived class specific code
        sub user_name { $_[0]->{user_name} }
        sub login {
            my $self = shift;

            my ($user_name, $user_password) = @_;

            # ...

            $self->{user_name} = $user_name;

            1;
        }

    The Database class defined above could be used as follows:

        use Database;

        do_somestuff();
        do_somestuff();

        sub do_somestuff {
            my $db = Database->instance();

            $db->login(...);
        }

    The instance() method calls the _new_instance() constructor method the
    first and only time a new instance is created (until the instance
    expires and then it starts over). All parameters passed to the
    instance() method are forwarded to _new_instance(). 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 array reference, for example).

        package MyApp::Database;
        use vars qw( $ERROR );
        use base qw( Class::WeakSingleton );
        use DBI;

        $ERROR = '';

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

            unless (defined ($self->{ DB } 
                             = DBI->connect("DBI:mSQL:$db:$host"))) {
                $ERROR = "Cannot connect to database: $DBI::errstr\n";
                # return failure;
                return undef;
            }

            # any other initialisation...

            # return sucess
            $self;
        }

    The above example might be used as follows:

        use MyApp::Database;

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

        package MyApp::FooBar
        use MyApp::Database;

        sub new {
            # usual stuff...

            # this FooBar object needs access to the database; the Singleton
            # approach gives a nice wrapper around global variables.

            # new instance is returned
            my $database = MyApp::Database->instance();

            # more stuff...
            # call some methods
        }

        sub some_methods {
            # more usual stuff

            # Get the same object that is used in new()
            my $database = MyApp::Database->instance;
        }

    The Class::WeakSingleton 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::WeakSingleton
    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 'Database' and 'MyApp::Database' from
    Class::WeakSingleton and have a single instance of *each* in a system,
    rather than a single instance of *either*.

AUTHOR
    Joshua b. Jore "<jjore@cpan.org>"

    Thanks to Andy Wardley for writing Class::Singleton.

COPYRIGHT
    Copyright (C) 2003 Joshua b. Jore. All Rights Reserved.

    This module is free software; you can redistribute it and/or modify it
    under the term of the Perl Artistic License.

SEE ALSO
    the Class::Singleton manpage
    Design Patterns
        Class::WeakSingleton is an implementation of the Singleton class
        described in "Design Patterns", Gamma et al, Addison-Wesley, 1995,
        ISBN 0-201-63361-2