1Apache2::Reload(3)    User Contributed Perl Documentation   Apache2::Reload(3)
2
3
4

NAME

6       Apache2::Reload - Reload Perl Modules when Changed on Disk
7

Synopsis

9         # Monitor and reload all modules in %INC:
10         # httpd.conf:
11         PerlModule Apache2::Reload
12         PerlInitHandler Apache2::Reload
13
14         # when working with protocols and connection filters
15         # PerlPreConnectionHandler Apache2::Reload
16
17         # 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
26         # Reload a single module from within itself:
27         package My::Apache2::Module;
28         use Apache2::Reload;
29         sub handler { ... }
30         1;
31

Description

33       "Apache2::Reload" reloads modules that change on the disk.
34
35       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
44       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
48       "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
52       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
57         PerlSetVar ReloadByModuleName On
58
59       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
69         PERL5LIB=/home/httpd/perl/extra; export PERL5LIB
70
71       in the script that starts Apache. Alternatively, you can set this
72       environment variable in httpd.conf:
73
74         PerlSetEnv PERL5LIB /home/httpd/perl/extra
75
76   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
80         PerlModule Apache2::Reload
81         PerlInitHandler Apache2::Reload
82
83       When working with connection filters and protocol modules
84       "Apache2::Reload" should be invoked in the pre_connection stage:
85
86         PerlPreConnectionHandler Apache2::Reload
87
88       See also the discussion on "PerlPreConnectionHandler".
89
90   Register Modules Implicitly
91       To only reload modules that have registered with "Apache2::Reload", add
92       the following to the httpd.conf:
93
94         PerlModule Apache2::Reload
95         PerlInitHandler Apache2::Reload
96         PerlSetVar ReloadAll Off
97         # ReloadAll defaults to On
98
99       Then any modules with the line:
100
101         use Apache2::Reload;
102
103       Will be reloaded when they change.
104
105   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
109         PerlModule Apache2::Reload
110         PerlInitHandler Apache2::Reload
111         PerlSetVar ReloadAll Off
112         PerlSetVar ReloadModules "My::Foo My::Bar Foo::Bar::Test"
113
114       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
117       The "*" wild character can be used to register groups of files under
118       the same namespace. For example the setting:
119
120         PerlSetVar ReloadModules "ModPerl::* Apache2::*"
121
122       will monitor all modules under the namespaces "ModPerl::" and
123       "Apache2::".
124
125   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
129         PerlModule Apache2::Reload
130         PerlInitHandler Apache2::Reload
131         PerlSetVar ReloadDirectories "/tmp/project1 /tmp/project2"
132
133       You can further narrow the list of modules to be reloaded from the
134       chosen directories with "ReloadModules" as in:
135
136         PerlModule Apache2::Reload
137         PerlInitHandler Apache2::Reload
138         PerlSetVar ReloadDirectories "/tmp/project1 /tmp/project2"
139         PerlSetVar ReloadAll Off
140         PerlSetVar ReloadModules "MyApache2::*"
141
142       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
146   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
150         PerlSetVar ReloadTouchFile /tmp/reload_modules
151
152       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
155         % touch /tmp/reload_modules
156
157       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
161   Unregistering a module
162       In some cases, it might be necessary to explicitly stop reloading a
163       module.
164
165         Apache2::Reload->unregister_module('Some::Module');
166
167       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

Performance Issues

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
177       •   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
184       •   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
188       Therefore doing a full server stop and restart is probably a better
189       solution.
190

Debug

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
195         PerlSetVar ReloadDebug On
196

Caveats

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
208   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
220       You can enable the "Debug|/Debug" mode to see what "Apache2::Reload"
221       does behind the scenes.
222
223   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
228       The Problem
229
230       Let's say that there is a module "My::Utils":
231
232         #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
241       And a registry script test.pl:
242
243         #file:test.pl
244         #------------
245         use My::Utils;
246         print "Content-type: text/plain\n\n";
247         print "the color is " . colour();
248
249       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
252         the color is white
253
254       Now we change My/Utils.pm:
255
256         -  sub colour { "white" }
257         +  sub colour { "red" }
258
259       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
263         the color is white
264
265       The Explanation
266
267       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
272       This is easy to verify. Let's change the script to be:
273
274         #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
283       Issue a request, you will see something similar to:
284
285         int CODE(0x8510af8)
286         ext CODE(0x8510af8)
287
288       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
291         -  sub colour { "red" }
292         +  sub colour { "blue" }
293
294       and calling the script on the secondnd time, we get:
295
296         int CODE(0x8510af8)
297         ext CODE(0x851112c)
298
299       You can see that the internal CODE reference is not the same as the
300       external one.
301
302       The Solution
303
304       There are two solutions to this problem:
305
306       Solution 1: replace use() with an explicit require() + import().
307
308        - use My::Utils;
309        + require My::Utils; My::Utils->import();
310
311       now the changed functions will be reimported on every request.
312
313       Solution 2: remember to touch the script itself every time you change
314       the module that it requires.
315

Threaded MPM and Multiple Perl Interpreters

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
323       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

Pseudo-hashes

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
334       Use an array with constant indexes. Its faster in the general case, its
335       more guaranteed, and generally, it works.
336
337       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
342       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

Authors

349       Matt Sergeant, matt@sergeant.org
350
351       Stas Bekman (porting to mod_perl 2.0)
352
353       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

MAINTAINERS

358       the mod_perl developers, dev@perl.apache.org
359
360
361
362perl v5.36.0                      2023-01-19                Apache2::Reload(3)
Impressum