NAME¶
load - control when subroutines will be loaded
SYNOPSIS¶
use load; # default, same as 'autoload'
use load 'autoload'; # export AUTOLOAD handler to this namespace
use load 'ondemand'; # load subroutines after __END__ when requested, default
use load 'now'; # load subroutines after __END__ now
use load (); # same as qw(dontscan inherit)
use load 'dontscan'; # don't scan module until it is really needed
use load 'inherit'; # do NOT export AUTOLOAD handler to this namespace
VERSION¶
This documentation describes version 0.23.
DESCRIPTION¶
The "load" pragma allows a module developer to give the application
developer more options with regards to optimize for memory or CPU usage. The
"load" pragma gives more control on the moment when subroutines are
loaded and start taking up memory. This allows the application developer to
optimize for CPU usage (by loading all of a module at compile time and thus
reducing the amount of CPU used during the execution of an application). Or
allow the application developer to optimize for memory usage, by loading
subroutines only when they are actually needed, thereby however increasing the
amount of CPU needed during execution.
The "load" pragma combines the best of both worlds from AutoLoader and
SelfLoader. And adds some more features.
In a situation where you want to use as little memory as possible, the
"load" pragma (in the context of a module) is a drop-in replacement
for AutoLoader. But for situations where you want to have a module load
everything it could ever possibly need (e.g. when starting a mod_perl server
in pre-fork mode), the "load" pragma can be used (in the context of
an application) to have all subroutines of a module loaded without having to
make any change to the source of the module in question.
So the typical use inside a module is to have:
package Your::Module;
use load;
in the source. And to place all subroutines that you want to be loadable on
demand after the (first) __END__.
If an application developer decides that all subroutines should be loaded at
compile time, (s)he can say in the application:
use load 'now';
use Your::Module;
This will cause the subroutines of Your::Module to all be loaded at compile
time.
MODES OF OPERATION¶
There are basically two places where you can call the "load" pragma:
inside a module¶
When you call the "load" pragma inside a module, you're basically
enabling that module for having an external control when certain subroutines
will be loaded. As with AutoLoader, any subroutines that should be loaded on
demand, should be located
after an __END__ line.
If no parameters are specified with the "use load", then the
"autoload" parameter is assumed. Whether the module's subroutines
are loaded at compile time or on demand, is determined by the calling
application. If the application doesn't specify anything specific, the
"ondemand" keyword will also be assumed.
inside an application¶
When you call the "load" pragma inside an application, you're
basically specifying when subroutines will be loaded by "load"
enhanced modules. As an application developer, you can basically use two
keywords: "ondemand" and "now".
If an application does not call the "load" pragma, the
"ondemand" keyword will be assumed. With "ondemand",
subroutines will only be loaded when they are actually executed. This saves
memory at the expense of extra CPU the first time the subroutine is called.
The "now" keyword indicates that all subroutines of all modules that
are enhanced with the "load" pragma, will be loaded at compile time
(thus using more memory, but
not having an extra CPU overhead the first
time the subroutine is executed).
KEYWORDS¶
The following keywords are recognized with the "use" command:
ondemand¶
The "ondemand" keyword indicates that subroutines, of modules that are
enhanced with the "load" pragma, will only be loaded when they are
actually called.
If the "ondemand" keyword is used in the context of an application,
all modules that are subsequently "use"d, will be forced to load
subroutines only when they are actually called (unless the module itself
forces a specific setting).
If the "ondemand" keyword is used in the context of a module, it
indicates that the subroutines of that module, should
always be loaded
when they are actually needed. Since this takes away the choice from the
application developer, the use of the "ondemand" keyword in module
context is not encouraged. See also the now and dontscan keywords.
now¶
The "now" keyword indicates that subroutines, of modules that are
enhanced with the "load" pragma, will be loaded at compile time.
If the "now" keyword is used in the context of an application, all
modules that are subsequently "use"d, will be forced to load all
subroutines at compile time (unless the module forces a specific setting
itself).
If the "now" keyword is used in the context of a module, it indicates
that the subroutines of that module, should
always be loaded at compile
time. Since this takes away the choice from the application developer, the use
of the "now" keyword in module context is not encouraged. See also
the ondemand keyword.
dontscan¶
The "dontscan" keyword only makes sense when used in the context of a
module. Normally, when a module that is enhanced with the "load"
pragma is compiled, the source after the __END__ is scanned for the locations
of the subroutines. This makes the compiling of modules a little slower, but
allows for a faster (initial) lookup of (yet) unloaded subroutines during
execution.
If the "dontscan" keyword is specified, this scanning of the source is
skipped at compile time. However, as soon as an attempt is made to ececute a
subroutine from this module, then first the scanning of the source is
performed, before the subroutine in question is loaded.
So, you should use the "dontscan" keyword if you are reasonably sure
that you will only need subroutines from the module in special cases. In all
other cases it will make more sense to have the source scanned at compile
time.
The "dontscan" keyword will be ignored if an application developer
forces subroutines to be loaded at compile time with the now keyword.
autoload¶
The "autoload" keyword only makes sense when used in the context of a
module. It indicates that a generic AUTOLOAD subroutine will be exported to
the module's namespace. It is selected by default if you use the
"load" pragma without parameters in the source of a module. See also
the inherit keyword to
not export the generic AUTOLOAD subroutine.
inherit¶
The "inherit" keyword only makes sense when used in the context of a
module. It indicates that
no AUTOLOAD subroutine will be exported to
the module's namespace. This can e.g. be used when you need to have your own
AUTOLOAD routine. That AUTOLOAD routine should then contain:
$load::AUTOLOAD = $sub;
goto &load::AUTOLOAD;
to access the "load" pragma functionality. Another case to use the
"inherit" keyword would be in a sub-class of a module which also is
"load" enhanced. In that case, the inheritance will cause the
AUTOLOAD subroutine of the base class to be used, thereby accessing the
"load" pragma automagically (and hence the naming of the keyword of
course). See also the autoload keyword to have the module use the generic
AUTOLOAD subroutine.
AutoLoader¶
The "AutoLoader" keyword enables AutoLoader emulation mode. It
basically takes over the functionality of the AutoLoader module (which is part
of Perl's core, and which is used by many of Perl's core modules).
Use of AutoLoader emulation mode usually only makes sense in a mod_perl prefork
environment (in combination with the "now" keyword), or a threaded
Perl environment.
It basically adds the flexibility of subroutine loading options of the
"load" pragma to the existing codebase of Perl's core and CPAN
modules. It is typically invoked from the command line:
perl -Mload=AutoLoader
or in a mod_perl configuration:
<Perl>
use load qw(AutoLoader now); # as early as possible
# rest of modules to be loaded
</Perl>
The AutoLoader emulation mode has the further advantage for modules being
developed with AutoLoader, as it is possible to run the module before having
to have installed the module (which is normally a requirement with using
AutoLoader).
Please note that AutoLoader emulation will only work properly for any modules
loaded
after the "load" module is loaded. It is therefore
important to activate the AutoLoader as soon as possible, before
any
other modules have been loaded. Of particular interest in this respect are the
threads and the ifdef modules.
REQUIRED MODULES¶
(none)
DIFFERENCES WITH SIMILAR MODULES¶
There are a number of (core) modules that more or less do the same thing as the
"load" pragma.
AutoSplit / AutoLoader¶
The "load" pragma is very similar to the AutoSplit / AutoLoader
combination. The main difference is that the splitting takes place when the
"load" import is called in a module and that there are no external
files created. Instead, just the offsets and lengths are recorded in a hash
(when "ondemand" is active) or all the source after __END__ is
eval'led (when "now" is active).
From a module developer point of view, the advantage is that you do not need to
install a module before you can test it. From an application developer point
of view, you have the flexibility of having everything loaded now or later (on
demand).
From a memory usage point of view, the "load" offset/length hash takes
up more memory than the equivalent AutoLoader setup. On the other hand,
accessing the source of a subroutine may generally be faster because the file
is more likely to reside in the operating system's buffers already.
As an extra feature, the "load" pragma allows an application to force
all subroutines to be loaded at compile time, which is not possible with
AutoLoader.
The "AutoLoader emulation" mode causes AutoLoader to be replaced by
"load", increasing further flexibility in loading options (which can
be particularly important in the "mod_perl prefork" situation) and
ease of use during development of modules using AutoLoader (as you don't need
to install the module before you can test it).
SelfLoader¶
The "load" pragma also has some functionality in common with the
SelfLoader module. But it gives more granularity: with SelfLoader, all
subroutines that are not loaded directly, will be loaded if
any not yet
loaded subroutine is requested. It also adds complexities if your module needs
to use the <DATA> handle. So the "load" pragma gives more
flexibility and fewer development complexities. And of course, an application
can force all subroutines to be loaded at compile time when needed with the
"load" pragma.
UNIVERSAL::can¶
To ensure the functioning of the ->can class method and &UNIVERSAL::can,
the "load" pragma hijacks the standard UNIVERSAL::can routine so
that it can check whether the subroutine/method that you want to check for,
actually exists and have a code reference to it returned. This has a side
effect that you the subroutine checked for, is loaded. You can use this side
effect to load subroutines without calling them.
Your::Module->can( 'loadthisnow' );
will load the subroutine "loadthisnow" of the Your::Module module
without actually calling it.
CAVEATS¶
Currently you may not have multiple packages in the same file, nor can you have
fully qualified subroutine names.
The parser that looks for package names and subroutines, is not very smart. This
is intentionally so, as making it smarter will make it a lot slower, but
probably still not smart enough. Therefore, the "package" and
"sub"'s
must be at the start of a line. And the name of the
"sub"
must be on the same line as the "sub".
EXAMPLES¶
Some code examples. Please note that these are just a part of an actual
situation.
base class¶
package Your::Module;
use load;
Exports the generic AUTOLOAD subroutine and adheres to whatever the application
developer specifies as mode of operation.
sub class¶
package Your::Module::Adapted;
@ISA = qw(Your::Module);
use load ();
Does
not export the generic AUTOLOAD subroutine, but inherits it from its
base class. Also implicitely specifies the "dontscan" keyword,
causing the source of the module to be scanned only when the first not yet
loaded subroutine is about to be executed. If you only want to have the
"inherit" keyword functionality, then you must specify that
explicitly:
package Your::Module::Adapted;
@ISA = qw(Your::Module);
use load 'inherit';
custom AUTOLOAD¶
package Your::Module;
use load 'inherit';
sub AUTOLOAD {
if (some condition) {
$load::AUTOLOAD = $Your::Module::AUTOLOAD;
goto &load::AUTOLOAD;
}
# do your own stuff
}
If you want to use your own AUTOLOAD subroutine, but still want to use the
functionality offered by the "load" pragma, you can use the above
construct.
mod_perl prefork¶
use load qw(AutoLoader now);
use Your::Module;
In pre-fork mod_perl applications (the default mod_perl applications before
mod_perl 2.0), it is advantageous to load all possible subroutines when the
Apache process is started. This is because the operating system will share
memory using a process called "Copy On Write". So even though it
will take more memory initially, that memory loss is easily evened out by the
gains of having everything shared. Loading a not yet loaded subroutine in that
situation, will cause otherwise shared memory to become unshared. Thereby
increasing the overall memory usage, because the amount that becomes unshared
is typically a lot more than the extra memory used by the subroutine (which is
caused by fragmentation of allocated memory).
The
AutoLoader emulation mode causes all modules that use
"AutoLoader" to be handled by "load". In combination with
the "now" mode, this means that many system modules will also be
loaded completely at server startup (causing a grow in initial use of memory,
but sharing more memory means that overall memory usage is significantly
reduced.
threaded applications and mod_perl worker¶
use Your::Module;
Threaded Perl applications, of which mod_perl applications using the
"worker" module are a special case, function best when subroutines
are only loaded when they are actually needed. This is caused by the nature of
the threading model of Perl, in which all data-structures are
copied to
each thread (essentially forcing them to become unshared as far as the
operating system is concerned).
Benchmarks have shown that the overhead of the extra CPU is easily offset by the
reduction of the amount of data that needs to be copied (and processed) when a
thread is created.
A little additional memory reduction can be achieved with the AutoLoader
emulation mode: this will prevent the AutoLoader module to be loaded (but have
its functionality handled by the "load" pragma).
SOURCE FILTERS¶
If your module wants to use "load" to load subroutines on demand
and that module needs a source filter (which is usually activated with
a "use" statement), then those modules need to be used when the
source of the subroutine is compiled. The class method "register" is
intended to be used from such a module, typicallly like this:
sub import {
my $package = caller();
load->register( $package,__PACKAGE__ ) # register caller's package
if defined( $load::VERSION ) # if load.pm loaded
and $load::VERSION > 0.11; # and recent enough
}
The first parameter is the name of the package
in which subroutines need
extra modules "use"d. The second parameter is the name of the module
that needs to be "use"d.
TODO¶
The coordinates of a subroutine in a module (start,number of bytes) are stored
in a hash in the load namespace. Ideally, this information should be stored in
the stash of the module to which they apply. Then the internals that check for
the existence of a subroutine, would see that the subroutine doesn't exist
(yet), but that there is an offset and length (and implicitely, a file from
%INC) from which the source could be read and evalled.
Loading all of the subroutines should maybe be handled inside the Perl parser,
having it skip __END__ when the global "now" flag is set.
Possibly we should use the <DATA> handle from a module if there is one, or
dup it and use that, rather than opening the file again.
Add SelfLoader emulation mode.
MODULE RATING¶
If you want to find out how this module is appreciated by other people, please
check out this module's rating at <
http://cpanratings.perl.org/l/load>
(if there are any ratings for this module). If you like this module, or
otherwise would like to have your opinion known, you can add your rating of
this module at <
http://cpanratings.perl.org/rate/?distribution=load>.
ACKNOWLEDGEMENTS¶
Frank Tolstrup for helping ironing out all of the Windows related issues.
AUTHOR¶
Elizabeth Mattijsen, <liz@dijkmat.nl>.
Please report bugs to <perlbugs@dijkmat.nl>.
COPYRIGHT¶
Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007, 2010, 2012 Elizabeth Mattijsen
<liz@dijkmat.nl>. All rights reserved. This program is free software;
you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO¶
AutoLoader, SelfLoader, ifdef, threads.