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
24 compilation is finished. Everything after the "__DATA__" token is
25 available for reading via the filehandle FOOBAR::DATA, where FOOBAR is
26 the name of the current package when the "__DATA__" token is reached.
27 This works just the same as "__END__" does in package 'main', but for
28 other modules data after "__END__" is not automatically retrievable,
29 whereas data after "__DATA__" is. The "__DATA__" token is not
30 recognized in versions of perl prior to 5.001m.
31 Note that it is possible to have "__DATA__" tokens in the same package
33 in multiple files, and that the last "__DATA__" token in a given
34 package that is encountered by the compiler is the one accessible by
35 the filehandle. This also applies to "__END__" and main, i.e. if the
36 'main' program has an "__END__", but a module 'require'd (_not_ 'use'd)
37 by that program has a 'package main;' declaration followed by an
38 '"__DATA__"', then the "DATA" filehandle is set to access the data
39 after the "__DATA__" in the module, _not_ the data after the "__END__"
40 token in the 'main' program, since the compiler encounters the
41 'require'd file later.
42 SelfLoader autoloading
44 The SelfLoader works by the user placing the "__DATA__" token after
45 perl code which needs to be compiled and run at 'require' time, but
46 before subroutine declarations that can be loaded in later - usually
47 because they may never be called.
48 The SelfLoader will read from the FOOBAR::DATA filehandle to load in
50 the data after "__DATA__", and load in any subroutine when it is
51 called. The costs are the one-time parsing of the data after
52 "__DATA__", and a load delay for the _first_ call of any autoloaded
53 function. The benefits (hopefully) are a speeded up compilation phase,
54 with no need to load functions which are never used.
55 The SelfLoader will stop reading from "__DATA__" if it encounters the
57 "__END__" token - just as you would expect. If the "__END__" token is
58 present, and is followed by the token DATA, then the SelfLoader leaves
59 the FOOBAR::DATA filehandle open on the line after that token.
60 The SelfLoader exports the "AUTOLOAD" subroutine to the package using
62 the SelfLoader, and this loads the called subroutine when it is first
63 called.
64 There is no advantage to putting subroutines which will _always_ be
66 called after the "__DATA__" token.
67 Autoloading and package lexicals
69 A 'my $pack_lexical' statement makes the variable $pack_lexical local
70 _only_ to the file up to the "__DATA__" token. Subroutines declared
71 elsewhere _cannot_ see these types of variables, just as if you
72 declared subroutines in the package but in another file, they cannot
73 see these variables.
74 So specifically, autoloaded functions cannot see package lexicals (this
76 applies to both the SelfLoader and the Autoloader). The "vars" pragma
77 provides an alternative to defining package-level globals that will be
78 visible to autoloaded routines. See the documentation on vars in the
79 pragma section of perlmod.
80 SelfLoader and AutoLoader
82 The SelfLoader can replace the AutoLoader - just change 'use
83 AutoLoader' to 'use SelfLoader' (though note that the SelfLoader
84 exports the AUTOLOAD function - but if you have your own AUTOLOAD and
85 are using the AutoLoader too, you probably know what you're doing), and
86 the "__END__" token to "__DATA__". You will need perl version 5.001m or
87 later to use this (version 5.001 with all patches up to patch m).
88 There is no need to inherit from the SelfLoader.
90 The SelfLoader works similarly to the AutoLoader, but picks up the subs
92 from after the "__DATA__" instead of in the 'lib/auto' directory.
93 There is a maintenance gain in not needing to run AutoSplit on the
94 module at installation, and a runtime gain in not needing to keep
95 opening and closing files to load subs. There is a runtime loss in
96 needing to parse the code after the "__DATA__". Details of the
97 AutoLoader and another view of these distinctions can be found in that
98 module's documentation.
99 __DATA__, __END__, and the FOOBAR::DATA filehandle.
101 This section is only relevant if you want to use the "FOOBAR::DATA"
102 together with the SelfLoader.
103 Data after the "__DATA__" token in a module is read using the
105 FOOBAR::DATA filehandle. "__END__" can still be used to denote the end
106 of the "__DATA__" section if followed by the token DATA - this is
107 supported by the SelfLoader. The "FOOBAR::DATA" filehandle is left open
108 if an "__END__" followed by a DATA is found, with the filehandle
109 positioned at the start of the line after the "__END__" token. If no
110 "__END__" token is present, or an "__END__" token with no DATA token on
111 the same line, then the filehandle is closed.
112 The SelfLoader reads from wherever the current position of the
114 "FOOBAR::DATA" filehandle is, until the EOF or "__END__". This means
115 that if you want to use that filehandle (and ONLY if you want to), you
116 should either
117 1. Put all your subroutine declarations immediately after the
119 "__DATA__" token and put your own data after those declarations, using
120 the "__END__" token to mark the end of subroutine declarations. You
121 must also ensure that the SelfLoader reads first by calling
122 'SelfLoader->load_stubs();', or by using a function which is
123 selfloaded;
124 or
126 2. You should read the "FOOBAR::DATA" filehandle first, leaving the
128 handle open and positioned at the first line of subroutine
129 declarations.
130 You could conceivably do both.
132 Classes and inherited methods.
134 For modules which are not classes, this section is not relevant. This
135 section is only relevant if you have methods which could be inherited.
136 A subroutine stub (or forward declaration) looks like
138 sub stub;
140 i.e. it is a subroutine declaration without the body of the subroutine.
142 For modules which are not classes, there is no real need for stubs as
143 far as autoloading is concerned.
144 For modules which ARE classes, and need to handle inherited methods,
146 stubs are needed to ensure that the method inheritance mechanism works
147 properly. You can load the stubs into the module at 'require' time, by
148 adding the statement 'SelfLoader->load_stubs();' to the module to do
149 this.
150 The alternative is to put the stubs in before the "__DATA__" token
152 BEFORE releasing the module, and for this purpose the
153 "Devel::SelfStubber" module is available. However this does require
154 the extra step of ensuring that the stubs are in the module. If this is
155 done I strongly recommend that this is done BEFORE releasing the module
156 - it should NOT be done at install time in general.
157
159 Subroutines in multiple packages within the same file are supported -
160 but you should note that this requires exporting the
161 "SelfLoader::AUTOLOAD" to every package which requires it. This is done
162 automatically by the SelfLoader when it first loads the subs into the
163 cache, but you should really specify it in the initialization before
164 the "__DATA__" by putting a 'use SelfLoader' statement in each package.
165 Fully qualified subroutine names are also supported. For example,
167 __DATA__
169 sub foo::bar {23}
170 package baz;
171 sub dob {32}
172 will all be loaded correctly by the SelfLoader, and the SelfLoader will
174 ensure that the packages 'foo' and 'baz' correctly have the SelfLoader
175 "AUTOLOAD" method when the data after "__DATA__" is first parsed.
176
178 "SelfLoader" is maintained by the perl5-porters. Please direct any
179 questions to the canonical mailing list. Anything that is applicable to
180 the CPAN release can be sent to its maintainer, though.
181 Author and Maintainer: The Perl5-Porters <perl5-porters@perl.org>
183 Maintainer of the CPAN release: Steffen Mueller <smueller@cpan.org>
185
187 This package has been part of the perl core since the first release of
188 perl5. It has been released separately to CPAN so older installations
189 can benefit from bug fixes.
190 This package has the same copyright and license as the perl core:
192 Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
194 2002, 2003, 2004, 2005, 2006 by Larry Wall and others
195 All rights reserved.
197 This program is free software; you can redistribute it and/or modify it
199 under the terms of either:
200 a) the GNU General Public License as published by the Free Software
202 Foundation; either version 1, or (at your option) any later
203 version, or
204 b) the "Artistic License" which comes with this Kit.
206 This program is distributed in the hope that it will be useful, but
208 WITHOUT ANY WARRANTY; without even the implied warranty of
209 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the
210 GNU General Public License or the Artistic License for more details.
211 You should have received a copy of the Artistic License with this Kit,
213 in the file named "Artistic". If not, I'll be glad to provide one.
214 You should also have received a copy of the GNU General Public License
216 along with this program in the file named "Copying". If not, write to
217 the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
218 Boston, MA 02110-1301, USA or visit their web page on the internet at
219 <http://www.gnu.org/copyleft/gpl.html>.
220 For those of you that choose to use the GNU General Public License, my
222 interpretation of the GNU General Public License is that no Perl script
223 falls under the terms of the GPL unless you explicitly put said script
224 under the terms of the GPL yourself. Furthermore, any object code
225 linked with perl does not automatically fall under the terms of the
226 GPL, provided such object code only adds definitions of subroutines and
227 variables, and does not otherwise impair the resulting interpreter from
228 executing any standard Perl script. I consider linking in C
229 subroutines in this manner to be the moral equivalent of defining
230 subroutines in the Perl language itself. You may sell such an object
231 file as proprietary provided that you provide or offer to provide the
232 Perl source, as specified by the GNU General Public License. (This is
233 merely an alternate way of specifying input to the program.) You may
234 also sell a binary produced by the dumping of a running Perl script
235 that belongs to you, provided that you provide or offer to provide the
236 Perl source as specified by the GPL. (The fact that a Perl interpreter
237 and your code are in the same binary file is, in this case, a form of
238 mere aggregation.) This is my interpretation of the GPL. If you still
239 have concerns or difficulties understanding my intent, feel free to
240 contact me. Of course, the Artistic License spells all this out for
241 your protection, so you may prefer to use that.
242perl v5.36.0 2022-08-30 SelfLoader(3pm)