stas 2004/06/06 03:11:45
Modified: src/docs/2.0/user/handlers filters.pod http.pod server.pod
Log:
syncing docs with reality
Revision Changes Path
1.43 +4 -4 modperl-docs/src/docs/2.0/user/handlers/filters.pod
Index: filters.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/filters.pod,v
retrieving revision 1.42
retrieving revision 1.43
diff -u -u -r1.42 -r1.43
--- filters.pod 4 Jun 2004 09:30:38 -0000 1.42
+++ filters.pod 6 Jun 2004 10:11:44 -0000 1.43
@@ -1771,7 +1771,7 @@
}
my $data = $b->read;
- $b = APR::Bucket->new(lc $data) if $data;
+ $b = APR::Bucket->new(lc $data) if length $data;
$bb->insert_tail($b);
}
@@ -2108,8 +2108,7 @@
sub handler : FilterRequestHandler {
my($f, $bb) = @_;
- my $c = $f->c;
- my $bb_ctx = APR::Brigade->new($c->pool, $c->bucket_alloc);
+ my $bb_ctx = APR::Brigade->new($f->c->pool, $f->c->bucket_alloc);
while (!$bb->is_empty) {
my $bucket = $bb->first;
@@ -2121,7 +2120,8 @@
last;
}
- if (my $data = $bucket->read) {
+ my $data = $bucket->read;
+ if (length $data) {
$data = join "",
map {scalar(reverse $_), "\n"} split "\n", $data;
$bucket = APR::Bucket->new($data);
1.33 +64 -25 modperl-docs/src/docs/2.0/user/handlers/http.pod
Index: http.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -u -r1.32 -r1.33
--- http.pod 7 May 2004 22:11:59 -0000 1.32
+++ http.pod 6 Jun 2004 10:11:44 -0000 1.33
@@ -53,11 +53,28 @@
Those familiar with mod_perl 1.0 will find the HTTP request cycle in
mod_perl 2.0 to be almost identical to the mod_perl 1.0's model. The
-only difference is in the I<response> phase which now includes
-filtering. Also the C<PerlHandler> directive has been renamed to
+different things are:
+
+=over
+
+=item *
+
+a new directive C<L<PerlMapToStorageHandler|/PerlMapToStorageHandler>>
+was added to match the new phase I<map_to_storage> added by Apache
+2.0.
+
+=item *
+
+the C<PerlHandler> directive has been renamed to
C<PerlResponseHandler> to better match the corresponding Apache phase
name (I<response>).
+=item *
+
+the I<response> phase now includes filtering.
+
+=back
+
The following diagram depicts the HTTP request life cycle and
highlights which handlers are available to mod_perl 2.0:
@@ -66,7 +83,7 @@
align="middle" alt="HTTP cycle"><br><br>
From the diagram it can be seen that an HTTP request is processes by
-11 phases, executed in the following order:
+12 phases, executed in the following order:
=over
@@ -106,7 +123,8 @@
connection input filters if any. Similarly the generated response is
first run through request output filters and eventually through
connection output filters before it's sent to the client. We will talk
-about filters in detail later in this chapter.
+about filters in detail later in L<the dedicated to filters
+chapter|docs::2.0::user::handlers::filters>.
Before discussing each handler in detail remember that if you use
L<the stacked handlers
@@ -144,15 +162,16 @@
use warnings;
use Apache::ServerUtil ();
+ use Apache::RequestIO ();
use File::Spec::Functions qw(catfile);
my $r = shift;
$r->content_type('text/plain');
- my $conf_file = catfile Apache::Server::server_root_relative($r->pool,
'conf'),
- "httpd.conf";
+ my $conf_file = catfile $r->server_root_relative,
+ "conf", "httpd.conf";
- printf "$conf_file is %0.2f minutes old", 60*24*(-M $conf_file);
+ printf "$conf_file is %0.2f minutes old\n", 60*24*(-M $conf_file);
This registry script is supposed to print when the last time
I<httpd.conf> has been modified, compared to the start of the request
@@ -269,7 +288,7 @@
sub handler {
my $r = shift;
- my ($date, $id, $page) = $r->uri =~ m|^/news/(\d+)/(\d+)/(.*)|;
+ my($date, $id, $page) = $r->uri =~ m|^/news/(\d+)/(\d+)/(.*)|;
$r->uri("/perl/news.pl");
$r->args("date=$date&id=$id&page=$page");
@@ -367,6 +386,7 @@
use Apache::RequestRec ();
use Apache::RequestIO ();
use Apache::RequestUtil ();
+ use APR::Table ();
use Apache::Const -compile => qw(DECLINED OK);
@@ -378,7 +398,7 @@
return Apache::DECLINED unless $r->method eq METHOD;
- Apache::Server::method_register($r->pool, METHOD);
+ Apache::method_register($r->pool, METHOD);
$r->handler("perl-script");
$r->push_handlers(PerlResponseHandler => \&send_email_handler);
@@ -398,27 +418,43 @@
return Apache::OK;
}
+ use APR::Brigade ();
+ use APR::Bucket ();
+
+ use Apache::Const -compile => qw(MODE_READBYTES);
+ use APR::Const -compile => qw(SUCCESS BLOCK_READ);
+
+ use constant IOBUFSIZE => 8192;
+
sub content {
my $r = shift;
- $r->setup_client_block;
- return '' unless $r->should_client_block;
- my $len = $r->headers_in->get('content-length');
- my $buf;
- $r->get_client_block($buf, $len);
+ my $bb = APR::Brigade->new($r->pool, $r->connection->bucket_alloc);
- return $buf;
- }
+ my $data = '';
+ my $seen_eos = 0;
+ do {
+ $r->input_filters->get_brigade($bb,
+ Apache::MODE_READBYTES, APR::BLOCK_READ, IOBUFSIZE);
+
+ while (!$bb->is_empty) {
+ my $b = $bb->first;
+ $b->remove;
+
+ if ($b->is_eos) {
+ $seen_eos++;
+ last;
+ }
+
+ my $buf = $b->read;
+ $data .= $buf if length $buf;
+ }
- sub send_email {
- my($rh_headers, $r_body) = @_;
+ } while (!$seen_eos);
- require MIME::Lite;
- MIME::Lite->send("smtp", SMTP_HOSTNAME, Timeout => 60);
+ $bb->destroy;
- my $msg = MIME::Lite->new(%$rh_headers, Data => $$r_body);
- #warn $msg->as_string;
- $msg->send;
+ return $data;
}
1;
@@ -970,6 +1006,7 @@
use Apache::RequestIO ();
use Apache::RequestRec ();
+ use Apache::RequestUtil ();
use Apache::Const -compile => 'OK';
@@ -1131,6 +1168,8 @@
sub handler {
package MyApache::Deparse;
+ use warnings;
+ use strict 'refs';
my $r = shift @_;
$r->content_type('text/plain');
$r->print('sub handler ', 'B::Deparse'->new->coderef2text(\&handler));
@@ -1189,8 +1228,8 @@
$r->connection->remote_ip, scalar(localtime),
$r->uri, $r->status, $r->bytes_sent;
- my $log_path = Apache::Server::server_root_relative($r->pool,
- "logs/$username.log");
+ my $log_path = join '/', $r->server_root_relative,
+ "logs", "$username.log";
open my $fh, ">>$log_path" or die "can't open $log_path: $!";
flock $fh, LOCK_EX;
print $fh $entry;
1.15 +68 -23 modperl-docs/src/docs/2.0/user/handlers/server.pod
Index: server.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/server.pod,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -u -r1.14 -r1.15
--- server.pod 10 May 2004 07:13:29 -0000 1.14
+++ server.pod 6 Jun 2004 10:11:44 -0000 1.15
@@ -42,6 +42,12 @@
From that moment on each working thread processes connections until
it's killed by the server or the server is shutdown.
+
+
+
+
+
+
=head2 Startup Phases Demonstration Module
Let's look at the following example that demonstrates all the startup
@@ -67,7 +73,7 @@
sub open_logs {
my($conf_pool, $log_pool, $temp_pool, $s) = @_;
- my $log_path = Apache::Server::server_root_relative($conf_pool,
$log_file);
+ my $log_path = $s->server_root_relative($log_file);
$s->warn("opening the log file: $log_path");
open $log_fh, ">>$log_path" or die "can't open $log_path: $!";
@@ -109,13 +115,15 @@
}
}
+ my $parent_pid = $$;
END {
- say("process $$ is shutdown\n");
+ my $msg = "process $$ is shutdown";
+ $msg .= "\n". "-" x 20 if $$ == $parent_pid;
+ say($msg);
}
1;
-
And the I<httpd.conf> configuration section:
<IfModule prefork.c>
@@ -142,34 +150,48 @@
the following is getting logged to I<logs/startup_log>:
- [Thu May 29 13:11:08 2003] - open_logs : process 21823 is born to
reproduce
- [Thu May 29 13:11:08 2003] - post_config: configuration is completed
- [Thu May 29 13:11:09 2003] - END : process 21823 is shutdown
-
- [Thu May 29 13:11:10 2003] - open_logs : process 21825 is born to
reproduce
- [Thu May 29 13:11:10 2003] - post_config: configuration is completed
- [Thu May 29 13:11:11 2003] - child_init : process 21830 is born to serve
- [Thu May 29 13:11:11 2003] - child_init : process 21831 is born to serve
- [Thu May 29 13:11:11 2003] - child_init : process 21832 is born to serve
- [Thu May 29 13:11:11 2003] - child_init : process 21833 is born to serve
- [Thu May 29 13:11:12 2003] - child_exit : process 21833 now exits
- [Thu May 29 13:11:12 2003] - child_exit : process 21832 now exits
- [Thu May 29 13:11:12 2003] - child_exit : process 21831 now exits
- [Thu May 29 13:11:12 2003] - child_exit : process 21830 now exits
- [Thu May 29 13:11:12 2003] - END : process 21825 is shutdown
+ [Sun Jun 6 01:50:06 2004] - open_logs : process 24189 is born to
reproduce
+ [Sun Jun 6 01:50:06 2004] - post_config: configuration is completed
+ [Sun Jun 6 01:50:07 2004] - END : process 24189 is shutdown
+ --------------------
+ [Sun Jun 6 01:50:08 2004] - open_logs : process 24190 is born to
reproduce
+ [Sun Jun 6 01:50:08 2004] - post_config: configuration is completed
+ [Sun Jun 6 01:50:09 2004] - child_init : process 24192 is born to serve
+ [Sun Jun 6 01:50:09 2004] - child_init : process 24193 is born to serve
+ [Sun Jun 6 01:50:09 2004] - child_init : process 24194 is born to serve
+ [Sun Jun 6 01:50:09 2004] - child_init : process 24195 is born to serve
+ [Sun Jun 6 01:50:10 2004] - child_exit : process 24193 now exits
+ [Sun Jun 6 01:50:10 2004] - END : process 24193 is shutdown
+ [Sun Jun 6 01:50:10 2004] - child_exit : process 24194 now exits
+ [Sun Jun 6 01:50:10 2004] - END : process 24194 is shutdown
+ [Sun Jun 6 01:50:10 2004] - child_exit : process 24195 now exits
+ [Sun Jun 6 01:50:10 2004] - child_exit : process 24192 now exits
+ [Sun Jun 6 01:50:10 2004] - END : process 24192 is shutdown
+ [Sun Jun 6 01:50:10 2004] - END : process 24195 is shutdown
+ [Sun Jun 6 01:50:10 2004] - END : process 24190 is shutdown
+ --------------------
First of all, we can clearly see that Apache always restart itself
after the first I<post_config> phase is over. The logs show that the
-I<post_config> phase is preceded by the I<open_logs> phase. Only
-after Apache has restarted itself and has completed the I<open_logs>
-and I<post_config> phase again the I<child_init> phase is run for each
+I<post_config> phase is preceded by the I<open_logs> phase. Only after
+Apache has restarted itself and has completed the I<open_logs> and
+I<post_config> phase again, the I<child_init> phase is run for each
child process. In our example we have had the setting
C<StartServers=4>, therefore you can see four child processes were
started.
Finally you can see that on server shutdown, the I<child_exit> phase
is run for each child process and the C<END {}> block is executed by
-the parent process only.
+the parent process and each of the child processes. This is because
+that C<END> block was inherited from the parent on fork.
+
+However the presented behavior varies from MPM to MPM. This
+demonstration was performed using prefork mpm. Other MPMs like winnt,
+may run I<open_logs> and I<post_config> more than once. Also the END
+blocks may be run more times, when threads are involved. You should be
+very careful when designing features relying on the phases covered in
+this chapter if you plan support multiple MPMs. The only thing that's
+sure is that you will have each of these phases run at least once.
Apache also specifies the I<pre_config> phase, which is executed
before the configuration files are parsed, but this is of no use to
@@ -179,6 +201,11 @@
Now let's discuss each of the mentioned startup handlers and their
implementation in the C<MyApache::StartupLog> module in detail.
+
+
+
+
+
=head2 PerlOpenLogsHandler
The I<open_logs> phase happens just before the I<post_config> phase.
@@ -205,7 +232,7 @@
sub open_logs {
my($conf_pool, $log_pool, $temp_pool, $s) = @_;
- my $log_path = Apache::Server::server_root_relative($conf_pool,
$log_file);
+ my $log_path = $s->server_root_relative($log_file);
$s->warn("opening the log file: $log_path");
open $log_fh, ">>$log_path" or die "can't open $log_path: $!";
@@ -274,6 +301,11 @@
=back
+
+
+
+
+
=head2 PerlPostConfigHandler
The I<post_config> phase happens right after Apache has processed the
@@ -315,6 +347,14 @@
C<L<PerlOpenLogsHandler|/PerlOpenLogsHandler>> identically applies to
this handler.
+
+
+
+
+
+
+
+
=head2 PerlChildInitHandler
The I<child_init> phase happens immediately after the child process is
@@ -349,6 +389,11 @@
I<httpd.conf>:
PerlChildInitHandler MyApache::StartupLog::child_init
+
+
+
+
+
=head2 PerlChildExitHandler
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
