19
19
C<L<ModPerl::MethodLookup|docs::2.0::api::ModPerl::MethodLookup>> can
20
20
be used to find out which modules need to be used.
27
=head2 Method Handlers
29
In mod_perl 2.0 method handlers are declared using the C<method>
35
sub handler : method {
40
See the I<attributes> manpage.
42
If C<Class-E<gt>method> syntax is used for a C<Perl*Handler>, the
43
C<:method> attribute is not required.
45
META: need to port the method handlers document from mp1 guide, may be
46
keep it as a separate document. Meanwhile refer to L<that
47
document|docs::1.0::guide::method_handlers>, though L<replace the C<$$>
48
prototype with the C<:method> attribute
49
|docs::2.0::user::porting::compat/Method_Handlers>.
54
It's possible to arrange for cleanups to happen at the end of various
55
phases. One can't rely on C<END> blocks to do the job, since these
56
L<don't get executed|/C_END__Blocks> until the interpreter quits, with
58
L<Registry|docs::2.0::api::ModPerl::Registry/C_END__Blocks> handlers.
60
Module authors needing to run cleanups after each HTTP request, should
62
C<L<PerlCleanupHandler|docs::2.0::user::handlers::http/PerlCleanupHandler>>.
64
Module authors needing to run cleanups at other times can always
65
register a cleanup callback via
66
C<L<cleanup_register|docs::2.0::api::APR::Pool/C_cleanup_register_>>
67
on the pool object of choice. Here are some examples of its usage:
69
To run something at the server shutdown and restart use
70
C<$s-E<gt>pool-E<gt>cleanup_register()> in F<startup.pl>:
72
#PerlRequire startup.pl
73
use Apache::ServerUtil ();
76
warn "parent pid is $$\n";
77
my $pool = Apache->server->pool;
78
$pool->cleanup_register(\&cleanup);
79
sub cleanup { warn "server cleanup in $$\n" }
81
This is usually useful when some server-wide cleanup should be
82
performed when the server is stopped or restarted.
84
To run a cleanup at the end of each connection phase, assign a cleanup
85
callback to the connection pool object:
87
use Apache::Connection ();
91
$pool->cleanup_register(\&my_cleanup);
92
sub my_cleanup { ... }
94
You can also create your own pool object, register a cleanup callback
95
and it'll be called when the object is destroyed:
101
my $pool = APR::Pool->new;
102
$pool->cleanup_register(\&cleanup, \@args);
106
my @args = @{ +shift };
107
warn "cleanup was called with args: @args";
110
In this example the cleanup callback gets called, when C<$pool> goes
111
out of scope and gets destroyed. This is very similar to OO C<DESTROY>
22
115
=head1 Goodies Toolkit
24
117
=head2 Environment Variables
177
264
In the following sections we discuss the specifics of Apache behavior
178
265
relevant to mod_perl developers.
180
=head2 Sending HTTP Response Headers
267
=head2 HTTP Response Headers
269
=head3 Generating HTTP Response Headers
271
The best approach for generating HTTP response headers is by using the
272
L<mod_perl API|docs::2.0::api::Apache::RequestRec>. Some common
273
headers have dedicated methods, others are set by manipulating the
274
C<L<headers_out|docs::2.0::api::Apache::RequestRec/C_headers_out_>>
277
For example to set the I<Content-type> header you should call
278
C<L<$r-E<gt>content_type|docs::2.0::api::Apache::RequestRec/C_content_type_>>:
280
use Apache::RequestRec ();
281
$r->content_type('text/html');
283
To C<L<set|docs::2.0::api::APR::Table/C_set_>> a custom header
284
I<My-Header> you should call:
286
use Apache::RequestRec ();
288
$r->headers_out->set(My-Header => "SomeValue");
290
If you are inside a registry script L<you can still
291
access|docs::2.0::user::coding::coding/Getting_the_C__r__Object> the
292
C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> object.
294
Howerever you can choose a slower method of generating headers by just
295
printing them out before printing any response. This will work only if
297
+ParseHeaders|docs::2.0::user::config::config/C_ParseHeaders_>> is
298
in effect. For example:
300
print "Content-type: text/html\n";
301
print "My-Header: SomeValue\n";
304
This method is slower since Apache needs to parse the text to identify
305
certain headers it needs to know about. It also has several
306
limitations which we will now discuss.
308
When using this approach you must make sure that the C<STDOUT>
309
filehandle is not set to flush the data after each print (which is set
310
by the value of a special perl variable C<$|>). Here we assume that
311
STDOUT is the currently C<select()>ed filehandle and C<$|> affects it.
313
For example this code won't work:
316
print "Content-type: text/html\n";
317
print "My-Header: SomeValue\n";
320
Having a true C<$|> causes the first print() call to flush its data
321
immediately, which is sent to the internal HTTP header parser, which
322
will fail since it won't see the terminating C<"\n\n">. One solution
323
is to make sure that STDOUT won't flush immediately, like so:
326
print "Content-type: text/html\n";
327
print "My-Header: SomeValue\n";
330
Notice that we C<local()>ize that change, so it L<won't affect any
332
code|docs::general::perl_reference::perl_reference/The_Scope_of_the_Special_Perl_Variables>.
334
If you send headers line by line and their total length is bigger than
335
8k, you will have the header parser problem again, since mod_perl will
336
flush data when the 8k buffer gets full. In which case the solution is
337
not to print the headers one by one, but to buffer them all in a
338
variable and then print the whole set at once.
340
Notice that you don't have any of these problems with mod_cgi, because
341
it ignores any of the flush attempts by Perl. mod_cgi simply opens a
342
pipe to the external process and reads any output sent from that
345
If you use C<$r> to set headers as explained at the beginning of this
346
section, you won't encounter any of these problems.
348
Finally, If you don't want Apache to send its own headers and you want
349
to send your own set of headers (non-parsed headers handlers) use
351
C<L<$r-E<gt>assbackwards|docs::2.0::api::Apache::RequestRec/C_assbackwards_>>
352
method. Notice that registry handlers will do that for you if the
353
script's name start with the C<nph-> prefix.
358
=head3 Forcing HTTP Response Headers Out
182
360
Apache 2.0 doesn't provide a method to force HTTP response headers
183
361
sending (what used to be done by C<send_http_header()> in Apache
184
362
1.3). HTTP response headers are sent as soon as the first bits of the
185
363
response body are seen by the special core output filter that
186
generates these headers. When the response handler send the first
364
generates these headers. When the response handler sends the first
187
365
chunks of body it may be cached by the mod_perl internal buffer or
188
366
even by some of the output filters. The response handler needs to
189
flush in order to tell all the components participating in the sending
190
of the response to pass the data out.
367
flush the output in order to tell all the components participating in
368
the sending of the response to pass the data out.
192
370
For example if the handler needs to perform a relatively long-running
193
371
operation (e.g. a slow db lookup) and the client may timeout if it
220
401
the issues is that the HTTP response filters are not setup before the
223
407
=head1 Perl Specifics in the mod_perl Environment
225
409
In the following sections we discuss the specifics of Perl behavior
415
=head2 C<BEGIN> Blocks
417
Perl executes C<BEGIN> blocks as soon as possible, at the time of
418
compiling the code. The same is true under mod_perl. However, since
419
mod_perl normally only compiles scripts and modules once, either in
420
the parent server (at the server startup) or once per-child (on the
421
first request using a module), C<BEGIN> blocks in that code will only
422
be run once. As the C<perlmod> manpage explains, once a C<BEGIN>
423
block has run, it is immediately undefined. In the mod_perl
424
environment, this means that C<BEGIN> blocks will not be run during
425
the response to an incoming request unless that request happens to be
426
the one that causes the compilation of the code, i.e. if it wasn't
429
C<BEGIN> blocks in modules and files pulled in via C<require()> or
430
C<use()> will be executed:
436
Only once, if pulled in by the parent process at the server startup.
440
Once per each child process or Perl interpreter if not pulled in by
445
An additional time, once per each child process or Perl interpreter if
446
the module is reloaded off disk again via
447
C<L<Apache::Reload|docs::2.0::api::Apache::Reload>>.
451
Unpredictable if you fiddle with C<%INC> yourself.
455
The C<BEGIN> blocks behavior is different in
456
C<L<ModPerl::Registry|docs::2.0::api::ModPerl::Registry/C_BEGIN__Blocks>>
458
C<L<ModPerl::PerlRun|docs::2.0::api::ModPerl::PerlRun/C_BEGIN__Blocks>>
459
handlers, and their subclasses.
465
=head2 C<CHECK> and C<INIT> Blocks
467
C<CHECK> and C<INIT> blocks run when the source code compilation is
468
complete, but before the program starts. C<CHECK> can mean
469
"checkpoint" or "double-check" or even just "stop". C<INIT> stands for
470
"initialization". The difference is subtle; C<CHECK> blocks are run
471
just after the compilation ends, C<INIT> just before the runtime
472
begins. (Hence the C<-c> command-line perl option runs C<CHECK> blocks
473
but not C<INIT> blocks.)
475
Perl only calls these blocks during I<perl_parse()>, which mod_perl
476
calls once at startup time. Under threaded mpm, these blocks will be
477
called once per C<L<parent perl interpreter
478
startup|docs::2.0::user::config::config/C_Parent_>>. Therefore
479
C<CHECK> and C<INIT> blocks don't work after the server is started,
480
for the same reason these code samples don't work:
482
% perl -e 'eval qq(CHECK { print "ok\n" })'
483
% perl -e 'eval qq(INIT { print "ok\n" })'
490
As the C<perlmod> manpage explains, an C<END> block is executed as
491
late as possible, that is, when the interpreter exits. So for example
492
mod_cgi will run its C<END> blocks on each invocation, since on every
493
invocation it starts a new interpreter and then kills it when the
494
request processing is done.
496
In the mod_perl environment, the interpreter does not exit after
497
serving a single request (unless it is configured to do so) and hence
498
it will run its C<END> blocks only when it exits, which usually
499
happens during the server shutdown, but may also happen earlier than
500
that (e.g. a process exits because it has served a
501
C<MaxRequestsPerChild> number of requests).
503
mod_perl does L<make a special
504
case|docs::2.0::api::ModPerl::Registry/C_END__Blocks>
505
for scripts running under
506
C<L<ModPerl::Registry|docs::2.0::api::ModPerl::Registry>> and friends.
508
The L<Cleaning up|/Cleaning_up> section explains how to deal with
509
cleanups for non-Registry handlers.
511
C<L<ModPerl::Global|docs::2.0::api::ModPerl::Global>> API:
512
C<L<special_list_register|docs::2.0::api::ModPerl::Global/C_special_list_register_>>,
513
C<L<special_list_call|docs::2.0::api::ModPerl::Global/C_special_list_call_>>
515
C<L<special_list_clear|docs::2.0::api::ModPerl::Global/C_special_list_clear_>>,
516
internally used by registry handlers, can be used to run C<END> blocks
228
520
=head2 Request-localized Globals
230
522
mod_perl 2.0 provides two types of C<SetHandler> handlers:
270
564
You can still call C<CORE::exit> to kill the interpreter, again if you
271
565
know what you are doing.
567
One caveat is when C<exit> is called inside C<eval> -- L<the
569
documentation|docs::2.0::api::ModPerl::Util/C_exit_> explains how to
570
deal with this situation.
577
=head1 C<ModPerl::Registry> Handlers Family
579
=head2 A Look Behind the Scenes
581
If you have a CGI script F<test.pl>:
584
print "Content-type: text/plain\n\n";
587
a typical registry family handler turns it into something like:
591
local $0 = "/full/path/to/test.pl";
594
print "Content-type: text/plain\n\n";
598
Turning it into an almost full-fledged mod_perl handler. The only
599
difference is that it handles the return status for you. (META: more
600
details on return status needed.)
602
It then executes it as:
604
foo_bar_baz::handler($r);
606
passing the C<L<$r|docs::2.0::api::Apache::RequestRec>> object as the
607
only argument to the C<handler()> function.
609
Depending on the used registry handler the package is made of the file
610
path, the uri or anything else. Check the handler's documentation to
611
learn which method is used.
615
=head2 Getting the C<$r> Object
617
As explained in L<A Look Behind the Scenes|/A_Look_Behind_the_Scenes>
618
the C<$r> object is always passed to the registry script's special
619
function C<handler> as the first and the only argument, so you can get
620
this object by accessing C<@_>, since:
623
print "Content-type: text/plain\n\n";
630
print "Content-type: text/plain\n\n";
634
behind the scenes. Now you can use C<$r> to call various mod_perl
635
methods, e.g. rewriting the script as:
638
$r->content_type('text/plain');
641
If you are deep inside some code and can't get to the entry point to
642
reach for C<$r>, you can use
643
C<L<Apache-E<gt>request|docs::2.0::api::Apache::RequestUtil/C_request_>>.
274
656
=head1 Threads Coding Issues Under mod_perl
added
removed
docs/user/coding/coding.pod
