--- /dev/null Fri Oct 16 06:02:02 2009
+++ mod_perl-2.0.4/lib/Apache2/Reload.pm Sun Nov 19 15:31:40 2006
@@ -0,0 +1,185 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+package Apache2::Reload;
+
+use strict;
+use warnings FATAL => 'all';
+
+use mod_perl2;
+
+our $VERSION = '0.09';
+
+use Apache2::Const -compile => qw(OK);
+
+use Apache2::Connection;
+use Apache2::ServerUtil;
+use Apache2::RequestUtil;
+
+use ModPerl::Util ();
+
+use vars qw(%INCS %Stat $TouchTime);
+
+%Stat = ($INC{"Apache2/Reload.pm"} => time);
+
+$TouchTime = time;
+
+sub import {
+ my $class = shift;
+ my ($package, $file) = (caller)[0,1];
+
+ $class->register_module($package, $file);
+}
+
+sub package_to_module {
+ my $package = shift;
+ $package =~ s/::/\//g;
+ $package .= ".pm";
+ return $package;
+}
+
+sub module_to_package {
+ my $module = shift;
+ $module =~ s/\//::/g;
+ $module =~ s/\.pm$//g;
+ return $module;
+}
+
+sub register_module {
+ my ($class, $package, $file) = @_;
+ my $module = package_to_module($package);
+
+ if ($file) {
+ $INCS{$module} = $file;
+ }
+ else {
+ $file = $INC{$module};
+ return unless $file;
+ $INCS{$module} = $file;
+ }
+}
+
+sub unregister_module {
+ my ($class, $package) = @_;
+ my $module = package_to_module($package);
+ delete $INCS{$module};
+}
+
+# the first argument is:
+# $c if invoked as 'PerlPreConnectionHandler'
+# $r if invoked as 'PerlInitHandler'
+sub handler {
+ my $o = shift;
+ $o = $o->base_server if ref($o) eq 'Apache2::Connection';
+
+ my $DEBUG = ref($o) && (lc($o->dir_config("ReloadDebug") || '') eq 'on');
+
+ my $TouchFile = ref($o) && $o->dir_config("ReloadTouchFile");
+
+ my $ConstantRedefineWarnings = ref($o) &&
+ (lc($o->dir_config("ReloadConstantRedefineWarnings") || '') eq 'off')
+ ? 0 : 1;
+
+ my $TouchModules;
+
+ if ($TouchFile) {
+ warn "Checking mtime of $TouchFile\n" if $DEBUG;
+ my $touch_mtime = (stat $TouchFile)[9] || return Apache2::Const::OK;
+ return Apache2::Const::OK unless $touch_mtime > $TouchTime;
+ $TouchTime = $touch_mtime;
+ open my $fh, $TouchFile or die "Can't open '$TouchFile': $!";
+ $TouchModules = <$fh>;
+ chomp $TouchModules if $TouchModules;
+ }
+
+ if (ref($o) && (lc($o->dir_config("ReloadAll") || 'on') eq 'on')) {
+ *Apache2::Reload::INCS = \%INC;
+ }
+ else {
+ *Apache2::Reload::INCS = \%INCS;
+ my $ExtraList =
+ $TouchModules ||
+ (ref($o) && $o->dir_config("ReloadModules")) ||
+ '';
+ my @extra = split /\s+/, $ExtraList;
+ foreach (@extra) {
+ if (/(.*)::\*$/) {
+ my $prefix = $1;
+ $prefix =~ s/::/\//g;
+ foreach my $match (keys %INC) {
+ if ($match =~ /^\Q$prefix\E/) {
+ $Apache2::Reload::INCS{$match} = $INC{$match};
+ }
+ }
+ }
+ else {
+ Apache2::Reload->register_module($_);
+ }
+ }
+ }
+
+ my $ReloadDirs = ref($o) && $o->dir_config("ReloadDirectories");
+ my @watch_dirs = split(/\s+/, $ReloadDirs||'');
+
+ my @changed;
+ foreach my $key (sort { $a cmp $b } keys %Apache2::Reload::INCS) {
+ my $file = $Apache2::Reload::INCS{$key};
+
+ next unless defined $file;
+ next if @watch_dirs && !grep { $file =~ /^$_/ } @watch_dirs;
+ warn "Apache2::Reload: Checking mtime of $key\n" if $DEBUG;
+
+ my $mtime = (stat $file)[9];
+
+ unless (defined($mtime) && $mtime) {
+ for (@INC) {
+ $mtime = (stat "$_/$file")[9];
+ last if defined($mtime) && $mtime;
+ }
+ }
+
+ warn("Apache2::Reload: Can't locate $file\n"), next
+ unless defined $mtime and $mtime;
+
+ unless (defined $Stat{$file}) {
+ $Stat{$file} = $^T;
+ }
+
+ if ($mtime > $Stat{$file}) {
+ push @changed, $key;
+ }
+ $Stat{$file} = $mtime;
+ }
+
+ #First, let's unload all changed modules
+ foreach my $module (@changed) {
+ my $package = module_to_package($module);
+ ModPerl::Util::unload_package($package);
+ }
+
+ #Then, let's reload them all, so that module dependencies can satisfy
+ #themselves in the correct order.
+ foreach my $module (@changed) {
+ my $package = module_to_package($module);
+ require $module;
+ warn("Apache2::Reload: process $$ reloading $package from $module\n")
+ if $DEBUG;
+ }
+
+ return Apache2::Const::OK;
+}
+
+1;
+__END__
--- /dev/null Fri Oct 16 06:02:02 2009
+++ mod_perl-2.0.4/docs/api/Apache2/Reload.pod Sun Nov 19 15:32:13 2006
@@ -1,0 +1,380 @@
+=head1 NAME
+
+Apache2::Reload - Reload Perl Modules when Changed on Disk
+
+=head1 Synopsis
+
+ # Monitor and reload all modules in %INC:
+ # httpd.conf:
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
+
+ # when working with protocols and connection filters
+ # PerlPreConnectionHandler Apache2::Reload
+
+ # Reload groups of modules:
+ # httpd.conf:
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
+ PerlSetVar ReloadAll Off
+ PerlSetVar ReloadModules "ModPerl::* Apache2::*"
+ #PerlSetVar ReloadDebug On
+
+ # Reload a single module from within itself:
+ package My::Apache2::Module;
+ use Apache2::Reload;
+ sub handler { ... }
+ 1;
+
+=head1 Description
+
+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<Apache2::Reload>. It can
+also do the check for modified modules, when a special touch-file has
+been modified.
+
+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<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<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'
+directories that you choose. For example, to accomplish that you can
+include a line:
+
+ PERL5LIB=/home/httpd/perl/extra; export PERL5LIB
+
+in the script that starts Apache. Alternatively, you can set this
+environment variable in I<httpd.conf>:
+
+ PerlSetEnv PERL5LIB /home/httpd/perl/extra
+
+=head2 Monitor All Modules in C<%INC>
+
+To monitor and reload all modules in C<%INC> at the beginning of
+request's processing, simply add the following configuration to your
+I<httpd.conf>:
+
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
+
+When working with connection filters and protocol modules
+C<Apache2::Reload> should be invoked in the pre_connection stage:
+
+ 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<Apache2::Reload>,
+add the following to the I<httpd.conf>:
+
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
+ PerlSetVar ReloadAll Off
+ # ReloadAll defaults to On
+
+Then any modules with the line:
+
+ use Apache2::Reload;
+
+Will be reloaded when they change.
+
+=head2 Register Modules Explicitly
+
+You can also register modules explicitly in your I<httpd.conf> file
+that you want to be reloaded on change:
+
+ PerlModule Apache2::Reload
+ PerlInitHandler Apache2::Reload
+ PerlSetVar ReloadAll Off
+ PerlSetVar ReloadModules "My::Foo My::Bar Foo::Bar::Test"
+
+Note that these are split on whitespace, but the module list B<must>
+be in quotes, otherwise Apache tries to parse the parameter list.
+
+The C<*> wild character can be used to register groups of files under
+the same namespace. For example the setting:
+
+ PerlSetVar ReloadModules "ModPerl::* Apache2::*"
+
+will monitor all modules under the namespaces C<ModPerl::> and
+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 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 Apache2::Reload
+ PerlInitHandler Apache2::Reload
+ PerlSetVar ReloadDirectories "/tmp/project1 /tmp/project2"
+ PerlSetVar ReloadAll Off
+ PerlSetVar ReloadModules "MyApache2::*"
+
+In this configuration example only modules from the namespace
+C<MyApache2::> found in the directories I</tmp/project1/> and
+I</tmp/project2/> (and their subdirectories) will be reloaded.
+
+=head2 Special "Touch" File
+
+You can also declare a file, which when gets C<touch(1)>ed, causes the
+reloads to be performed. For example if you set:
+
+ PerlSetVar ReloadTouchFile /tmp/reload_modules
+
+and don't C<touch(1)> the file I</tmp/reload_modules>, the reloads
+won't happen until you go to the command line and type:
+
+ % touch /tmp/reload_modules
+
+When you do that, the modules that have been changed, will be
+magically reloaded on the next request. This option works with any
+mode described before.
+
+=head2 Unregistering a module
+
+In some cases, it might be necessary to explicitely stop reloading
+a 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
+care.
+
+=head1 Performance Issues
+
+This module 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<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:
+
+=over
+
+=item *
+
+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<Apache2::Reload>
+will stat(2) each registered module or even worse--all modules in
+C<%INC>, which will significantly slow everything down.
+
+=item *
+
+Once the child process reloads the modules, the memory used by these
+modules is not shared with the parent process anymore. Therefore the
+memory consumption may grow significantly.
+
+=back
+
+Therefore doing a full server stop and restart is probably a better
+solution.
+
+=head1 Debug
+
+If you aren't sure whether the modules that are supposed to be
+reloaded, are actually getting reloaded, turn the debug mode on:
+
+ PerlSetVar ReloadDebug On
+
+=head1 Caveats
+
+=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<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<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.
+
+
+=head2 Failing to Find a File to Reload
+
+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<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<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<Apache2::Reload> will silently
+skip that module.
+
+You can enable the C<Debug|/Debug> mode to see what C<Apache2::Reload>
+does behind the scenes.
+
+
+
+=head2 Problems with Scripts Running with Registry Handlers that Cache the Code
+
+The following problem is relevant only to registry handlers that cache
+the compiled script. For example it concerns
+C<L<ModPerl::Registry|docs::2.0::api::ModPerl::Registry>> but not
+C<L<ModPerl::PerlRun|docs::2.0::api::ModPerl::PerlRun>>.
+
+=head3 The Problem
+
+Let's say that there is a module C<My::Utils>:
+
+ #file:My/Utils.pm
+ #----------------
+ package My::Utils;
+ BEGIN { warn __PACKAGE__ , " was reloaded\n" }
+ use base qw(Exporter);
+ @EXPORT = qw(colour);
+ sub colour { "white" }
+ 1;
+
+And a registry script F<test.pl>:
+
+ #file:test.pl
+ #------------
+ use My::Utils;
+ print "Content-type: text/plain\n\n";
+ print "the color is " . colour();
+
+Assuming that the server is running in a single mode, we request the
+script for the first time and we get the response:
+
+ the color is white
+
+Now we change F<My/Utils.pm>:
+
+ - sub colour { "white" }
+ + sub colour { "red" }
+
+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:
+
+ the color is white
+
+=head3 The Explanation
+
+Even though F<My/Utils.pm> was reloaded, C<ModPerl::Registry>'s cached
+code won't run 'C<use My::Utils;>' again (since it happens only once,
+i.e. during the compile time). Therefore the script doesn't know that
+the subroutine reference has been changed.
+
+This is easy to verify. Let's change the script to be:
+
+ #file:test.pl
+ #------------
+ use My::Utils;
+ print "Content-type: text/plain\n\n";
+ my $sub_int = \&colour;
+ my $sub_ext = \&My::Utils::colour;
+ print "int $sub_int\n";
+ print "ext $sub_ext\n";
+
+Issue a request, you will see something similar to:
+
+ int CODE(0x8510af8)
+ ext CODE(0x8510af8)
+
+As you can see both point to the same CODE reference (meaning that
+it's the same symbol). After modifying F<My/Utils.pm> again:
+
+ - sub colour { "red" }
+ + sub colour { "blue" }
+
+and calling the script on the secondnd time, we get:
+
+ int CODE(0x8510af8)
+ ext CODE(0x851112c)
+
+You can see that the internal CODE reference is not the same as the
+external one.
+
+=head3 The Solution
+
+There are two solutions to this problem:
+
+Solution 1: replace C<use()> with an explicit C<require()> +
+C<import()>.
+
+ - use My::Utils;
+ + require My::Utils; My::Utils->import();
+
+now the changed functions will be reimported on every request.
+
+Solution 2: remember to touch the script itself every time you change
+the module that it requires.
+
+=head1 Threaded MPM and Multiple Perl Interpreters
+
+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
+reloaded as each child is hit with a request.
+
+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<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.
+
+
+=head1 Pseudo-hashes
+
+The short summary of this is: Don't use pseudo-hashes. They are
+deprecated since Perl 5.8 and are removed in 5.9.
+
+Use an array with constant indexes. Its faster in the general case,
+its more guaranteed, and generally, it works.
+
+The long summary is that some work has been done to get this module
+working with modules that use pseudo-hashes, but it's still broken in
+the case of a single module that contains multiple packages that all
+use pseudo-hashes.
+
+So don't do that.
+
+
+
+
+=head1 Copyright
+
+mod_perl 2.0 and its core modules are copyrighted under
+The Apache Software License, Version 2.0.
+
+
+=head1 Authors
+
+Matt Sergeant, [email protected]
+
+Stas Bekman (porting to mod_perl 2.0)
+
+A few concepts borrowed from C<Stonehenge::Reload> by Randal Schwartz
+and C<Apache::StatINC> (mod_perl 1.x) by Doug MacEachern and Ask
+Bjoern Hansen.
+
+=cut
+