ModPerl::RegistryLoader(3pm)

1docs::api::ModPerl::RegUissetrryCLoonatdreirb(u3t)ed PerdlocDso:c:uampein:t:aMtoidoPnerl::RegistryLoader(3)
2
3
4

NAME

6       ModPerl::RegistryLoader - Compile ModPerl::RegistryCooker scripts at
7       server startup
8

Synopsis

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

Description

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
46       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

Methods

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
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
95           "ServerRoot" 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
113           translate 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
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
160           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

Implementation Notes

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

Authors

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

NAME

Synopsis

Description

Methods

Implementation Notes

Authors

SEE ALSO