1docs::api::ModPerl::RegUissetrryCLoonatdreirb(u3t)ed PerdlocDso:c:uampein:t:aMtoidoPnerl::RegistryLoader(3)
2
3
4
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
14 # explicit uri => filename mapping
15 my $rlbb = ModPerl::RegistryLoader->new(
16 package => 'ModPerl::RegistryBB',
17 debug => 1, # default 0
18 );
19
20 $rlbb->handler($uri, $filename);
21
22 ###
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
35 ###
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 com‐
44 pilation on the first request in every httpd instance.
45
46 This module is of course useless for those running the "ModPerl::Perl‐
47 Run" handler, because the scripts get recompiled on each request under
48 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 "ModPerl::Reg‐
55 istryBB" the object is initialized as:
56
57 my $rlbb = ModPerl::RegistryLoader->new(
58 package => 'ModPerl::RegistryBB',
59 );
60
61 If the package is not specified "ModPerl::Registry" is assumed:
62
63 my $rlbb = ModPerl::RegistryLoader->new();
64
65 To turn the debugging on, set the debug attribute to a true value:
66
67 my $rlbb = ModPerl::RegistryLoader->new(
68 package => 'ModPerl::RegistryBB',
69 debug => 1,
70 );
71
72 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
76 my $rlbb = ModPerl::RegistryLoader->new(
77 package => 'ModPerl::RegistryBB',
78 trans => \&trans,
79 );
80
81 See the handler() item for an example of using the trans attribute.
82
83 handler()
84 $rl->handler($uri, [$filename, [$virtual_hostname]]);
85
86 The handler() method takes argument of "uri" and optionally of
87 "filename" and of "virtual_hostname".
88
89 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
93 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 "Server‐
95 Root" configuration directive. For example:
96
97 httpd.conf:
98 -----------
99 ServerRoot /usr/local/apache
100 Alias /registry/ /usr/local/apache/cgi-bin/
101
102 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
111 To make the loader smarter about the URI->filename translation, you
112 may provide the "new()" method with a "trans()" function to trans‐
113 late the uri to filename.
114
115 The following example will pre-load all files ending with .pl in
116 the cgi-bin directory relative to "ServerRoot".
117
118 httpd.conf:
119 -----------
120 ServerRoot /usr/local/apache
121 Alias /registry/ /usr/local/apache/cgi-bin/
122
123 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
132 my $dir = File::Spec->catdir(Apache2::ServerUtil::server_root,
133 "cgi-bin");
134
135 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
142 my $rl = ModPerl::RegistryLoader->new(
143 package => "ModPerl::Registry",
144 trans => \&trans,
145 );
146 my $dh = DirHandle->new($dir) or die $!;
147
148 for my $file ($dh->read) {
149 next unless $file =~ /\.pl$/;
150 $rl->handler("/registry/$file");
151 }
152 }
153
154 If $virtual_hostname argument is passed it'll be used in the cre‐
155 ation 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
160 Also explained in the "ModPerl::RegistryLoader" documentation, this
161 only has an effect at run time if $ModPerl::RegistryCooker::Name‐
162 WithVirtualHost is set to true, otherwise the $virtual_hostname
163 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 environ‐
170 ments.
171
173 The original "Apache2::RegistryLoader" implemented by Doug MacEachern.
174
175 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)
181
182
183
184perl v5.8.8 2006-11-d1o9cs::api::ModPerl::RegistryLoader(3)