1Apache2::Reload(3) User Contributed Perl Documentation 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 #PerlSetVar ReloadByModuleName On
25 # Reload a single module from within itself:
27 package My::Apache2::Module;
28 use Apache2::Reload;
29 sub handler { ... }
30 1;
31
33 "Apache2::Reload" reloads modules that change on the disk.
34 When Perl pulls a file via "require", it stores the filename in the
36 global hash %INC. The next time Perl tries to "require" the same file,
37 it sees the file in %INC and does not reload from disk. This module's
38 handler can be configured to iterate over the modules in %INC and
39 reload those that have changed on disk or only specific modules that
40 have registered themselves with "Apache2::Reload". It can also do the
41 check for modified modules, when a special touch-file has been
42 modified.
43 Require-hooks, i.e., entries in %INC which are references, are ignored.
45 The hook should modify %INC itself, adding the path to the module file,
46 for it to be reloaded.
47 "Apache2::Reload" inspects and reloads the file associated with a given
49 module. Changes to @INC are not recognized, as it is the file which is
50 being re-required, not the module name.
51 In version 0.10 and earlier the module name, not the file, is re-
53 required. Meaning it operated on the the current context of @INC. If
54 you still want this behavior set this environment variable in
55 httpd.conf:
56 PerlSetVar ReloadByModuleName On
58 This means, when called as a "Perl*Handler", "Apache2::Reload" will not
60 see @INC paths added or removed by "ModPerl::Registry" scripts, as the
61 value of @INC is saved on server startup and restored to that value
62 after each request. In other words, if you want "Apache2::Reload" to
63 work with modules that live in custom @INC paths, you should modify
64 @INC when the server is started. Besides, 'use lib' in the startup
65 script, you can also set the "PERL5LIB" variable in the httpd's
66 environment to include any non-standard 'lib' directories that you
67 choose. For example, to accomplish that you can include a line:
68 PERL5LIB=/home/httpd/perl/extra; export PERL5LIB
70 in the script that starts Apache. Alternatively, you can set this
72 environment variable in httpd.conf:
73 PerlSetEnv PERL5LIB /home/httpd/perl/extra
75 Monitor All Modules in %INC
77 To monitor and reload all modules in %INC at the beginning of request's
78 processing, simply add the following configuration to your httpd.conf:
79 PerlModule Apache2::Reload
81 PerlInitHandler Apache2::Reload
82 When working with connection filters and protocol modules
84 "Apache2::Reload" should be invoked in the pre_connection stage:
85 PerlPreConnectionHandler Apache2::Reload
87 See also the discussion on "PerlPreConnectionHandler".
89 Register Modules Implicitly
91 To only reload modules that have registered with "Apache2::Reload", add
92 the following to the httpd.conf:
93 PerlModule Apache2::Reload
95 PerlInitHandler Apache2::Reload
96 PerlSetVar ReloadAll Off
97 # ReloadAll defaults to On
98 Then any modules with the line:
100 use Apache2::Reload;
102 Will be reloaded when they change.
104 Register Modules Explicitly
106 You can also register modules explicitly in your httpd.conf file that
107 you want to be reloaded on change:
108 PerlModule Apache2::Reload
110 PerlInitHandler Apache2::Reload
111 PerlSetVar ReloadAll Off
112 PerlSetVar ReloadModules "My::Foo My::Bar Foo::Bar::Test"
113 Note that these are split on whitespace, but the module list must be in
115 quotes, otherwise Apache tries to parse the parameter list.
116 The "*" wild character can be used to register groups of files under
118 the same namespace. For example the setting:
119 PerlSetVar ReloadModules "ModPerl::* Apache2::*"
121 will monitor all modules under the namespaces "ModPerl::" and
123 "Apache2::".
124 Monitor Only Certain Sub Directories
126 To reload modules only in certain directories (and their
127 subdirectories) add the following to the httpd.conf:
128 PerlModule Apache2::Reload
130 PerlInitHandler Apache2::Reload
131 PerlSetVar ReloadDirectories "/tmp/project1 /tmp/project2"
132 You can further narrow the list of modules to be reloaded from the
134 chosen directories with "ReloadModules" as in:
135 PerlModule Apache2::Reload
137 PerlInitHandler Apache2::Reload
138 PerlSetVar ReloadDirectories "/tmp/project1 /tmp/project2"
139 PerlSetVar ReloadAll Off
140 PerlSetVar ReloadModules "MyApache2::*"
141 In this configuration example only modules from the namespace
143 "MyApache2::" found in the directories /tmp/project1/ and
144 /tmp/project2/ (and their subdirectories) will be reloaded.
145 Special "Touch" File
147 You can also declare a file, which when gets touch(1)ed, causes the
148 reloads to be performed. For example if you set:
149 PerlSetVar ReloadTouchFile /tmp/reload_modules
151 and don't touch(1) the file /tmp/reload_modules, the reloads won't
153 happen until you go to the command line and type:
154 % touch /tmp/reload_modules
156 When you do that, the modules that have been changed, will be magically
158 reloaded on the next request. This option works with any mode described
159 before.
160 Unregistering a module
162 In some cases, it might be necessary to explicitly stop reloading a
163 module.
164 Apache2::Reload->unregister_module('Some::Module');
166 But be carefull, since unregistering a module in this way will only do
168 so for the current interpreter. This feature should be used with care.
169
171 This module is perfectly suited for a development environment. Though
172 it's possible that you would like to use it in a production
173 environment, since with "Apache2::Reload" you don't have to restart the
174 server in order to reload changed modules during software updates.
175 Though this convenience comes at a price:
176 • If the "touch" file feature is used, "Apache2::Reload" has to
178 stat(2) the touch file on each request, which adds a slight but
179 most likely insignificant overhead to response times. Otherwise
180 "Apache2::Reload" will stat(2) each registered module or even
181 worse--all modules in %INC, which will significantly slow
182 everything down.
183 • Once the child process reloads the modules, the memory used by
185 these modules is not shared with the parent process anymore.
186 Therefore the memory consumption may grow significantly.
187 Therefore doing a full server stop and restart is probably a better
189 solution.
190
192 If you aren't sure whether the modules that are supposed to be
193 reloaded, are actually getting reloaded, turn the debug mode on:
194 PerlSetVar ReloadDebug On
196
198 Problems With Reloading Modules Which Do Not Declare Their Package Name
199 If you modify modules, which don't declare their "package", and rely on
200 "Apache2::Reload" to reload them, you may encounter problems: i.e.,
201 it'll appear as if the module wasn't reloaded when in fact it was. This
202 happens because when "Apache2::Reload" require()s such a module all the
203 global symbols end up in the "Apache2::Reload" namespace! So the
204 module does get reloaded and you see the compile time errors if there
205 are any, but the symbols don't get imported to the right namespace.
206 Therefore the old version of the code is running.
207 Failing to Find a File to Reload
209 "Apache2::Reload" uses %INC to find the files on the filesystem. If an
210 entry for a certain filepath in %INC is relative, "Apache2::Reload"
211 will use @INC to try to resolve that relative path. Now remember that
212 mod_perl freezes the value of @INC at the server startup, and you can
213 modify it only for the duration of one request when you need to load
214 some module which is not in on of the @INC directories. So a module
215 gets loaded, and registered in %INC with a relative path. Now when
216 "Apache2::Reload" tries to find that module to check whether it has
217 been modified, it can't find since its directory is not in @INC. So
218 "Apache2::Reload" will silently skip that module.
219 You can enable the "Debug|/Debug" mode to see what "Apache2::Reload"
221 does behind the scenes.
222 Problems with Scripts Running with Registry Handlers that Cache the Code
224 The following problem is relevant only to registry handlers that cache
225 the compiled script. For example it concerns "ModPerl::Registry" but
226 not "ModPerl::PerlRun".
227 The Problem
229 Let's say that there is a module "My::Utils":
231 #file:My/Utils.pm
233 #----------------
234 package My::Utils;
235 BEGIN { warn __PACKAGE__ , " was reloaded\n" }
236 use base qw(Exporter);
237 @EXPORT = qw(colour);
238 sub colour { "white" }
239 1;
240 And a registry script test.pl:
242 #file:test.pl
244 #------------
245 use My::Utils;
246 print "Content-type: text/plain\n\n";
247 print "the color is " . colour();
248 Assuming that the server is running in a single mode, we request the
250 script for the first time and we get the response:
251 the color is white
253 Now we change My/Utils.pm:
255 - sub colour { "white" }
257 + sub colour { "red" }
258 And issue the request again. "Apache2::Reload" does its job and we can
260 see that "My::Utils" was reloaded (look in the error_log file). However
261 the script still returns:
262 the color is white
264 The Explanation
266 Even though My/Utils.pm was reloaded, "ModPerl::Registry"'s cached code
268 won't run '"use My::Utils;"' again (since it happens only once, i.e.
269 during the compile time). Therefore the script doesn't know that the
270 subroutine reference has been changed.
271 This is easy to verify. Let's change the script to be:
273 #file:test.pl
275 #------------
276 use My::Utils;
277 print "Content-type: text/plain\n\n";
278 my $sub_int = \&colour;
279 my $sub_ext = \&My::Utils::colour;
280 print "int $sub_int\n";
281 print "ext $sub_ext\n";
282 Issue a request, you will see something similar to:
284 int CODE(0x8510af8)
286 ext CODE(0x8510af8)
287 As you can see both point to the same CODE reference (meaning that it's
289 the same symbol). After modifying My/Utils.pm again:
290 - sub colour { "red" }
292 + sub colour { "blue" }
293 and calling the script on the secondnd time, we get:
295 int CODE(0x8510af8)
297 ext CODE(0x851112c)
298 You can see that the internal CODE reference is not the same as the
300 external one.
301 The Solution
303 There are two solutions to this problem:
305 Solution 1: replace use() with an explicit require() + import().
307 - use My::Utils;
309 + require My::Utils; My::Utils->import();
310 now the changed functions will be reimported on every request.
312 Solution 2: remember to touch the script itself every time you change
314 the module that it requires.
315
317 If you use "Apache2::Reload" with a threaded MPM and multiple Perl
318 interpreters, the modules will be reloaded by each interpreter as they
319 are used, not every interpreters at once. Similar to mod_perl 1.0
320 where each child has its own Perl interpreter, the modules are reloaded
321 as each child is hit with a request.
322 If a module is loaded at startup, the syntax tree of each subroutine is
324 shared between interpreters (big win), but each subroutine has its own
325 padlist (where lexical my variables are stored). Once
326 "Apache2::Reload" reloads a module, this sharing goes away and each
327 Perl interpreter will have its own copy of the syntax tree for the
328 reloaded subroutines.
329
331 The short summary of this is: Don't use pseudo-hashes. They are
332 deprecated since Perl 5.8 and are removed in 5.9.
333 Use an array with constant indexes. Its faster in the general case, its
335 more guaranteed, and generally, it works.
336 The long summary is that some work has been done to get this module
338 working with modules that use pseudo-hashes, but it's still broken in
339 the case of a single module that contains multiple packages that all
340 use pseudo-hashes.
341 So don't do that.
343
345 mod_perl 2.0 and its core modules are copyrighted under The Apache
346 Software License, Version 2.0.
347
349 Matt Sergeant, matt@sergeant.org
350 Stas Bekman (porting to mod_perl 2.0)
352 A few concepts borrowed from "Stonehenge::Reload" by Randal Schwartz
354 and "Apache::StatINC" (mod_perl 1.x) by Doug MacEachern and Ask Bjoern
355 Hansen.
356
358 the mod_perl developers, dev@perl.apache.org
359perl v5.36.0 2023-01-19 Apache2::Reload(3)