NAME

Anansi::ObjectManager - A module object encapsulation manager

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;

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.

METHODS

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}],
    );

self (Blessed Hash, Required)

An object of this namespace.

parameters (Hash, Required)

Named parameters.

USER (Blessed Hash, Required): The object that needs the USES objects to only be garbage collected at some time after it has finished using them. This object may be garbage collected at any time after the Perl interpreter has determined that it is no longer in use.
USES (Blessed Hash or Array, Required): Either an object or an array of objects that the USER object needs to only be garbage collected at some time after it has finished using them.

Ensures that a module object instance is tied to one or more module object instances to ensure that those object instances are terminated after the tying object instance. This allows a tying object to make full use of the tied objects up to the moment of termination.

finalise

    package Some::Example;

    use base qw(Anansi::ObjectManager);

    sub old {
        my ($self, %parameters) = @_;
        $self->finalise();
    }

    1;

self (Blessed Hash, Required): An object of this namespace.
parameters (Hash, Optional): Named parameters.

Ensures that all of the known object instances are allowed to terminate in reverse order of dependence. Indirectly called by the termination of an instance of this module.

identification

    my $someExample = Some::Example->new();
    my $objectManager = Anansi::ObjectManager->new();
    my $identification = $objectManager->identification($someExample);
    if(defined($identification));

    my $someExample = Some::Example->new();
    my $objectManager = Anansi::ObjectManager->new();
    my $identification, $index;
    try {
        $identification = $someExample->{IDENTIFICATION};
    }
    $ordinal = $objectManager->identification($identification) if(defined($identification));
    if(defined($ordinal));

self (Blessed Hash, Required): An object of this namespace.
instance (Blessed Hash or String, Optional): Either a previously registered object or an object's identifying registration number or an object's unique ordinal number as stored internally by this module.

Assigns an identifying number to a module object instance as required and either returns the identifying number or the unique ordinal number of the module object instance as stored internally by this module.

initialise

    package Some::Example;

    use base qw(Anansi::ObjectManager);

    sub initialise {
        my ($self, %parameters) = @_;
        $self->SUPER::initialise(%parameters);
    }

    1;

self (Blessed Hash, Required): An object of this namespace.
parameters (Hash, Optional): Named parameters.

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

new

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

class (Blessed Hash or String, Required): Either an object of this namespace or this module's namespace.
parameters (Hash, Optional): Named parameters.

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.

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

self (Blessed Hash, Required)

An object of this namespace.

parameters (Hash, Required)

Named parameters.

USER (Blessed Hash, Required): The object that has previously needed the 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.
USES (Blessed Hash or Array, Required): Either an object or an array of objects that the USER object has previously needed to only be garbage collected at some time after it has finished using them and now no longer does.

Ensures that module object instances that have previously been tied to an object instance can terminate prior to the termination of the tying object instance. This allows object instances that are no longer required to be cleaned-up early by the perl interpreter garbage collection.

old

    package Some::Example;

    use base qw(Anansi::ObjectManager);

    sub old {
        my ($self, %parameters) = @_;
        $self->SUPER::old(%parameters);
    }

    1;

self (Blessed Hash, Required): An object of this namespace.
parameters (Hash, Optional): Named parameters.

Performs module object instance clean-up actions.

register

    my $someObject = Some::Example->new();
    my $objectManager = Anansi::ObjectManager->new();
    $objectManager->register($someObject);

self (Blessed Hash, Required): An object of this namespace.
instance (Blessed Hash, Required): The object to register with this module.

Ties as required an object instance to this module and increments an internal counter as to how many times the object instance has been tied. This ensure that the perl garbage collection does not remove the object instance from memory until either the object instance is untied or this module has terminated.

registrations

    my $someObject = Some::Example->new();
    my $objectManager = Anansi::ObjectManager->new();
    $objectManager->register($someObject);
    if(0 < $objectManager->registrations($someObject));

self (Blessed Hash, Required): An object of this namespace.
instance (Blessed Hash, Required): The object that has previously been registered with this module.

Determines the number of times an object instance has been tied to this module. If no previous registrations exist then 0 (zero) will be returned.

reinitialise

    package Some::Example;

    use base qw(Anansi::ObjectManager);

    sub reinitialise {
        my ($self, %parameters) = @_;
        $self->SUPER::reinitialise(%parameters);
    }

    1;

self (Blessed Hash, Required): An object of this namespace.
parameters (Hash, Optional): Named parameters.

Performs additional after creation actions on subsequent instance objects of this module that are created.

unregister

    my $someObject = Some::Example->new();
    my $objectManager = Anansi::ObjectManager->new();
    $objectManager->register($someObject);
    my $objectManager = Anansi::ObjectManager->new();
    $objectManager->unregister($someObject);

self (Blessed Hash, Required): An object of this namespace.
instance (Blessed Hash, Required): The object that has previously been registered with this module.

Reduce the number of times an object instance has been tied to this module and remove the tie that inhibits the perl garbage collection from removing the object instance from memory if the object instance is no longer tied.

user

    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 $userObjects = $objectManager->user($someObject);
    if(defined($userObjects)) {
        foreach my $userObject (@{$userObjects}) {
        }
    }

self (Blessed Hash, Required): An object of this namespace.
instance (Blessed Hash, Required): Either an object that has not previously been registered with this module or one that has been previously registered.

Determine the object instances that are made use of by the supplied object instance. If the object instance has not previously been registered then it will be. If object instances are found, an array of their unique ordinal numbers as stored internally by this module will be returned otherwise an undef will be returned.

uses

    my $someObject = Some::Example->new();
    my $anotherObject = Another::Example->new();
    $someObject->{ANOTHER_OBJECT} = $anotherObject;
    my $objectManager = Anansi::ObjectManager->new();
    $objectManager->current(
        USER => $someObject,
        USES => $someObject->{ANOTHER_OBJECT},
    );
    my $usesObjects = $objectManager->uses($anotherObject);
    if(defined($usesObjects)) {
        foreach my $usesObject (@{$usesObjects}) {
        }
    }

self (Blessed Hash, Required): An object of this namespace.
instance (Blessed Hash, Required): Either an object that has not previously been registered with this module or one that has been previously registered.

Determine the object instances that make use of the supplied object instance. If the object instance has not previously been registered then it will be. If object instances are found, an array of their unique ordinal numbers as stored internally by this module will be returned otherwise an undef will be returned.

NOTES

This module is designed to make it simple, easy and quite fast to code your design in perl. If for any reason you feel that it doesn't achieve these goals then please let me know. I am here to help. All constructive criticisms are also welcomed.

As this module is not intended to be directly implemented by an end user subroutine, as a measure to improve process speed, relatively few validation and verification tests are performed. As a result, if you have any problems implementing this module from within your own module, please contact me. If this lack of testing becomes a problem in the future, I will modify this module to implement the necessary tests. Thank you for your continued support and understanding.

AUTHOR

Kevin Treleaven <kevin AT treleaven DOT net>

To install Anansi::ObjectManager, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Anansi::ObjectManager

CPAN shell

perl -MCPAN -e shell
install Anansi::ObjectManager

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)