You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by ra...@apache.org on 2005/04/02 23:56:49 UTC
svn commit: r159823 -
perl/modperl/docs/trunk/src/docs/2.0/api/Apache2/Reload.pod
Author: randyk
Date: Sat Apr 2 13:56:47 2005
New Revision: 159823
URL: http://svn.apache.org/viewcvs?view=rev&rev=159823
Log:
s/Apache/Apache2/
Modified:
perl/modperl/docs/trunk/src/docs/2.0/api/Apache2/Reload.pod
Modified: perl/modperl/docs/trunk/src/docs/2.0/api/Apache2/Reload.pod
URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/api/Apache2/Reload.pod?view=diff&r1=159822&r2=159823
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/api/Apache2/Reload.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/api/Apache2/Reload.pod Sat Apr 2 13:56:47 2005
@@ -1,50 +1,50 @@
=head1 NAME
-Apache::Reload - Reload Perl Modules when Changed on Disk
+Apache2::Reload - Reload Perl Modules when Changed on Disk
=head1 Synopsis
# Monitor and reload all modules in %INC:
# httpd.conf:
- PerlModule Apache::Reload
- PerlInitHandler Apache::Reload
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
# when working with protocols and connection filters
- # PerlPreConnectionHandler Apache::Reload
+ # PerlPreConnectionHandler Apache2::Reload
# Reload groups of modules:
# httpd.conf:
- PerlModule Apache::Reload
- PerlInitHandler Apache::Reload
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
PerlSetVar ReloadAll Off
- PerlSetVar ReloadModules "ModPerl::* Apache::*"
+ PerlSetVar ReloadModules "ModPerl::* Apache2::*"
#PerlSetVar ReloadDebug On
# Reload a single module from within itself:
- package My::Apache::Module;
- use Apache::Reload;
+ package My::Apache2::Module;
+ use Apache2::Reload;
sub handler { ... }
1;
=head1 Description
-C<Apache::Reload> reloads modules that change on the disk.
+C<Apache2::Reload> reloads modules that change on the disk.
When Perl pulls a file via C<require>, it stores the filename in the
global hash C<%INC>. The next time Perl tries to C<require> the same
file, it sees the file in C<%INC> and does not reload from disk. This
module's handler can be configured to iterate over the modules in
C<%INC> and reload those that have changed on disk or only specific
-modules that have registered themselves with C<Apache::Reload>. It can
+modules that have registered themselves with C<Apache2::Reload>. It can
also do the check for modified modules, when a special touch-file has
been modified.
-Note that C<Apache::Reload> operates on the current context of
+Note that C<Apache2::Reload> operates on the current context of
C<@INC>. Which means, when called as a C<Perl*Handler> it will not
-see C<@INC> paths added or removed by C<Apache::Registry> scripts, as
+see C<@INC> paths added or removed by C<ModPerl::Registry> scripts, as
the value of C<@INC> is saved on server startup and restored to that
value after each request. In other words, if you want
-C<Apache::Reload> to work with modules that live in custom C<@INC>
+C<Apache2::Reload> to work with modules that live in custom C<@INC>
paths, you should modify C<@INC> when the server is started. Besides,
C<'use lib'> in the startup script, you can also set the C<PERL5LIB>
variable in the httpd's environment to include any non-standard 'lib'
@@ -64,30 +64,30 @@
request's processing, simply add the following configuration to your
I<httpd.conf>:
- PerlModule Apache::Reload
- PerlInitHandler Apache::Reload
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
When working with connection filters and protocol modules
-C<Apache::Reload> should be invoked in the pre_connection stage:
+C<Apache2::Reload> should be invoked in the pre_connection stage:
- PerlPreConnectionHandler Apache::Reload
+ PerlPreConnectionHandler Apache2::Reload
See also the discussion on
C<L<PerlPreConnectionHandler|docs::2.0::user::handlers::protocols/PerlPreConnectionHandler>>.
=head2 Register Modules Implicitly
-To only reload modules that have registered with C<Apache::Reload>,
+To only reload modules that have registered with C<Apache2::Reload>,
add the following to the I<httpd.conf>:
- PerlModule Apache::Reload
- PerlInitHandler Apache::Reload
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
PerlSetVar ReloadAll Off
# ReloadAll defaults to On
Then any modules with the line:
- use Apache::Reload;
+ use Apache2::Reload;
Will be reloaded when they change.
@@ -96,8 +96,8 @@
You can also register modules explicitly in your I<httpd.conf> file
that you want to be reloaded on change:
- PerlModule Apache::Reload
- PerlInitHandler Apache::Reload
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
PerlSetVar ReloadAll Off
PerlSetVar ReloadModules "My::Foo My::Bar Foo::Bar::Test"
@@ -107,31 +107,31 @@
The C<*> wild character can be used to register groups of files under
the same namespace. For example the setting:
- PerlSetVar ReloadModules "ModPerl::* Apache::*"
+ PerlSetVar ReloadModules "ModPerl::* Apache2::*"
will monitor all modules under the namespaces C<ModPerl::> and
-C<Apache::>.
+C<Apache2::>.
=head2 Monitor Only Certain Sub Directories
To reload modules only in certain directories (and their
subdirectories) add the following to the I<httpd.conf>:
- PerlModule Apache::Reload
- PerlInitHandler Apache::Reload
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
PerlSetVar ReloadDirectories "/tmp/project1 /tmp/project2"
You can further narrow the list of modules to be reloaded from the
chosen directories with C<ReloadModules> as in:
- PerlModule Apache::Reload
- PerlInitHandler Apache::Reload
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
PerlSetVar ReloadDirectories "/tmp/project1 /tmp/project2"
PerlSetVar ReloadAll Off
- PerlSetVar ReloadModules "MyApache::*"
+ PerlSetVar ReloadModules "MyApache2::*"
In this configuration example only modules from the namespace
-C<MyApache::> found in the directories I</tmp/project1/> and
+C<MyApache2::> found in the directories I</tmp/project1/> and
I</tmp/project2/> (and their subdirectories) will be reloaded.
=head2 Special "Touch" File
@@ -155,7 +155,7 @@
In some cases, it might be necessary to explicitely stop reloading
a module.
- Apache::Reload->unregister_module('Some::Module');
+ Apache2::Reload->unregister_module('Some::Module');
But be carefull, since unregistering a module in this way will only
do so for the current interpreter. This feature should be used with
@@ -165,7 +165,7 @@
This modules is perfectly suited for a development environment. Though
it's possible that you would like to use it in a production
-environment, since with C<Apache::Reload> you don't have to restart
+environment, since with C<Apache2::Reload> you don't have to restart
the server in order to reload changed modules during software
updates. Though this convenience comes at a price:
@@ -173,9 +173,9 @@
=item *
-If the "touch" file feature is used, C<Apache::Reload> has to stat(2)
+If the "touch" file feature is used, C<Apache2::Reload> has to stat(2)
the touch file on each request, which adds a slight but most likely
-insignificant overhead to response times. Otherwise C<Apache::Reload>
+insignificant overhead to response times. Otherwise C<Apache2::Reload>
will stat(2) each registered module or even worse--all modules in
C<%INC>, which will significantly slow everything down.
@@ -202,10 +202,10 @@
=head2 Problems With Reloading Modules Which Do Not Declare Their Package Name
If you modify modules, which don't declare their C<package>, and rely on
-C<Apache::Reload> to reload them, you may encounter problems: i.e.,
+C<Apache2::Reload> to reload them, you may encounter problems: i.e.,
it'll appear as if the module wasn't reloaded when in fact it
-was. This happens because when C<Apache::Reload> C<require()>s such a
-module all the global symbols end up in the C<Apache::Reload>
+was. This happens because when C<Apache2::Reload> C<require()>s such a
+module all the global symbols end up in the C<Apache2::Reload>
namespace! So the module does get reloaded and you see the compile
time errors if there are any, but the symbols don't get imported to
the right namespace. Therefore the old version of the code is running.
@@ -213,19 +213,19 @@
=head2 Failing to Find a File to Reload
-C<Apache::Reload> uses C<%INC> to find the files on the filesystem. If
+C<Apache2::Reload> uses C<%INC> to find the files on the filesystem. If
an entry for a certain filepath in C<%INC> is relative,
-C<Apache::Reload> will use C<@INC> to try to resolve that relative
+C<Apache2::Reload> will use C<@INC> to try to resolve that relative
path. Now remember that mod_perl freezes the value of C<@INC> at the
server startup, and you can modify it only for the duration of one
request when you need to load some module which is not in on of the
C<@INC> directories. So a module gets loaded, and registered in
-C<%INC> with a relative path. Now when C<Apache::Reload> tries to find
+C<%INC> with a relative path. Now when C<Apache2::Reload> tries to find
that module to check whether it has been modified, it can't find since
-its directory is not in C<@INC>. So C<Apache::Reload> will silently
+its directory is not in C<@INC>. So C<Apache2::Reload> will silently
skip that module.
-You can enable the C<Debug|/Debug> mode to see what C<Apache::Reload>
+You can enable the C<Debug|/Debug> mode to see what C<Apache2::Reload>
does behind the scenes.
@@ -268,7 +268,7 @@
- sub colour { "white" }
+ sub colour { "red" }
-And issue the request again. C<Apache::Reload> does its job and we can
+And issue the request again. C<Apache2::Reload> does its job and we can
see that C<My::Utils> was reloaded (look in the I<error_log>
file). However the script still returns:
@@ -328,7 +328,7 @@
=head1 Threaded MPM and Multiple Perl Interpreters
-If you use C<Apache::Reload> with a threaded MPM and multiple Perl
+If you use C<Apache2::Reload> with a threaded MPM and multiple Perl
interpreters, the modules will be reloaded by each interpreter as they
are used, not every interpreters at once. Similar to mod_perl 1.0
where each child has its own Perl interpreter, the modules are
@@ -337,7 +337,7 @@
If a module is loaded at startup, the syntax tree of each subroutine
is shared between interpreters (big win), but each subroutine has its
own padlist (where lexical my variables are stored). Once
-C<Apache::Reload> reloads a module, this sharing goes away and each
+C<Apache2::Reload> reloads a module, this sharing goes away and each
Perl interpreter will have its own copy of the syntax tree for the
reloaded subroutines.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org