NAME

AutoLoader - load functions only on demand


SYNOPSIS

    package FOOBAR;
    use Exporter;
    use AutoLoader;
    @ISA = qw(Exporter AutoLoader);


DESCRIPTION

This module tells its users that functions in the FOOBAR package are to be autoloaded from auto/$AUTOLOAD.al. See Autoloading and the AutoSplit manpage.


__END__

The module using the autoloader should have the special marker __END__ prior to the actual subroutine declarations. All code that is before the marker will be loaded and compiled when the module is used. At the marker, perl will cease reading and parsing. See also the AutoSplit module, a utility that automatically splits a module into a collection of files for autoloading.

When a subroutine not yet in memory is called, the AUTOLOAD function attempts to locate it in a directory relative to the location of the module file itself. As an example, assume POSIX.pm is located in /usr/local/lib/perl5/POSIX.pm. The autoloader will look for perl subroutines for this package in /usr/local/lib/perl5/auto/POSIX/*.al. The .al file is named using the subroutine name, sans package.


Loading Stubs

The AutoLoader module provide a special import method that will load the stubs (from autosplit.ix file) of the calling module. These stubs are needed to make inheritance work correctly for class modules.

Modules that inherit from AutoLoader should always ensure that they override the AutoLoader->import() method. If the module inherit from Exporter like shown in the synopis section this is already taken care of. For class methods an empty import would do nicely:

  package MyClass;
  use AutoLoader;        # load stubs
  @ISA=qw(AutoLoader);
  sub import {}          # hide AutoLoader::import

You can also set up autoloading by importing the AUTOLOAD function instead of inheriting from AutoLoader:

  package MyClass;
  use AutoLoader;        # load stubs
  *AUTOLOAD = \&AutoLoader::AUTOLOAD;


Package Lexicals

Package lexicals declared with my in the main block of a package using the AutoLoader will not be visible to auto-loaded functions, due to the fact that the given scope ends at the __END__ marker. A module using such variables as package globals will not work properly under the AutoLoader.

The vars pragma (see vars) may be used in such situations as an alternative to explicitly qualifying all globals with the package namespace. Variables pre-declared with this pragma will be visible to any autoloaded routines (but will not be invisible outside the package, unfortunately).


AutoLoader vs. SelfLoader

The AutoLoader is a counterpart to the SelfLoader module. Both delay the loading of subroutines, but the SelfLoader accomplishes the goal via the __DATA__ marker rather than __END__. While this avoids the use of a hierarchy of disk files and the associated open/close for each routine loaded, the SelfLoader suffers a disadvantage in the one-time parsing of the lines after __DATA__, after which routines are cached. SelfLoader can also handle multiple packages in a file.

AutoLoader only reads code as it is requested, and in many cases should be faster, but requires a machanism like AutoSplit be used to create the individual files. The ExtUtils::MakeMaker will invoke AutoSplit automatically if the AutoLoader is used in a module source file.


CAVEAT

On systems with restrictions on file name length, the file corresponding to a subroutine may have a shorter name that the routine itself. This can lead to conflicting file names. The AutoSplit package warns of these potential conflicts when used to split a module.