A.3. The Apache::RegistryLoader Class

Ordinarily, Apache::Registry scripts are not compiled until they are needed. This means that the very first time one of these scripts is required by a child process, there will be a delay while the script is loaded and compiled.

Apache::RegistryLoader was designed to avoid this delay by precompiling Apache::Registry scripts during the server startup phase. In addition to minimizing loading time, it also reduces memory consumption because the Registry scripts are compiled into the single server parent process before it forks off the flock of child servers. The memory occupied by this precompiled code is then shared among the children, and although there doesn't appear to be a difference in child process size when you invoke ps (on Unix systems), overall memory consumption is reduced. See the mod_perl_tuning document in the mod_perl distribution for more details.

Typically, you will invoke Apache::RegistryLoader from a Perl startup script. A typical entry looks like this:

#!/usr/local/bin/perl

use MyFavoriteModule1 ();
use MyFavoriteModule2 ();
...
use Apache::RegistryLoader ();
my $rl = Apache::RegistryLoader->new;
$rl->handler('/perl/test.pl'=> '/home/www/perl/test.pl'),
$rl->handler('/perl/test2.pl'=> '/home/www/perl/test2.pl'),
...

This code creates a new Apache::RegistryLoader object by invoking the class's new() method and then calls this object's handler() method for each script you want to load. Apache::RegistryLoader is actually a subclass of Apache::Registry which overrides certain methods such that the Apache::RegistryLoader handler() method only invokes the script compliation and caching methods of Apache::Registry.

Notice that handler() requires two arguments: the URI of the script to compile and its physical pathname. The reason you can't just provide one or the other is that the task of translating from a URI to a filename is usually done at request time by a translation handler. However, at server startup time there's no request to process, and therefore no way of getting at the translation handler.

If you specify a URI only, Apache::RegistryLoader will try to interpret it relative to the server root. This will work only if the Apache::Registry directory URI is aliased to an identically named physical directory beneath the server root.

Here's an example:

# in httpd.conf
ServerRoot /home/www
Alias      /perl/  /home/www/perl/

# in Perl startup script
use Apache::RegistryLoader ();
Apache::RegistryLoader->new->handler("/perl/test.pl");

Another solution is to provide a URI translation routine to the new() method at the time you create the Apache::RegistryLoader object. The Apache translation handlers can only be run during request time, so we must roll our own during startup. The translation handler will take an argument consisting of the script URI and return the translated physical pathname to the file as its function result. The following code fragment illustrates how to precompile all .pl files in the directory ~www/perl/ :

# in perl.conf (or any other configuration file)
PerlRequire conf/preload_scripts.pl

# in conf/preload_scripts.pl
#!/usr/local/bin/perl
use Apache::RegistryLoader ();
use DirHandle ();
use strict;

sub do_translate {
  my $uri = shift;
  return Apache->server_root_relative($uri);
};

my $rl = Apache::RegistryLoader->new(trans => &do_translate);
my $dir = Apache->server_root_relative("perl/");

my $dh = DirHandle->new($dir) or die $!;

foreach my $file ($dh->read) {
   next unless $file =~ /.pl$/;
   $rl->handler("/perl/$file");
}