/ 
Class-LazyLoad-0.04
River stage zero No dependents
/ Class::LazyLoad

NAME

Class::LazyLoad -

SYNOPSIS

use Class::LazyLoad::Functions 'lazyload', 'unlazyload';

# lazyload classes dynamically
lazyload('My::Class'); 
unlazyload('My::Class');

# lazyload classes at compile time
use Class::LazyLoad 'My::Class'; 

# Same as above
use Class::LazyLoad [ 'My::Class', 'new' ]; 

# For different constructors
use Class::LazyLoad [ 'My::Class', 'build', 'create' ]; 

# or make your class into a lazyload
package My::Class;

# If you're using 'new' as the constructor
use Class::LazyLoad;

# Or, if you're using different constructor names
use Class::LazyLoad [ __PACKAGE__, 'build', 'create' ];

# ... rest of your class here

DESCRIPTION

This is a highly flexible and general purpose lazyloader class. With very minimal configuration, it will correctly intercept constructor calls and wait until first access before actually executing the constructor.

WHY ANOTHER LAZYLOADER?

We looked at all the lazyloaders out there and realized that they were more complicated and in-depth than we wanted to be. Each one we looked at required the developer of the class to figure out how to lazyload their class. Plus, there was no provision for a consumer to lazyload a class that wasn't initially designed for it.

We wanted to lazyload anything we felt like and, if desired, indicate that a given class should be lazyloadable in a very . . . well . . . Lazy fashion. Hence, this class.

METHODS

isa()

This will dispatch to your class's isa().

can()

This will inflate the object, then dispatch to your class's can(). This is because of the following snippet:

my $ref = $object->can( 'method' );
$ref->( $object, @args );

If the object is not inflated during can(), the wrong (or no!) subreference will be returned.

LazyLoaded Public Attribute Access

We correctly handle the lazyloading of public attribute access, so that the following will work (depending on the underlying implementation of your object)

SCALAR: ${$proxied_object}
ARRAY:  $proxied_object->[3]
HASH:   $proxied_object->{foo}
SUB:    $proxied_object->(foo)

This basically results in the inflation of the proxied object.

LazyLoaded Operator Overloading

We correctly lazyload overloaded operators so that their use will result in the inflation of the proxied object. The only restriction we have is that the dereference operators are not overloadable since we make use of them to allow for proxied attribute access.

ASSUMPTIONS

  • Overloaded operators

    We assume that you do not overload ${}, @{}, %{}, and &{}. We use these to test if you are accessing the object internals directly. The effect is that we will not redispatch these overloads to your object. The workaround is to do something else first, then we're not in the way anymore.

Exportable Functions

To export these functions, you have to use Class::LazyLoad::Functions instead.

lazyload

Use this if you want to mark a class for lazyloading at runtime. The first parameter is the class you want to lazyload. Any subsequent parameters are the constructor name(s). (If none are provided, 'new' is assumed.)

unlazyload

Use this if you want to unmark a class for lazyloading. Once this is called, the class will no longer benefit from lazyloading.

init_lazyloads

This is the actual function called by the INIT block to do lazyloading during compile-time. Use this if you are working in an environment that may not execute the INIT phase. (If you don't understand what that means, you probably don't have to worry about it.)

lazyload_one

This works much like lazyload but will only lazyload a single instance of a given package. It will force compilation of the package, but it will not alter the package itself.

CAVEATS

This code has not been tested extensively in persistent environments, such as mod_perl. As such, the mechanism used (INIT blocks) may not work in certain situations. We provide init_lazyloads() in case you need to intialize by hand.

BUGS

None that we are aware of. Of course, if you find a bug, let us know, and we will be sure to fix it.

CODE COVERAGE

We use Devel::Cover to test the code coverage of our tests, below is the Devel::Cover report on this module test suite.

----------------------------------- ------ ------ ------ ------ ------ ------
File                                  stmt branch   cond    sub   time  total
----------------------------------- ------ ------ ------ ------ ------ ------
blib/lib/Class/LazyLoad.pm           100.0  100.0  100.0  100.0   94.7  100.0
.../lib/Class/LazyLoad/Functions.pm  100.0    n/a    n/a  100.0    5.3  100.0
Total                                100.0  100.0  100.0  100.0  100.0  100.0
----------------------------------- ------ ------ ------ ------ ------ ------

SEE ALSO

Object::Realize::Later
Class::LazyObject

AUTHORS

Rob Kinyon, <rob.kinyon@gmail.com> Stevan Little, <stevan@iinteractive.com>

COPYRIGHT AND LICENSE

Copyright (C) 2004 Rob Kinyon and Stevan Little

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.