1SelfLoader(3pm) Perl Programmers Reference Guide SelfLoader(3pm)
2
6 SelfLoader - load functions only on demand
7
9 package FOOBAR;
10 use SelfLoader;
11 ... (initializing code)
13 __DATA__
15 sub {....
16
18 This module tells its users that functions in the FOOBAR package are to
19 be autoloaded from after the "__DATA__" token. See also "Autoloading"
20 in perlsub.
21 The __DATA__ token
23 The "__DATA__" token tells the perl compiler that the perl code for
25 compilation is finished. Everything after the "__DATA__" token is
26 available for reading via the filehandle FOOBAR::DATA, where FOOBAR is
27 the name of the current package when the "__DATA__" token is reached.
28 This works just the same as "__END__" does in package 'main', but for
29 other modules data after "__END__" is not automatically retrievable,
30 whereas data after "__DATA__" is. The "__DATA__" token is not recog‐
31 nized in versions of perl prior to 5.001m.
32 Note that it is possible to have "__DATA__" tokens in the same package
34 in multiple files, and that the last "__DATA__" token in a given pack‐
35 age that is encountered by the compiler is the one accessible by the
36 filehandle. This also applies to "__END__" and main, i.e. if the 'main'
37 program has an "__END__", but a module 'require'd (_not_ 'use'd) by
38 that program has a 'package main;' declaration followed by an
39 '"__DATA__"', then the "DATA" filehandle is set to access the data
40 after the "__DATA__" in the module, _not_ the data after the "__END__"
41 token in the 'main' program, since the compiler encounters the
42 'require'd file later.
43 SelfLoader autoloading
45 The SelfLoader works by the user placing the "__DATA__" token after
47 perl code which needs to be compiled and run at 'require' time, but
48 before subroutine declarations that can be loaded in later - usually
49 because they may never be called.
50 The SelfLoader will read from the FOOBAR::DATA filehandle to load in
52 the data after "__DATA__", and load in any subroutine when it is
53 called. The costs are the one-time parsing of the data after
54 "__DATA__", and a load delay for the _first_ call of any autoloaded
55 function. The benefits (hopefully) are a speeded up compilation phase,
56 with no need to load functions which are never used.
57 The SelfLoader will stop reading from "__DATA__" if it encounters the
59 "__END__" token - just as you would expect. If the "__END__" token is
60 present, and is followed by the token DATA, then the SelfLoader leaves
61 the FOOBAR::DATA filehandle open on the line after that token.
62 The SelfLoader exports the "AUTOLOAD" subroutine to the package using
64 the SelfLoader, and this loads the called subroutine when it is first
65 called.
66 There is no advantage to putting subroutines which will _always_ be
68 called after the "__DATA__" token.
69 Autoloading and package lexicals
71 A 'my $pack_lexical' statement makes the variable $pack_lexical local
73 _only_ to the file up to the "__DATA__" token. Subroutines declared
74 elsewhere _cannot_ see these types of variables, just as if you
75 declared subroutines in the package but in another file, they cannot
76 see these variables.
77 So specifically, autoloaded functions cannot see package lexicals (this
79 applies to both the SelfLoader and the Autoloader). The "vars" pragma
80 provides an alternative to defining package-level globals that will be
81 visible to autoloaded routines. See the documentation on vars in the
82 pragma section of perlmod.
83 SelfLoader and AutoLoader
85 The SelfLoader can replace the AutoLoader - just change 'use
87 AutoLoader' to 'use SelfLoader' (though note that the SelfLoader
88 exports the AUTOLOAD function - but if you have your own AUTOLOAD and
89 are using the AutoLoader too, you probably know what you're doing), and
90 the "__END__" token to "__DATA__". You will need perl version 5.001m or
91 later to use this (version 5.001 with all patches up to patch m).
92 There is no need to inherit from the SelfLoader.
94 The SelfLoader works similarly to the AutoLoader, but picks up the subs
96 from after the "__DATA__" instead of in the 'lib/auto' directory.
97 There is a maintenance gain in not needing to run AutoSplit on the mod‐
98 ule at installation, and a runtime gain in not needing to keep opening
99 and closing files to load subs. There is a runtime loss in needing to
100 parse the code after the "__DATA__". Details of the AutoLoader and
101 another view of these distinctions can be found in that module's docu‐
102 mentation.
103 __DATA__, __END__, and the FOOBAR::DATA filehandle.
105 This section is only relevant if you want to use the "FOOBAR::DATA"
107 together with the SelfLoader.
108 Data after the "__DATA__" token in a module is read using the FOO‐
110 BAR::DATA filehandle. "__END__" can still be used to denote the end of
111 the "__DATA__" section if followed by the token DATA - this is sup‐
112 ported by the SelfLoader. The "FOOBAR::DATA" filehandle is left open if
113 an "__END__" followed by a DATA is found, with the filehandle posi‐
114 tioned at the start of the line after the "__END__" token. If no
115 "__END__" token is present, or an "__END__" token with no DATA token on
116 the same line, then the filehandle is closed.
117 The SelfLoader reads from wherever the current position of the "FOO‐
119 BAR::DATA" filehandle is, until the EOF or "__END__". This means that
120 if you want to use that filehandle (and ONLY if you want to), you
121 should either
122 1. Put all your subroutine declarations immediately after the
124 "__DATA__" token and put your own data after those declarations, using
125 the "__END__" token to mark the end of subroutine declarations. You
126 must also ensure that the SelfLoader reads first by calling 'Self‐
127 Loader->load_stubs();', or by using a function which is selfloaded;
128 or
130 2. You should read the "FOOBAR::DATA" filehandle first, leaving the
132 handle open and positioned at the first line of subroutine declara‐
133 tions.
134 You could conceivably do both.
136 Classes and inherited methods.
138 For modules which are not classes, this section is not relevant. This
140 section is only relevant if you have methods which could be inherited.
141 A subroutine stub (or forward declaration) looks like
143 sub stub;
145 i.e. it is a subroutine declaration without the body of the subroutine.
147 For modules which are not classes, there is no real need for stubs as
148 far as autoloading is concerned.
149 For modules which ARE classes, and need to handle inherited methods,
151 stubs are needed to ensure that the method inheritance mechanism works
152 properly. You can load the stubs into the module at 'require' time, by
153 adding the statement 'SelfLoader->load_stubs();' to the module to do
154 this.
155 The alternative is to put the stubs in before the "__DATA__" token
157 BEFORE releasing the module, and for this purpose the "Devel::SelfStub‐
158 ber" module is available. However this does require the extra step of
159 ensuring that the stubs are in the module. If this is done I strongly
160 recommend that this is done BEFORE releasing the module - it should NOT
161 be done at install time in general.
162
164 Subroutines in multiple packages within the same file are supported -
165 but you should note that this requires exporting the "Self‐
166 Loader::AUTOLOAD" to every package which requires it. This is done
167 automatically by the SelfLoader when it first loads the subs into the
168 cache, but you should really specify it in the initialization before
169 the "__DATA__" by putting a 'use SelfLoader' statement in each package.
170 Fully qualified subroutine names are also supported. For example,
172 __DATA__
174 sub foo::bar {23}
175 package baz;
176 sub dob {32}
177 will all be loaded correctly by the SelfLoader, and the SelfLoader will
179 ensure that the packages 'foo' and 'baz' correctly have the SelfLoader
180 "AUTOLOAD" method when the data after "__DATA__" is first parsed.
181perl v5.8.8 2001-09-21 SelfLoader(3pm)