libapa...yLoader(3pm)

💖 libapa...yLoader(3pm) — the manual page, but make it make sense

okay bestie, pull up a chair, because this one's the ModPerl::RegistryLoader page from the User Contributed Perl Documentation, and it's genuinely useful, no cap. Let's get into it. ✨

---

✨ NAME ✨

ModPerl::RegistryLoader — compile ModPerl::RegistryCooker scripts at server startup 🎀

like, before anyone even knocks on the door. iconic behavior.

---

🦋 SYNOPSIS 🦋

# in startup.pl
use ModPerl::RegistryLoader ();
use File::Spec ();

# explicit uri => filename mapping
my $rlbb = ModPerl::RegistryLoader->new(
    package => 'ModPerl::RegistryBB',
    debug   => 1, # default 0
);

$rlbb->handler($uri, $filename);

###
# uri => filename mapping using a helper function
sub trans {
    my $uri = shift;
    $uri =~ s|^/registry/|cgi-bin/|;
    return File::Spec->catfile(Apache2::ServerUtil::server_root, $uri);
}
my $rl = ModPerl::RegistryLoader->new(
    package => 'ModPerl::Registry',
    trans   => \&trans,
);
$rl->handler($uri);

###
$rlbb->handler($uri, $filename, $virtual_hostname);

---

🌸 DESCRIPTION 🌸

so this module lets you compile scripts — the ones running under packages derived from ModPerl::RegistryCooker — at server startup. 🫶

the way it works: the script's handler routine gets compiled by the parent server, and then all the children get a copy of it. that means memory is saved because the compiled copy is initially shared with the parent, and you also skip the whole overhead of compiling the script on the very first request in every single httpd instance. efficiency queen. 👑

lowkey important: this module is useless for anyone running the ModPerl::PerlRun handler, because under that handler the scripts get recompiled on each request. so like… don't. 💀

---

💅 METHODS 💅

new()

when u create a new ModPerl::RegistryLoader object, you gotta say which of the ModPerl::RegistryCooker derived modules you're using. for example, if a script is gonna run under ModPerl::RegistryBB, you init the object like this:

my $rlbb = ModPerl::RegistryLoader->new(
    package => 'ModPerl::RegistryBB',
);

if the package isn't specified, ModPerl::Registry is assumed. default queen behavior:

my $rlbb = ModPerl::RegistryLoader->new();

to turn debugging on, set the debug attribute to a true value:

my $rlbb = ModPerl::RegistryLoader->new(
    package => 'ModPerl::RegistryBB',
    debug   => 1,
);

and instead of specifying a filename explicitly for every single uri you pass to handler(), there's a special attribute called trans that you can set to a subroutine, and it does the automatic remapping for you. bestie behavior fr fr:

my $rlbb = ModPerl::RegistryLoader->new(
    package => 'ModPerl::RegistryBB',
    trans   => \&trans,
);

peep the handler() item below for an actual example of the trans attribute in action. 👀

handler()

$rl->handler($uri, [$filename, [$virtual_hostname]]);

the handler() method takes an argument of uri, and optionally filename and virtual_hostname. 🎀

now, URI to filename translation normally doesn't happen until HTTP request time, so we're forced to roll our own translation. if the filename is supplied, it's used in the translation. simple as that.

if the filename is omitted and a trans subroutine wasn't set in new(), the loader will try using the uri relative to the ServerRoot configuration directive. for example:

httpd.conf:
-----------
ServerRoot /usr/local/apache
Alias /registry/ /usr/local/apache/cgi-bin/

startup.pl:
-----------
use ModPerl::RegistryLoader ();
my $rl = ModPerl::RegistryLoader->new(
    package => 'ModPerl::Registry',
);
# preload /usr/local/apache/cgi-bin/test.pl
$rl->handler(/registry/test.pl);

to make the loader smarter about the URI->filename translation, you may give the new() method a trans() function to translate the uri to filename.

the following example pre-loads all files ending with .pl in the cgi-bin directory relative to ServerRoot. slay.

httpd.conf:
-----------
ServerRoot /usr/local/apache
Alias /registry/ /usr/local/apache/cgi-bin/

startup.pl:
-----------
{
    # test the scripts pre-loading by using trans sub
    use ModPerl::RegistryLoader ();
    use File::Spec ();
    use DirHandle ();
    use strict;

    my $dir = File::Spec->catdir(Apache2::ServerUtil::server_root,
                                "cgi-bin");

    sub trans {
        my $uri = shift;
        $uri =~ s|^/registry/|cgi-bin/|;
        return File::Spec->catfile(Apache2::ServerUtil::server_root,
                                   $uri);
    }

    my $rl = ModPerl::RegistryLoader->new(
        package => "ModPerl::Registry",
        trans   => \&trans,
    );
    my $dh = DirHandle->new($dir) or die $!;

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

if the $virtual_hostname argument is passed, it'll be used in the creation of the package name that the script gets compiled into — but only for those registry handlers that use the namespace_from_uri() method. also go read the notes on $ModPerl::RegistryCooker::NameWithVirtualHost in the ModPerl::RegistryCooker documentation, iykyk. 📚

and like, this is also explained in the ModPerl::RegistryLoader documentation, but here's the tea: this only has an effect at run time if $ModPerl::RegistryCooker::NameWithVirtualHost is set to true. otherwise the $virtual_hostname argument is ignored. 🙈

---

🧚 IMPLEMENTATION NOTES 🧚

ModPerl::RegistryLoader does a very simple job: at run time it loads and sub-classes the module you passed via the package attribute, then overrides some of its functions, all to emulate the run-time environment. 🌈

which is what lets you preload the same script into different registry environments. cute, right?

---

👑 AUTHORS 👑

• the original Apache2::RegistryLoader was implemented by Doug MacEachern.
• Stas Bekman did the porting to the new registry framework based on ModPerl::RegistryLoader.

---

🔥 SEE ALSO 🔥

ModPerl::RegistryCooker, ModPerl::Registry, ModPerl::RegistryBB, ModPerl::PerlRun, Apache(3), mod_perl(3)

---

and that's the whole page, bestie!! 🌟 this was perl v5.42.3, dated 2026-08-20, from the libapa...yLoader(3pm) era of the manual. go preload something. mwah. 💜