NAME
SYNOPSIS
DESCRIPTION
USE
compile_all
REQUIREMENTS
CAVEATS
MAINTAINER
SEE ALSO
COPYRIGHT
VERSION

NAME

GT::AutoLoader - load subroutines on demand

SYNOPSIS

    package GT::Module;
    use GT::AutoLoader; # You now have an AUTOLOAD subroutine that will check for entries in %COMPILE

    package GT::OtherModule;
    use GT::AutoLoader(NAME => '_AUTOLOAD'); # Import AUTOLOAD as _AUTOLOAD, define our own AUTOLOAD
    sub AUTOLOAD {
        ...
        goto &_AUTOLOAD;
    }

then:

    $COMPILE{sub} = __LINE__ . <<'END_OF_SUB';
    sub method_name {
        ...
    }
    END_OF_SUB

DESCRIPTION

The GT::AutoLoader module works as a way to speed up your code. Currently, the only thing it does is scan for a %COMPILE hash in your package. If it finds it, it looks for the subroutine you called, and if found compiles and runs it.

If unable to find a subroutine to compile in %COMPILE, GT::AutoLoader will scan your inheritance tree (@ISA) for another AUTOLOAD subroutine to pass this off to. If there isn't any, a fatal error occurs.

To use GT::AutoLoader, in its standard behaviour, simply put: use GT::AutoLoader; in your module. When you use GT::AutoLoader, two things will happen. First, an AUTOLOAD subroutine will be imported into your namespace that will automatically compile your subroutines only when they are needed, thus speeding up compile time. Secondly, a %COMPILE hash will be defined in your package, eliminating the need for you to: use vars qw/%COMPILE/;

USE

You can pass options to GT::AutoLoader to change the behaviour of the module. Currently, logging is the only option, however more options (perhaps including a different compiling scheme) will be added at some future point.

Options are specified as import() arguments. For example:

    use GT::AutoLoader(OPTION => "value");

NAME

If you want to import the autoload subroutine as something other than 'Package::AUTOLOAD', the 'NAME' option should be used. Its value is the name to import as. For example, to import a GT::AutoLoader AUTOLOAD named _AUTOLOAD (this is useful when declaring your own AUTOLOAD behaviour, but still using GT::AutoLoader's behaviour as a fallback), you would do something like:

    use GT::AutoLoader(NAME => '_AUTOLOAD');

LOG

Takes a code reference as its value. The code reference will be called three arguments - the package name, the name of the function, and the autoload method (Currently only 'COMPILE'). Note that this will be called for ALL autoloaded subroutines, not just the ones in your package.

WARNING - you cannot put code in your log that relies on autoloaded methods - you'll end up throwing the program into an infinite loop.

For example, to get a line of debugging after each subroutine is compiled, you could use GT::AutoLoader like this:

    use GT::AutoLoader(LOG => sub {
        print "Compiled $_[1] in package $_[0]\n"
    });

NEXT

Normally, GT::AutoLoader will look for another AUTOLOAD to call in your package's @ISA inheritance tree. You can alter this behaviour and tell GT::AutoLoader what to call next using the NEXT option.

For example, if you have a sub _AUTOLOAD { } that you wanted to call if the method isn't found by GT::AutoLoader, you would use GT::AutoLoader like this:

    use GT::AutoLoader(NEXT => 'Package::Name::_AUTOLOAD');

The _AUTOLOAD function in your package will now be called if GT::AutoLoader can't load the method on its own. $AUTOLOAD will be set for you in whichever package the function you provide is in. Note that if you simply want to use an inherited AUTOLOAD, you should not use this option; GT::AutoLoader will handle that just fine on its own.

You may omit the package (Package::Name::) if the function is in your current package.

compile_all

A function exists in GT::AutoLoader to compile all %COMPILE-subroutines. By default (without arguments) compile_all() compiles every %COMPILE-subroutine in every package that has used GT::AutoLoader. You can, however, pass in a list of packages which compile_all() will check instead of compiling everything. Note that GT::AutoLoader will only compile %COMPILE-subroutines in packages that have used GT::AutoLoader, so if you specify package ``Foo'', but ``Foo'' hasn't used GT::AutoLoader, it will be ignored.

You can do something like:

    GT::AutoLoader::compile_all(__PACKAGE__) if MOD_PERL;

to have a GT::AutoLoader compile every %COMPILE-subroutine in the current package automatically under mod_perl, or you could add this code to your mod_perl startup file or test script:

    GT::AutoLoader::compile_all;

Test scripts should definately use compile_all() to ensure that all subroutines compile correctly!

REQUIREMENTS

None.

CAVEATS

Due to the nature of Perl's AUTOLOAD handling, you must take care when using GT::AutoLoader in a subclass. In short, subclassed methods MUST NOT be put into the %COMPILE hash.

The problem is that since the subroutine does not exist in the package, Perl, while decending the inheritance tree, will not see it but will probably see the parent's method (unless nothing else has called the method, but you should never count on that), and call it rather than looking for your package's AUTOLOAD.

This isn't to say that subclasses cannot use AUTOLOAD - just that subclasses cannot use autoloaded methods (%COMPILE-subroutines) if a method of the same name exists in the parent class. Autoloaded function calls are not affected.

MAINTAINER

Jason Rhinelander

COPYRIGHT

VERSION

Revision: $Id: AutoLoader.pm,v 1.13 2005/03/21 06:57:58 jagerman Exp $