view release on metacpan or  search on metacpan

lib/Apache2/Reload.pm  view on Meta::CPAN

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
  #PerlSetVar ReloadByModuleName 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.

Require-hooks, i.e., entries in %INC which are references, are ignored.  The 
hook should modify %INC itself, adding the path to the module file, for it to 
be reloaded.

C<Apache2::Reload> inspects and reloads the B<file> associated with a given 
module.  Changes to @INC are not recognized, as it is the file which is 
being re-required, not the module name.

In version 0.10 and earlier the B<module name>, not the file, is re-required.  
Meaning it operated on the the current context of @INC.  If you still want this 
behavior set this environment variable in I<httpd.conf>:

  PerlSetVar ReloadByModuleName On

This means, when called as a C<Perl*Handler>, C<Apache2::Reload> 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: