view release on metacpan or  search on metacpan

lib/Anansi/ObjectManager.pm  view on Meta::CPAN

package Anansi::ObjectManager;


=head1 NAME

Anansi::ObjectManager - A module object encapsulation manager

=head1 SYNOPSIS

    package Anansi::Example;

    use Anansi::ObjectManager;

    sub DESTROY {
        my ($self) = @_;
        my $objectManager = Anansi::ObjectManager->new();
        if(1 == $objectManager->registrations($self)) {
            $objectManager->obsolete(
                USER => $self,
            );
            $objectManager->unregister($self);
        }
    }

    sub new {
        my ($class, %parameters) = @_;
        return if(ref($class) =~ /^ (ARRAY|CODE|FORMAT|GLOB|HASH|IO|LVALUE|REF|Regexp|SCALAR|VSTRING)$/i);
        $class = ref($class) if(ref($class) !~ /^$/);
        my $self = {
            NAMESPACE => $class,
            PACKAGE => __PACKAGE__,
        };
        bless($self, $class);
        my $objectManager = Anansi::ObjectManager->new();
        $objectManager->register($self);
        return $self;
    }

    1;

    package main;

    use Anansi::Example;

    my $object = Anansi::Example->new();

    1;

=head1 DESCRIPTION

This is a manager for encapsulating module objects within other module objects
and ensures that the memory used by any module object will only be garbage
collected by the perl run time environment when the module object is no longer
used.  Many of the subroutines/methods declared by this module are for internal
use only but are provided in this context for purposes of module extension.

=cut


our $VERSION = '0.09';

my $NAMESPACE;

my $OBJECTMANAGER = Anansi::ObjectManager->new();


=head1 METHODS

=cut


=head2 current

    my $someObject = Some::Example->new();
    $someObject->{ANOTHER_OBJECT} = Another::Example->new();
    my $objectManager = Anansi::ObjectManager->new();
    $objectManager->current(
        USER => $someObject,
        USES => $someObject->{ANOTHER_OBJECT},
    );

    my $someObject = Some::Example->new();
    $someObject->{ANOTHER_OBJECT} = Another::Example->new();
    $someObject->{YET_ANOTHER_OBJECT} = Yet::Another::Example->new();
    my $objectManager = Anansi::ObjectManager->new();
    $objectManager->current(
        USER => $someObject,
        USES => [$someObject->{ANOTHER_OBJECT}, $someObject->{YET_ANOTHER_OBJECT}],
    );

=over 4

=item self I<(Blessed Hash, Required)>

lib/Anansi/ObjectManager.pm  view on Meta::CPAN

=over 4

=item self I<(Blessed Hash, Required)>

An object of this namespace.

=item parameters I<(Hash, Optional)>

Named parameters.

=back

Performs after creation actions on the first instance object of this module that
is created.

=cut


sub initialise {
    my ($self, %parameters) = @_;
    $self->{IDENTIFICATION} = $self->identification();
    $self->{IDENTIFICATIONS} = [
        $self->{IDENTIFICATION}
    ];
}


=head2 new

    my $objectManager = Anansi::ObjectManager->new();

=over 4

=item class I<(Blessed Hash B<or> String, Required)>

Either an object of this namespace or this module's namespace.

=item parameters I<(Hash, Optional)>

Named parameters.

=back

Instantiates an object instance of this module, ensuring that the object
instance can be interpreted by this module.  This object is a singleton so only
one object will ever be created at any one time by a Perl script.  Subsequent
uses of this subroutine will return the existing object.

=cut


sub new {
    my ($class, %parameters) = @_;
    return if(ref($class) =~ /^(ARRAY|CODE|FORMAT|GLOB|HASH|IO|LVALUE|REF|Regexp|SCALAR|VSTRING)$/i);
    $class = ref($class) if(ref($class) !~ /^$/);
    if(!defined($NAMESPACE)) {
        my $self = {
            NAMESPACE => $class,
            PACKAGE => __PACKAGE__,
        };
        $NAMESPACE = bless($self, $class);
        $NAMESPACE->initialise(%parameters);
    } else {
        $NAMESPACE->reinitialise(%parameters);
    }
    return $NAMESPACE;
}


=head2 obsolete

    my $someObject = Some::Example->new();
    $someObject->{ANOTHER_OBJECT} = Another::Example->new();
    my $objectManager = Anansi::ObjectManager->new();
    $objectManager->current(
        USER => $someObject,
        USES => $someObject->{ANOTHER_OBJECT},
    );
    my $objectManager = Anansi::ObjectManager->new();
    $objectManager->obsolete(
        USER => $someObject,
        USES => $someObject->{ANOTHER_OBJECT},
    );
    delete $someObject->{ANOTHER_OBJECT};

    my $someObject = Some::Example->new();
    $someObject->{ANOTHER_OBJECT} = Another::Example->new();
    $someObject->{YET_ANOTHER_OBJECT} = Yet::Another::Example->new();
    my $objectManager = Anansi::ObjectManager->new();
    $objectManager->current(
        USER => $someObject,
        USES => [$someObject->{ANOTHER_OBJECT}, $someObject->{YET_ANOTHER_OBJECT}],
    );
    my $objectManager = Anansi::ObjectManager->new();
    $objectManager->obsolete(
        USER => $someObject,
        USES => [$someObject->{ANOTHER_OBJECT}, $someObject->{YET_ANOTHER_OBJECT}],
    );
    delete $someObject->{ANOTHER_OBJECT};
    delete $someObject->{YET_ANOTHER_OBJECT};

=over 4

=item self I<(Blessed Hash, Required)>

An object of this namespace.

=item parameters I<(Hash, Required)>

Named parameters.

=over 4

=item USER I<(Blessed Hash, Required)>

The object that has previously needed the I<USES> objects to only be garbage
collected at some time after it has finished using them and no longer does.
This object may be garbage collected at any time after the Perl interpreter has
determined that it is no longer in use.

=item USES I<(Blessed Hash B<or> Array, Required)>