1docs::api::Apache2::RelUosaedr(3C)ontributed Perl Documednotcast:i:oanpi::Apache2::Reload(3)
2
6 Apache2::Reload - Reload Perl Modules when Changed on Disk
7
9 # Monitor and reload all modules in %INC:
10 # httpd.conf:
11 PerlModule Apache2::Reload
12 PerlInitHandler Apache2::Reload
13 # when working with protocols and connection filters
15 # PerlPreConnectionHandler Apache2::Reload
16 # Reload groups of modules:
18 # httpd.conf:
19 PerlModule Apache2::Reload
20 PerlInitHandler Apache2::Reload
21 PerlSetVar ReloadAll Off
22 PerlSetVar ReloadModules "ModPerl::* Apache2::*"
23 #PerlSetVar ReloadDebug On
24 # Reload a single module from within itself:
26 package My::Apache2::Module;
27 use Apache2::Reload;
28 sub handler { ... }
29 1;
30
32 "Apache2::Reload" reloads modules that change on the disk.
33 When Perl pulls a file via "require", it stores the filename in the
35 global hash %INC. The next time Perl tries to "require" the same file,
36 it sees the file in %INC and does not reload from disk. This module's
37 handler can be configured to iterate over the modules in %INC and
38 reload those that have changed on disk or only specific modules that
39 have registered themselves with "Apache2::Reload". It can also do the
40 check for modified modules, when a special touch-file has been modi‐
41 fied.
42 Note that "Apache2::Reload" operates on the current context of @INC.
44 Which means, when called as a "Perl*Handler" it will not see @INC paths
45 added or removed by "ModPerl::Registry" scripts, as the value of @INC
46 is saved on server startup and restored to that value after each
47 request. In other words, if you want "Apache2::Reload" to work with
48 modules that live in custom @INC paths, you should modify @INC when the
49 server is started. Besides, 'use lib' in the startup script, you can
50 also set the "PERL5LIB" variable in the httpd's environment to include
51 any non-standard 'lib' directories that you choose. For example, to
52 accomplish that you can include a line:
53 PERL5LIB=/home/httpd/perl/extra; export PERL5LIB
55 in the script that starts Apache. Alternatively, you can set this envi‐
57 ronment variable in httpd.conf:
58 PerlSetEnv PERL5LIB /home/httpd/perl/extra
60 Monitor All Modules in %INC
62 To monitor and reload all modules in %INC at the beginning of request's
64 processing, simply add the following configuration to your httpd.conf:
65 PerlModule Apache2::Reload
67 PerlInitHandler Apache2::Reload
68 When working with connection filters and protocol modules
70 "Apache2::Reload" should be invoked in the pre_connection stage:
71 PerlPreConnectionHandler Apache2::Reload
73 See also the discussion on "PerlPreConnectionHandler".
75 Register Modules Implicitly
77 To only reload modules that have registered with "Apache2::Reload", add
79 the following to the httpd.conf:
80 PerlModule Apache2::Reload
82 PerlInitHandler Apache2::Reload
83 PerlSetVar ReloadAll Off
84 # ReloadAll defaults to On
85 Then any modules with the line:
87 use Apache2::Reload;
89 Will be reloaded when they change.
91 Register Modules Explicitly
93 You can also register modules explicitly in your httpd.conf file that
95 you want to be reloaded on change:
96 PerlModule Apache2::Reload
98 PerlInitHandler Apache2::Reload
99 PerlSetVar ReloadAll Off
100 PerlSetVar ReloadModules "My::Foo My::Bar Foo::Bar::Test"
101 Note that these are split on whitespace, but the module list must be in
103 quotes, otherwise Apache tries to parse the parameter list.
104 The "*" wild character can be used to register groups of files under
106 the same namespace. For example the setting:
107 PerlSetVar ReloadModules "ModPerl::* Apache2::*"
109 will monitor all modules under the namespaces "ModPerl::" and
111 "Apache2::".
112 Monitor Only Certain Sub Directories
114 To reload modules only in certain directories (and their subdirecto‐
116 ries) add the following to the httpd.conf:
117 PerlModule Apache2::Reload
119 PerlInitHandler Apache2::Reload
120 PerlSetVar ReloadDirectories "/tmp/project1 /tmp/project2"
121 You can further narrow the list of modules to be reloaded from the cho‐
123 sen directories with "ReloadModules" as in:
124 PerlModule Apache2::Reload
126 PerlInitHandler Apache2::Reload
127 PerlSetVar ReloadDirectories "/tmp/project1 /tmp/project2"
128 PerlSetVar ReloadAll Off
129 PerlSetVar ReloadModules "MyApache2::*"
130 In this configuration example only modules from the namespace "MyA‐
132 pache2::" found in the directories /tmp/project1/ and /tmp/project2/
133 (and their subdirectories) will be reloaded.
134 Special "Touch" File
136 You can also declare a file, which when gets touch(1)ed, causes the
138 reloads to be performed. For example if you set:
139 PerlSetVar ReloadTouchFile /tmp/reload_modules
141 and don't touch(1) the file /tmp/reload_modules, the reloads won't hap‐
143 pen until you go to the command line and type:
144 % touch /tmp/reload_modules
146 When you do that, the modules that have been changed, will be magically
148 reloaded on the next request. This option works with any mode described
149 before.
150 Unregistering a module
152 In some cases, it might be necessary to explicitely stop reloading a
154 module.
155 Apache2::Reload->unregister_module('Some::Module');
157 But be carefull, since unregistering a module in this way will only do
159 so for the current interpreter. This feature should be used with care.
160
162 This module is perfectly suited for a development environment. Though
163 it's possible that you would like to use it in a production environ‐
164 ment, since with "Apache2::Reload" you don't have to restart the server
165 in order to reload changed modules during software updates. Though this
166 convenience comes at a price:
167 · If the "touch" file feature is used, "Apache2::Reload" has to
169 stat(2) the touch file on each request, which adds a slight but
170 most likely insignificant overhead to response times. Otherwise
171 "Apache2::Reload" will stat(2) each registered module or even
172 worse--all modules in %INC, which will significantly slow every‐
173 thing down.
174 · Once the child process reloads the modules, the memory used by
176 these modules is not shared with the parent process anymore. There‐
177 fore the memory consumption may grow significantly.
178 Therefore doing a full server stop and restart is probably a better
180 solution.
181
183 If you aren't sure whether the modules that are supposed to be
184 reloaded, are actually getting reloaded, turn the debug mode on:
185 PerlSetVar ReloadDebug On
187
189 Problems With Reloading Modules Which Do Not Declare Their Package Name
190 If you modify modules, which don't declare their "package", and rely on
192 "Apache2::Reload" to reload them, you may encounter problems: i.e.,
193 it'll appear as if the module wasn't reloaded when in fact it was. This
194 happens because when "Apache2::Reload" "require()"s such a module all
195 the global symbols end up in the "Apache2::Reload" namespace! So the
196 module does get reloaded and you see the compile time errors if there
197 are any, but the symbols don't get imported to the right namespace.
198 Therefore the old version of the code is running.
199 Failing to Find a File to Reload
201 "Apache2::Reload" uses %INC to find the files on the filesystem. If an
203 entry for a certain filepath in %INC is relative, "Apache2::Reload"
204 will use @INC to try to resolve that relative path. Now remember that
205 mod_perl freezes the value of @INC at the server startup, and you can
206 modify it only for the duration of one request when you need to load
207 some module which is not in on of the @INC directories. So a module
208 gets loaded, and registered in %INC with a relative path. Now when
209 "Apache2::Reload" tries to find that module to check whether it has
210 been modified, it can't find since its directory is not in @INC. So
211 "Apache2::Reload" will silently skip that module.
212 You can enable the "Debug⎪/Debug" mode to see what "Apache2::Reload"
214 does behind the scenes.
215 Problems with Scripts Running with Registry Handlers that Cache the
217 Code
218 The following problem is relevant only to registry handlers that cache
220 the compiled script. For example it concerns "ModPerl::Registry" but
221 not "ModPerl::PerlRun".
222 The Problem
224 Let's say that there is a module "My::Utils":
226 #file:My/Utils.pm
228 #----------------
229 package My::Utils;
230 BEGIN { warn __PACKAGE__ , " was reloaded\n" }
231 use base qw(Exporter);
232 @EXPORT = qw(colour);
233 sub colour { "white" }
234 1;
235 And a registry script test.pl:
237 #file:test.pl
239 #------------
240 use My::Utils;
241 print "Content-type: text/plain\n\n";
242 print "the color is " . colour();
243 Assuming that the server is running in a single mode, we request the
245 script for the first time and we get the response:
246 the color is white
248 Now we change My/Utils.pm:
250 - sub colour { "white" }
252 + sub colour { "red" }
253 And issue the request again. "Apache2::Reload" does its job and we can
255 see that "My::Utils" was reloaded (look in the error_log file). However
256 the script still returns:
257 the color is white
259 The Explanation
261 Even though My/Utils.pm was reloaded, "ModPerl::Registry"'s cached code
263 won't run '"use My::Utils;"' again (since it happens only once, i.e.
264 during the compile time). Therefore the script doesn't know that the
265 subroutine reference has been changed.
266 This is easy to verify. Let's change the script to be:
268 #file:test.pl
270 #------------
271 use My::Utils;
272 print "Content-type: text/plain\n\n";
273 my $sub_int = \&colour;
274 my $sub_ext = \&My::Utils::colour;
275 print "int $sub_int\n";
276 print "ext $sub_ext\n";
277 Issue a request, you will see something similar to:
279 int CODE(0x8510af8)
281 ext CODE(0x8510af8)
282 As you can see both point to the same CODE reference (meaning that it's
284 the same symbol). After modifying My/Utils.pm again:
285 - sub colour { "red" }
287 + sub colour { "blue" }
288 and calling the script on the secondnd time, we get:
290 int CODE(0x8510af8)
292 ext CODE(0x851112c)
293 You can see that the internal CODE reference is not the same as the
295 external one.
296 The Solution
298 There are two solutions to this problem:
300 Solution 1: replace "use()" with an explicit "require()" + "import()".
302 - use My::Utils;
304 + require My::Utils; My::Utils->import();
305 now the changed functions will be reimported on every request.
307 Solution 2: remember to touch the script itself every time you change
309 the module that it requires.
310
312 If you use "Apache2::Reload" with a threaded MPM and multiple Perl
313 interpreters, the modules will be reloaded by each interpreter as they
314 are used, not every interpreters at once. Similar to mod_perl 1.0
315 where each child has its own Perl interpreter, the modules are reloaded
316 as each child is hit with a request.
317 If a module is loaded at startup, the syntax tree of each subroutine is
319 shared between interpreters (big win), but each subroutine has its own
320 padlist (where lexical my variables are stored). Once
321 "Apache2::Reload" reloads a module, this sharing goes away and each
322 Perl interpreter will have its own copy of the syntax tree for the
323 reloaded subroutines.
324
326 The short summary of this is: Don't use pseudo-hashes. They are depre‐
327 cated since Perl 5.8 and are removed in 5.9.
328 Use an array with constant indexes. Its faster in the general case, its
330 more guaranteed, and generally, it works.
331 The long summary is that some work has been done to get this module
333 working with modules that use pseudo-hashes, but it's still broken in
334 the case of a single module that contains multiple packages that all
335 use pseudo-hashes.
336 So don't do that.
338
340 mod_perl 2.0 and its core modules are copyrighted under The Apache
341 Software License, Version 2.0.
342
344 Matt Sergeant, matt@sergeant.org
345 Stas Bekman (porting to mod_perl 2.0)
347 A few concepts borrowed from "Stonehenge::Reload" by Randal Schwartz
349 and "Apache::StatINC" (mod_perl 1.x) by Doug MacEachern and Ask Bjoern
350 Hansen.
351perl v5.8.8 2006-11-19 docs::api::Apache2::Reload(3)