1AutoLoader(3pm) Perl Programmers Reference Guide AutoLoader(3pm)
2
6 AutoLoader - load subroutines only on demand
7
9 package Foo;
10 use AutoLoader 'AUTOLOAD'; # import the default AUTOLOAD subroutine
11 package Bar;
13 use AutoLoader; # don't import AUTOLOAD, define our own
14 sub AUTOLOAD {
15 ...
16 $AutoLoader::AUTOLOAD = "...";
17 goto &AutoLoader::AUTOLOAD;
18 }
19
21 The AutoLoader module works with the AutoSplit module and the "__END__"
22 token to defer the loading of some subroutines until they are used
23 rather than loading them all at once.
24 To use AutoLoader, the author of a module has to place the definitions
26 of subroutines to be autoloaded after an "__END__" token. (See perl‐
27 data.) The AutoSplit module can then be run manually to extract the
28 definitions into individual files auto/funcname.al.
29 AutoLoader implements an AUTOLOAD subroutine. When an undefined sub‐
31 routine in is called in a client module of AutoLoader, AutoLoader's
32 AUTOLOAD subroutine attempts to locate the subroutine in a file with a
33 name related to the location of the file from which the client module
34 was read. As an example, if POSIX.pm is located in
35 /usr/local/lib/perl5/POSIX.pm, AutoLoader will look for perl subrou‐
36 tines POSIX in /usr/local/lib/perl5/auto/POSIX/*.al, where the ".al"
37 file has the same name as the subroutine, sans package. If such a file
38 exists, AUTOLOAD will read and evaluate it, thus (presumably) defining
39 the needed subroutine. AUTOLOAD will then "goto" the newly defined
40 subroutine.
41 Once this process completes for a given function, it is defined, so
43 future calls to the subroutine will bypass the AUTOLOAD mechanism.
44 Subroutine Stubs
46 In order for object method lookup and/or prototype checking to operate
48 correctly even when methods have not yet been defined it is necessary
49 to "forward declare" each subroutine (as in "sub NAME;"). See "SYNOP‐
50 SIS" in perlsub. Such forward declaration creates "subroutine stubs",
51 which are place holders with no code.
52 The AutoSplit and AutoLoader modules automate the creation of forward
54 declarations. The AutoSplit module creates an 'index' file containing
55 forward declarations of all the AutoSplit subroutines. When the
56 AutoLoader module is 'use'd it loads these declarations into its call‐
57 ers package.
58 Because of this mechanism it is important that AutoLoader is always
60 "use"d and not "require"d.
61 Using AutoLoader's AUTOLOAD Subroutine
63 In order to use AutoLoader's AUTOLOAD subroutine you must explicitly
65 import it:
66 use AutoLoader 'AUTOLOAD';
68 Overriding AutoLoader's AUTOLOAD Subroutine
70 Some modules, mainly extensions, provide their own AUTOLOAD subrou‐
72 tines. They typically need to check for some special cases (such as
73 constants) and then fallback to AutoLoader's AUTOLOAD for the rest.
74 Such modules should not import AutoLoader's AUTOLOAD subroutine.
76 Instead, they should define their own AUTOLOAD subroutines along these
77 lines:
78 use AutoLoader;
80 use Carp;
81 sub AUTOLOAD {
83 my $sub = $AUTOLOAD;
84 (my $constname = $sub) =~ s/.*:://;
85 my $val = constant($constname, @_ ? $_[0] : 0);
86 if ($! != 0) {
87 if ($! =~ /Invalid/ ⎪⎪ $!{EINVAL}) {
88 $AutoLoader::AUTOLOAD = $sub;
89 goto &AutoLoader::AUTOLOAD;
90 }
91 else {
92 croak "Your vendor has not defined constant $constname";
93 }
94 }
95 *$sub = sub { $val }; # same as: eval "sub $sub { $val }";
96 goto &$sub;
97 }
98 If any module's own AUTOLOAD subroutine has no need to fallback to the
100 AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit
101 subroutines), then that module should not use AutoLoader at all.
102 Package Lexicals
104 Package lexicals declared with "my" in the main block of a package
106 using AutoLoader will not be visible to auto-loaded subroutines, due to
107 the fact that the given scope ends at the "__END__" marker. A module
108 using such variables as package globals will not work properly under
109 the AutoLoader.
110 The "vars" pragma (see "vars" in perlmod) may be used in such situa‐
112 tions as an alternative to explicitly qualifying all globals with the
113 package namespace. Variables pre-declared with this pragma will be
114 visible to any autoloaded routines (but will not be invisible outside
115 the package, unfortunately).
116 Not Using AutoLoader
118 You can stop using AutoLoader by simply
120 no AutoLoader;
122 AutoLoader vs. SelfLoader
124 The AutoLoader is similar in purpose to SelfLoader: both delay the
126 loading of subroutines.
127 SelfLoader uses the "__DATA__" marker rather than "__END__". While
129 this avoids the use of a hierarchy of disk files and the associated
130 open/close for each routine loaded, SelfLoader suffers a startup speed
131 disadvantage in the one-time parsing of the lines after "__DATA__",
132 after which routines are cached. SelfLoader can also handle multiple
133 packages in a file.
134 AutoLoader only reads code as it is requested, and in many cases should
136 be faster, but requires a mechanism like AutoSplit be used to create
137 the individual files. ExtUtils::MakeMaker will invoke AutoSplit auto‐
138 matically if AutoLoader is used in a module source file.
139
141 AutoLoaders prior to Perl 5.002 had a slightly different interface.
142 Any old modules which use AutoLoader should be changed to the new call‐
143 ing style. Typically this just means changing a require to a use,
144 adding the explicit 'AUTOLOAD' import if needed, and removing
145 AutoLoader from @ISA.
146 On systems with restrictions on file name length, the file correspond‐
148 ing to a subroutine may have a shorter name that the routine itself.
149 This can lead to conflicting file names. The AutoSplit package warns
150 of these potential conflicts when used to split a module.
151 AutoLoader may fail to find the autosplit files (or even find the wrong
153 ones) in cases where @INC contains relative paths, and the program does
154 "chdir".
155
157 SelfLoader - an autoloader that doesn't use external files.
158perl v5.8.8 2001-09-21 AutoLoader(3pm)