1docs::api::ModPerl::RegUissetrryCLoonatdreirb(u3t)ed PerdlocDso:c:uampein:t:aMtoidoPnerl::RegistryLoader(3)
2
6 ModPerl::RegistryLoader - Compile ModPerl::RegistryCooker scripts at
7 server startup
8
10 # in startup.pl
11 use ModPerl::RegistryLoader ();
12 use File::Spec ();
13 # explicit uri => filename mapping
15 my $rlbb = ModPerl::RegistryLoader->new(
16 package => 'ModPerl::RegistryBB',
17 debug => 1, # default 0
18 );
19 $rlbb->handler($uri, $filename);
21 ###
23 # uri => filename mapping using a helper function
24 sub trans {
25 my $uri = shift;
26 $uri =~ s|^/registry/|cgi-bin/|;
27 return File::Spec->catfile(Apache2::ServerUtil::server_root, $uri);
28 }
29 my $rl = ModPerl::RegistryLoader->new(
30 package => 'ModPerl::Registry',
31 trans => \&trans,
32 );
33 $rl->handler($uri);
34 ###
36 $rlbb->handler($uri, $filename, $virtual_hostname);
37
39 This modules allows compilation of scripts, running under packages
40 derived from "ModPerl::RegistryCooker", at server startup. The
41 script's handler routine is compiled by the parent server, of which
42 children get a copy and thus saves some memory by initially sharing the
43 compiled copy with the parent and saving the overhead of script's
44 compilation on the first request in every httpd instance.
45 This module is of course useless for those running the
47 "ModPerl::PerlRun" handler, because the scripts get recompiled on each
48 request under this handler.
49
51 new()
52 When creating a new "ModPerl::RegistryLoader" object, one has to
53 specify which of the "ModPerl::RegistryCooker" derived modules to
54 use. For example if a script is going to run under
55 "ModPerl::RegistryBB" the object is initialized as:
56 my $rlbb = ModPerl::RegistryLoader->new(
58 package => 'ModPerl::RegistryBB',
59 );
60 If the package is not specified "ModPerl::Registry" is assumed:
62 my $rlbb = ModPerl::RegistryLoader->new();
64 To turn the debugging on, set the debug attribute to a true value:
66 my $rlbb = ModPerl::RegistryLoader->new(
68 package => 'ModPerl::RegistryBB',
69 debug => 1,
70 );
71 Instead of specifying explicitly a filename for each uri passed to
73 handler(), a special attribute trans can be set to a subroutine to
74 perform automatic remapping.
75 my $rlbb = ModPerl::RegistryLoader->new(
77 package => 'ModPerl::RegistryBB',
78 trans => \&trans,
79 );
80 See the handler() item for an example of using the trans attribute.
82 handler()
84 $rl->handler($uri, [$filename, [$virtual_hostname]]);
85 The handler() method takes argument of "uri" and optionally of
87 "filename" and of "virtual_hostname".
88 URI to filename translation normally doesn't happen until HTTP
90 request time, so we're forced to roll our own translation. If the
91 filename is supplied it's used in translation.
92 If the filename is omitted and a "trans" subroutine was not set in
94 new(), the loader will try using the "uri" relative to the
95 "ServerRoot" configuration directive. For example:
96 httpd.conf:
98 -----------
99 ServerRoot /usr/local/apache
100 Alias /registry/ /usr/local/apache/cgi-bin/
101 startup.pl:
103 -----------
104 use ModPerl::RegistryLoader ();
105 my $rl = ModPerl::RegistryLoader->new(
106 package => 'ModPerl::Registry',
107 );
108 # preload /usr/local/apache/cgi-bin/test.pl
109 $rl->handler(/registry/test.pl);
110 To make the loader smarter about the URI->filename translation, you
112 may provide the "new()" method with a "trans()" function to
113 translate the uri to filename.
114 The following example will pre-load all files ending with .pl in
116 the cgi-bin directory relative to "ServerRoot".
117 httpd.conf:
119 -----------
120 ServerRoot /usr/local/apache
121 Alias /registry/ /usr/local/apache/cgi-bin/
122 startup.pl:
124 -----------
125 {
126 # test the scripts pre-loading by using trans sub
127 use ModPerl::RegistryLoader ();
128 use File::Spec ();
129 use DirHandle ();
130 use strict;
131 my $dir = File::Spec->catdir(Apache2::ServerUtil::server_root,
133 "cgi-bin");
134 sub trans {
136 my $uri = shift;
137 $uri =~ s|^/registry/|cgi-bin/|;
138 return File::Spec->catfile(Apache2::ServerUtil::server_root,
139 $uri);
140 }
141 my $rl = ModPerl::RegistryLoader->new(
143 package => "ModPerl::Registry",
144 trans => \&trans,
145 );
146 my $dh = DirHandle->new($dir) or die $!;
147 for my $file ($dh->read) {
149 next unless $file =~ /\.pl$/;
150 $rl->handler("/registry/$file");
151 }
152 }
153 If $virtual_hostname argument is passed it'll be used in the
155 creation of the package name the script will be compiled into for
156 those registry handlers that use namespace_from_uri() method. See
157 also the notes on $ModPerl::RegistryCooker::NameWithVirtualHost in
158 the "ModPerl::RegistryCooker" documentation.
159 Also explained in the "ModPerl::RegistryLoader" documentation, this
161 only has an effect at run time if
162 $ModPerl::RegistryCooker::NameWithVirtualHost is set to true,
163 otherwise the $virtual_hostname argument is ignored.
164
166 "ModPerl::RegistryLoader" performs a very simple job, at run time it
167 loads and sub-classes the module passed via the package attribute and
168 overrides some of its functions, to emulate the run-time environment.
169 This allows to preload the same script into different registry
170 environments.
171
173 The original "Apache2::RegistryLoader" implemented by Doug MacEachern.
174 Stas Bekman did the porting to the new registry framework based on
176 "ModPerl::RegistryLoader".
177
179 "ModPerl::RegistryCooker", "ModPerl::Registry", "ModPerl::RegistryBB",
180 "ModPerl::PerlRun", Apache(3), mod_perl(3)
181perl v5.30.0 2019-10-d0o7cs::api::ModPerl::RegistryLoader(3)