Object::Realize::Later 0.16

Object::Realize::Later is a Perl module with delayed creation of objects.

SYNOPSIS

package MyLazyObject;

use Object::Realize::Later
becomes => MyRealObject,
realize => load;

The Object::Realize::Later class helps with implementing transparent on demand realization of object data. This is related to the tricks on autoloading of data, the lesser known cousin of autoloading of functionality.

On demand realization is all about performance gain. Why should you spent costly time on realizing an object, when the data on the object is never (or not yet) used? In interactive programs, postponed realization may boost start-up: the realization of objects is triggered by the use, so spread over time.

METHODS

Construction

use(Object::Realize::Later OPTIONS)

When you invoke (use) the Object::Realize::Later package, it will add a set of methods to your package (see section "Added to YOUR class").

Option --Default
becomes < required >
believe_caller < false >
realize < required >
source_module < becomes >
warn_realization < false >
warn_realize_again < false >
. becomes CLASS

Which type will this object become after realization.

. believe_caller BOOLEAN

When a method is called on the un-realized object, the AUTOLOAD checks whether this resolves the need. If not, the realization is not done. However, when realization may result in an object that extends the functionality of the class specified with becomes, this check must be disabled. In that case, specify true for this option.

. realize METHOD|CODE

How will transform. If you specify a CODE reference, then this will be called with the lazy-object as first argument, and the requested method as second.
After realization, you may still have your hands on the lazy object on various places. Be sure that your realization method is coping with that, for instance by using Memoize. See examples below.

. source_module CLASS

if the class (a package) is included in a file (module) with a different name, then use this argument to specify the file name. The name is expected to be the same as in the require call which would load it.

. warn_realization BOOLEAN

Print a warning message when the realization starts. This is for debugging purposes.

. warn_realize_again BOOLEAN

When an object is realized, the original object -which functioned as a stub- is reconstructed to work as proxy to the realized object. This option will issue a warning when that proxy is used, which means that somewhere in your program there is a variable still holding a reference to the stub. This latter is not problematic at all, although it slows-down each method call.

Added to YOUR class

$obj->AUTOLOAD

When a method is called which is not available for the lazy object, the AUTOLOAD is called.

$obj->can(METHOD)

Object::Realize::Later->can(METHOD)

Is the specified METHOD available for the lazy or the realized version of this object? It will return the reference to the code.

Example:

MyLazyObject->can(lazyWork) # true
MyLazyObject->can(realWork) # true

my $lazy = MyLazyObject->new;
$lazy->can(lazyWork); # true
$lazy->can(realWork); # true
$obj->forceRealize

You can force the load by calling this method on your object. It returns the realized object.

Object::Realize::Later->isa(CLASS)

Is this object a (sub-)class of the specified CLASS or can it become a (sub-)class of CLASS.

Example:

MyLazyObject->isa(MyRealObject) # true
MyLazyObject->isa(SuperClassOfLazy); # true
MyLazyObject->isa(SuperClassOfReal); # true

my $lazy = MyLazyObject->new;
$lazy->isa(MyRealObject); # true
$lazy->isa(SuperClassOfLazy); # true
$lazy->isa(SuperClassOfReal); # true
$obj->willRealize

Returns which class will be the realized to follow-up this class.

Object::Realize::Later internals

The next methods are not exported to the class where the `use took place. These methods implement the actual realization.

Object::Realize::Later->import(OPTIONS)

The OPTIONS used for import are the values after the class name with use. So this routine implements the actual option parsing. It generates code dynamically, which is then evaluated in the callers name-space.

Object::Realize::Later->realizationOf(OBJECT [,REALIZED])

Returns the REALIZED version of OBJECT, optionally after setting it first. When the method returns undef, the realization has not yet taken place or the realized object has already been removed again.

Object::Realize::Later->realize(OPTIONS)

This method is called when a $object-forceRealize()> takes place. It checks whether the realization has been done already (is which case the realized object is returned)