ModPerl::MethodLookup(3pm)

1docs::api::ModPerl::MetUhsoedrLoCooknutpr(i3b)uted PerldDooccsu:m:eanptia:t:iMoondPerl::MethodLookup(3)
2
3
4

NAME

6       ModPerl::MethodLookup -- Lookup mod_perl modules, objects and methods
7

Synopsis

9         use ModPerl::MethodLookup;
10
11         # return all module names containing XS method 'print'
12         my ($hint, @modules) =
13             ModPerl::MethodLookup::lookup_method('print');
14
15         # return only module names containing method 'print' which
16         # expects the first argument to be of type 'Apache2::Filter'
17         # (here $filter is an Apache2::Filter object)
18         my ($hint, @modules) =
19             ModPerl::MethodLookup::lookup_method('print', $filter);
20         # or
21         my ($hint, @modules) =
22             ModPerl::MethodLookup::lookup_method('print', 'Apache2::Filter');
23
24         # what XS methods defined by module 'Apache2::Filter'
25         my ($hint, @methods) =
26             ModPerl::MethodLookup::lookup_module('Apache2::Filter');
27
28         # what XS methods can be invoked on the object $r (or a ref)
29         my ($hint, @methods) =
30             ModPerl::MethodLookup::lookup_object($r);
31         # or
32         my ($hint, @methods) =
33             ModPerl::MethodLookup::lookup_object('Apache2::RequestRec');
34
35         # preload all mp2 modules in startup.pl
36         ModPerl::MethodLookup::preload_all_modules();
37
38         # command line shortcuts
39         % perl -MModPerl::MethodLookup -e print_module \
40           Apache2::RequestRec Apache2::Filter
41         % perl -MModPerl::MethodLookup -e print_object Apache2
42         % perl -MModPerl::MethodLookup -e print_method \
43           get_server_built request
44         % perl -MModPerl::MethodLookup -e print_method read
45         % perl -MModPerl::MethodLookup -e print_method read APR::Bucket
46

Description

48       mod_perl 2.0 provides many methods, which reside in various modules.
49       One has to load each of the modules before using the desired methods.
50       "ModPerl::MethodLookup" provides the Perl API for finding module names
51       which contain methods in question and other helper functions, to find
52       out out what methods defined by some module, what methods can be called
53       on a given object, etc.
54

API

56       "lookup_method()"
57
58       Find modules (packages) containing a certain method
59
60         ($hint, @modules) = lookup_method($method_name);
61         ($hint, @modules) = lookup_method($method_name, $object);
62         ($hint, @modules) = lookup_method($method_name, $class));
63
64       arg1: $method_name ( string )
65           the method name to look up
66
67       opt arg2: $object or $class
68           a blessed object or the name of the class it's blessed into. If
69           there is more than one match, this extra information is used to
70           return only modules containing methods operating on the objects of
71           the same kind.
72
73           If a sub-classed object is passed it'll be handled correctly, by
74           checking its super-class(es).  This usage is useful when the
75           "AUTOLOAD" is used to find a not yet loaded module which include
76           the called method.
77
78       ret1: $hint
79           a string containing a human readable lookup result, suggesting
80           which modules should be loaded, ready for copy-n-paste or explain‐
81           ing the failure if the lookup didn't succeed.
82
83       ret2: @modules
84           an array of modules which have matched the query, i.e. the names of
85           the modules which contain the requested method.
86
87       since: 2.0.00
88
89       Examples:
90
91       Return all module names containing XS method print:
92
93         my ($hint, @modules) =
94             ModPerl::MethodLookup::lookup_method('print');
95
96       Return only module names containing method print which expects the
97       first argument to be of type "Apache2::Filter":
98
99         my $filter = bless {}, 'Apache2::Filter';
100         my ($hint, @modules) =
101             ModPerl::MethodLookup::lookup_method('print', $filter);
102
103       or:
104
105         my ($hint, @modules) =
106             ModPerl::MethodLookup::lookup_method('print', 'Apache2::Filter');
107
108       "lookup_module()"
109
110       Find methods contained in a certain module (package)
111
112         ($hint, @methods) = lookup_module($module_name);
113
114       arg1: $module_name ( string )
115           the module name
116
117       ret1: $hint
118           a string containing a human readable lookup result, suggesting,
119           which methods the module $module_name implements, or explaining the
120           failure if the lookup failed.
121
122       ret2: @methods
123           an array of methods which have matched the query, i.e. the names of
124           the methods defined in the requested module.
125
126       since: 2.0.00
127
128       Example:
129
130       What XS methods defined by module "Apache2::Filter":
131
132         my ($hint, @methods) =
133             ModPerl::MethodLookup::lookup_module('Apache2::Filter');
134
135       "lookup_object()"
136
137         ($hint, @methods) = lookup_object($object);
138         ($hint, @methods) = lookup_object($class);
139
140       arg1: $object or $class
141           an object or a name of a class an object is blessed into
142
143           If a sub-classed object is passed it'll be handled correctly, by
144           including methods provided by its super-class(es).
145
146       ret1: $hint
147           a string containing a human readable lookup result, suggesting,
148           which methods the given object can invoke (including module names
149           that need to be loaded to use those methods), or explaining the
150           failure if the lookup failed.
151
152       ret2: @methods
153           an array of methods which have matched the query, i.e. the names of
154           the methods that can be invoked on the given object (or its class
155           name).
156
157       since: 2.0.00
158
159       META: As of this writing this function may miss some of the func‐
160       tions/methods that can be invoked on the given object. Currently we
161       can't programmatically deduct the objects they are invoked on, because
162       these methods are written in pure XS and manipulate the arguments stack
163       themselves. Currently these are mainly XS functions, not methods, which
164       of course aren't invoked on objects. There are also logging function
165       wrappers ("Apache2::Log").
166
167       Examples:
168
169       What XS methods can be invoked on the object $r:
170
171         my ($hint, @methods) =
172             ModPerl::MethodLookup::lookup_object($r);
173
174       or $r's class -- "Apache2::RequestRec":
175
176         my ($hint, @methods) =
177             ModPerl::MethodLookup::lookup_object('Apache2::RequestRec');
178
179       "preload_all_modules()"
180
181       The function "preload_all_modules()" preloads all mod_perl 2.0 modules,
182       which implement their API in XS. This is similar to the mod_perl 1.0
183       behavior which has most of its methods loaded at the startup.
184
185       CPAN modules developers should make sure their distribution loads each
186       of the used mod_perl 2.0 modules explicitly, and not use this function,
187       as it takes the fine control away from the users. One should avoid
188       doing this the production server (unless all modules are used indeed)
189       in order to save memory.
190
191       since: 2.0.00
192
193       "print_method()"
194
195       "print_method()" is a convenience wrapper for "lookup_method()", mainly
196       designed to be used from the command line. For example to print all the
197       modules which define method read execute:
198
199         % perl -MModPerl::MethodLookup -e print_method read
200
201       Since this will return more than one module, we can narrow the query to
202       only those methods which expect the first argument to be blessed into
203       class "APR::Bucket":
204
205         % perl -MModPerl::MethodLookup -e print_method read APR::Bucket
206
207       You can pass more than one method and it'll perform a lookup on each of
208       the methods. For example to lookup methods "get_server_built" and
209       "request" you can do:
210
211         % perl -MModPerl::MethodLookup -e print_method \
212           get_server_built request
213
214       The function "print_method()" is exported by default.
215
216       since: 2.0.00
217
218       "print_module()"
219
220       "print_module()" is a convenience wrapper for "lookup_module()", mainly
221       designed to be used from the command line. For example to print all the
222       methods defined in the module "Apache2::RequestRec", followed by meth‐
223       ods defined in the module "Apache2::Filter" you can run:
224
225         % perl -MModPerl::MethodLookup -e print_module \
226           Apache2::RequestRec Apache2::Filter
227
228       The function "print_module()" is exported by default.
229
230       since: 2.0.00
231
232       "print_object()"
233
234       "print_object()" is a convenience wrapper for "lookup_object()", mainly
235       designed to be used from the command line. For example to print all the
236       methods that can be invoked on object blessed into a class
237       "Apache2::RequestRec" run:
238
239         % perl -MModPerl::MethodLookup -e print_object \
240           Apache2::RequestRec
241
242       Similar to "print_object()", more than one class can be passed to this
243       function.
244
245       The function "print_object()" is exported by default.
246
247       since: 2.0.00
248

Applications

250       "AUTOLOAD"
251
252       When Perl fails to locate a method it checks whether the package the
253       object belongs to has an "AUTOLOAD" function defined and if so, calls
254       it with the same arguments as the missing method while setting a global
255       variable $AUTOLOAD (in that package) to the name of the originally
256       called method. We can use this facility to lookup the modules to be
257       loaded when such a failure occurs. Though since we have many packages
258       to take care of we will use a special "UNIVERSAL::AUTOLOAD" function
259       which Perl calls if can't find the "AUTOLOAD" function in the given
260       package.
261
262       In that function you can query "ModPerl::MethodLookup", require() the
263       module that includes the called method and call that method again using
264       the goto() trick:
265
266         use ModPerl::MethodLookup;
267         sub UNIVERSAL::AUTOLOAD {
268             my ($hint, @modules) =
269                 ModPerl::MethodLookup::lookup_method($UNIVERSAL::AUTOLOAD, @_);
270             if (@modules) {
271                 eval "require $_" for @modules;
272                 goto &$UNIVERSAL::AUTOLOAD;
273             }
274             else {
275                 die $hint;
276             }
277         }
278
279       However we don't endorse this approach. It's a better approach to
280       always abort the execution which printing the $hintand use fix the code
281       to load the missing module. Moreover installing "UNIVERSAL::AUTOLOAD"
282       may cause a lot of problems, since once it's installed Perl will call
283       it every time some method is missing (e.g. undefined "DESTROY" meth‐
284       ods). The following approach seems to somewhat work for me. It installs
285       "UNIVERSAL::AUTOLOAD" only when the the child process starts.
286
287         httpd.conf:
288         -----------
289         PerlChildInitHandler ModPerl::MethodLookupAuto
290
291         startup.pl:
292         -----------
293         {
294             package ModPerl::MethodLookupAuto;
295             use ModPerl::MethodLookup;
296
297             use Carp;
298             sub handler {
299
300                 *UNIVERSAL::AUTOLOAD = sub {
301                     my $method = $AUTOLOAD;
302                     return if $method =~ /DESTROY/; # exclude DESTROY resolving
303
304                     my ($hint, @modules) =
305                         ModPerl::MethodLookup::lookup_method($method, @_);
306                     $hint ⎪⎪= "Can't find method $AUTOLOAD";
307                     croak $hint;
308                 };
309                 return 0;
310             }
311         }
312
313       This example doesn't load the modules for you. It'll print to STDERR
314       what module should be loaded, when a method from the not-yet-loaded
315       module is called.
316
317       A similar technique is used by "Apache2::porting".
318
319       META: there is a better version of AUTOLOAD discussed on the dev list.
320       Replace the current one with it. (search the archive for EazyLife)
321
322       Command Line Lookups
323
324       When a method is used and mod_perl has reported a failure to find it,
325       it's often useful to use the command line query to figure out which
326       module needs to be loaded. For example if when executing:
327
328         $r->construct_url();
329
330       mod_perl complains:
331
332         Can't locate object method "construct_url" via package
333         "Apache2::RequestRec" at ...
334
335       you can ask "ModPerl::MethodLookup" for help:
336
337         % perl -MModPerl::MethodLookup -e print_method construct_url
338         To use method 'construct_url' add:
339                 use Apache2::URI ();
340
341       and after copy-n-pasting the use statement in our code, the problem
342       goes away.
343
344       One can create a handy alias for this technique. For example, C-style
345       shell users can do:
346
347          % alias lookup "perl -MModPerl::MethodLookup -e print_method"
348
349       For Bash-style shell users:
350
351          % alias lookup="perl -MModPerl::MethodLookup -e print_method"
352
353       Now the lookup is even easier:
354
355         % lookup construct_url
356         to use method 'construct_url' add:
357                 use Apache2::URI;
358
359       Similar aliases can be provided for "print_object()" and "print_mod‐
360       ule()".
361

Todo

363       These methods aren't yet picked by this module (the extract from the
364       map file):
365
366        modperl_filter_attributes     ⎪ MODIFY_CODE_ATTRIBUTES
367        modperl_spawn_proc_prog       ⎪ spawn_proc_prog
368        apr_ipsubnet_create           ⎪ new
369
370       Please report to the mod_perl development mailing list if you find any
371       other missing methods. But remember that as of this moment the module
372       reports only XS functions. In the future we may add support for pure
373       perl functions/methods as well.
374

Copyright

385       mod_perl 2.0 and its core modules are copyrighted under The Apache
386       Software License, Version 2.0.
387

Authors

389       The mod_perl development team and numerous contributors.
390
391
392
393perl v5.8.8                       2006-11-19docs::api::ModPerl::MethodLookup(3)