stas 2004/05/07 15:11:59
Modified: src/docs/2.0/api/ModPerl PerlRun.pod Registry.pod
src/docs/2.0/user/coding coding.pod
src/docs/2.0/user/handlers http.pod
Log:
- how to do cleanups
- special blocks
- exit updates
Revision Changes Path
1.2 +65 -5 modperl-docs/src/docs/2.0/api/ModPerl/PerlRun.pod
Index: PerlRun.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/ModPerl/PerlRun.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -u -r1.1 -r1.2
--- PerlRun.pod 27 Jan 2003 04:05:12 -0000 1.1
+++ PerlRun.pod 7 May 2004 22:11:59 -0000 1.2
@@ -2,18 +2,78 @@
ModPerl::PerlRun - Run unaltered CGI scripts under mod_perl
-=head1 SYNOPSIS
+=head1 Synopsis
-=head1 DESCRIPTION
+ # httpd.conf
+ PerlModule ModPerl::PerlRun
+ Alias /perl-run/ /home/httpd/perl/
+ <Location /perl-run>
+ SetHandler perl-script
+ PerlResponseHandler ModPerl::PerlRun
+ PerlOptions +ParseHeaders
+ Options +ExecCGI
+ </Location>
-=head1 AUTHORS
+
+=head1 Description
+
+
+
+
+=head1 Special Blocks
+
+
+=head2 C<BEGIN> Blocks
+
+When running under the C<ModPerl::PerlRun> handler C<BEGIN> blocks
+behave as follows:
+
+=over
+
+=item *
+
+C<BEGIN> blocks defined in scripts running under the
+C<ModPerl::PerlRun> handler are executed on each and every request.
+
+=item *
+
+C<BEGIN> blocks defined in modules loaded from scripts running under
+C<ModPerl::PerlRun> (and which weren't already loaded prior to the
+request) are executed on each and every request only if those modules
+declare no package. If a package is declared C<BEGIN> blocks will be
+run only the first time each module is loaded, since those modules
+don't get reloaded on subsequent requests.
+
+=back
+
+See also L<C<BEGIN> blocks in mod_perl
+handlers|docs::2.0::user::coding::coding/C_BEGIN__Blocks>.
+
+
+=head2 C<CHECK> and C<INIT> Blocks
+
+Same as normal L<mod_perl
+handlers|docs::2.0::user::coding::coding/C_CHECK__and_C_INIT__Blocks>.
+
+
+
+=head2 C<END> Blocks
+
+Same as
+C<L<ModPerl::Registry|docs::2.0::api::ModPerl::Registry/C_BEGIN__Blocks>>.
+
+
+=head1 Authors
Doug MacEachern
Stas Bekman
-=head1 SEE ALSO
-ModPerl::RegistryCooker(3), Apache(3), mod_perl(3)
+
+=head1 See Also
+
+C<L<ModPerl::RegistryCooker|docs::2.0::api::ModPerl::RegistryCooker>>
+and C<L<ModPerl::Registry|docs::2.0::api::ModPerl::Registry>>.
=cut
1.5 +60 -6 modperl-docs/src/docs/2.0/api/ModPerl/Registry.pod
Index: Registry.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/ModPerl/Registry.pod,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -u -r1.4 -r1.5
--- Registry.pod 3 Mar 2004 23:33:52 -0000 1.4
+++ Registry.pod 7 May 2004 22:11:59 -0000 1.5
@@ -62,10 +62,65 @@
of many Perl modules, this difference should be noticeable to the
human eye.
+
+
+=head1 Special Blocks
+
+
+=head2 C<BEGIN> Blocks
+
+C<BEGIN> blocks defined in scripts running under the
+C<ModPerl::Registry> handler behave similarly to the normal L<mod_perl
+handlers|docs::2.0::user::coding::coding/C_BEGIN__Blocks> plus:
+
+=over
+
+=item *
+
+Only once, if pulled in by the parent process via
+C<Apache::RegistryLoader>.
+
+=item *
+
+An additional time, once per child process or Perl interpreter, each
+time the script file changes on disk.
+
+=back
+
+C<BEGIN> blocks defined in modules loaded from C<ModPerl::Registry>
+scripts behave identically to the normal L<mod_perl
+handlers|docs::2.0::user::coding::coding/C_BEGIN__Blocks>, regardless
+of whether they define a package or not.
+
+
+
+=head2 C<CHECK> and C<INIT> Blocks
+
+Same as normal L<mod_perl
+handlers|docs::2.0::user::coding::coding/C_CHECK__and_C_INIT__Blocks>.
+
+
+
+=head2 C<END> Blocks
+
+C<END> blocks encountered during compilation of a script, are called
+after the script has completed its run, including subsequent
+invocations when the script is cached in memory. This is assuming that
+the script itself doesn't define a package on its own. If the script
+defines its own package, the C<END> blocks in the scope of that
+package will be executed at the end of the interpretor's life.
+
+C<END> blocks residing in modules loaded by registry script will be
+executed only once, when the interpreter exits.
+
+
+
=head1 Security
-ModPerl::Registry::handler will preform the same checks as mod_cgi
-before running the script.
+C<ModPerl::Registry::handler> performs the same sanity checks as
+mod_cgi does, before running the script.
+
+
=head1 Environment
@@ -106,8 +161,6 @@
"always use C<-w>, always use C<-w> and 'use strict'".
This is more important here than anywhere else!
-Your scripts cannot contain the __END__ or __DATA__ token to terminate
-compilation. (META: works in 2.0).
=head1 Authors
@@ -116,7 +169,8 @@
=head1 See Also
-C<L<ModPerl::RegistryCooker>>, C<L<ModPerl::RegistryBB>>,
-C<L<ModPerl::PerlRun>>, Apache(3), mod_perl(3)
+C<L<ModPerl::RegistryCooker|docs::2.0::api::ModPerl::RegistryCooker>>,
+C<L<ModPerl::RegistryBB|docs::2.0::api::ModPerl::RegistryBB>> and
+C<L<ModPerl::PerlRun|docs::2.0::api::ModPerl::PerlRun>>.
=cut
1.32 +186 -5 modperl-docs/src/docs/2.0/user/coding/coding.pod
Index: coding.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/coding/coding.pod,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -u -r1.31 -r1.32
--- coding.pod 3 Mar 2004 23:33:52 -0000 1.31
+++ coding.pod 7 May 2004 22:11:59 -0000 1.32
@@ -20,7 +20,11 @@
be used to find out which modules need to be used.
-=head1 Method Handlers
+=head1 Techniques
+
+
+
+=head2 Method Handlers
In mod_perl 2.0 method handlers are declared using the C<method>
attribute:
@@ -45,6 +49,69 @@
|docs::2.0::user::porting::compat/Method_Handlers>.
+=head2 Cleaning up
+
+It's possible to arrange for cleanups to happen at the end of various
+phases. One can't rely on C<END> blocks to do the job, since these
+L<don't get executed|/C_END__Blocks> until the interpreter quits, with
+an exception to the
+L<Registry|docs::2.0::api::ModPerl::Registry/C_END__Blocks> handlers.
+
+Module authors needing to run cleanups after each HTTP request, should
+use
+C<L<PerlCleanupHandler|docs::2.0::user::handlers::http/PerlCleanupHandler>>.
+
+Module authors needing to run cleanups at other times can always
+register a cleanup callback via
+C<L<cleanup_register|docs::2.0::api::APR::Pool/C_cleanup_register_>>
+on the pool object of choice. Here are some examples of its usage:
+
+To run something at the server shutdown and restart use
+C<$s-E<gt>pool-E<gt>cleanup_register()> in F<startup.pl>:
+
+ #PerlRequire startup.pl
+ use Apache::ServerUtil ();
+ use APR::Pool ();
+
+ warn "parent pid is $$\n";
+ my $pool = Apache->server->pool;
+ $pool->cleanup_register(\&cleanup);
+ sub cleanup { warn "server cleanup in $$\n" }
+
+This is usually useful when some server-wide cleanup should be
+performed when the server is stopped or restarted.
+
+To run a cleanup at the end of each connection phase, assign a cleanup
+callback to the connection pool object:
+
+ use Apache::Connection ();
+ use APR::Pool ();
+
+ my $pool = $c->pool;
+ $pool->cleanup_register(\&my_cleanup);
+ sub my_cleanup { ... }
+
+You can also create your own pool object, register a cleanup callback
+and it'll be called when the object is destroyed:
+
+ use APR::Pool ();
+
+ {
+ my @args = 1..3;
+ my $pool = APR::Pool->new;
+ $pool->cleanup_register(\&cleanup, [EMAIL PROTECTED]);
+ }
+
+ sub cleanup {
+ my @args = @{ +shift };
+ warn "cleanup was called with args: @args";
+ }
+
+In this example the cleanup callback gets called, when C<$pool> goes
+out of scope and gets destroyed. This is very similar to OO C<DESTROY>
+method.
+
+
=head1 Goodies Toolkit
=head2 Environment Variables
@@ -345,6 +412,111 @@
+=head2 C<BEGIN> Blocks
+
+Perl executes C<BEGIN> blocks as soon as possible, at the time of
+compiling the code. The same is true under mod_perl. However, since
+mod_perl normally only compiles scripts and modules once, either in
+the parent server (at the server startup) or once per-child (on the
+first request using a module), C<BEGIN> blocks in that code will only
+be run once. As the C<perlmod> manpage explains, once a C<BEGIN>
+block has run, it is immediately undefined. In the mod_perl
+environment, this means that C<BEGIN> blocks will not be run during
+the response to an incoming request unless that request happens to be
+the one that causes the compilation of the code, i.e. if it wasn't
+loaded yet.
+
+C<BEGIN> blocks in modules and files pulled in via C<require()> or
+C<use()> will be executed:
+
+=over 4
+
+=item *
+
+Only once, if pulled in by the parent process at the server startup.
+
+=item *
+
+Once per each child process or Perl interpreter if not pulled in by
+the parent process.
+
+=item *
+
+An additional time, once per each child process or Perl interpreter if
+the module is reloaded off disk again via
+C<L<Apache::Reload|docs::2.0::api::Apache::Reload>>.
+
+=item *
+
+Unpredictable if you fiddle with C<%INC> yourself.
+
+=back
+
+The C<BEGIN> blocks behavior is different in
+C<L<ModPerl::Registry|docs::2.0::api::ModPerl::Registry/C_BEGIN__Blocks>>
+and
+C<L<ModPerl::PerlRun|docs::2.0::api::ModPerl::PerlRun/C_BEGIN__Blocks>>
+handlers, and their subclasses.
+
+
+
+
+
+=head2 C<CHECK> and C<INIT> Blocks
+
+C<CHECK> and C<INIT> blocks run when the source code compilation is
+complete, but before the program starts. C<CHECK> can mean
+"checkpoint" or "double-check" or even just "stop". C<INIT> stands for
+"initialization". The difference is subtle; C<CHECK> blocks are run
+just after the compilation ends, C<INIT> just before the runtime
+begins. (Hence the C<-c> command-line perl option runs C<CHECK> blocks
+but not C<INIT> blocks.)
+
+Perl only calls these blocks during I<perl_parse()>, which mod_perl
+calls once at startup time. Under threaded mpm, these blocks will be
+called once per C<L<parent perl interpreter
+startup|docs::2.0::user::config::config/C_Parent_>>. Therefore
+C<CHECK> and C<INIT> blocks don't work after the server is started,
+for the same reason these code samples don't work:
+
+ % perl -e 'eval qq(CHECK { print "ok\n" })'
+ % perl -e 'eval qq(INIT { print "ok\n" })'
+
+
+
+
+=head2 C<END> Blocks
+
+As the C<perlmod> manpage explains, an C<END> block is executed as
+late as possible, that is, when the interpreter exits. So for example
+mod_cgi will run its C<END> blocks on each invocation, since on every
+invocation it starts a new interpreter and then kills it when the
+request processing is done.
+
+In the mod_perl environment, the interpreter does not exit after
+serving a single request (unless it is configured to do so) and hence
+it will run its C<END> blocks only when it exits, which usually
+happens during the server shutdown, but may also happen earlier than
+that (e.g. a process exits because it has served a
+C<MaxRequestsPerChild> number of requests).
+
+mod_perl does L<make a special
+case|docs::2.0::api::ModPerl::Registry/C_END__Blocks>
+for scripts running under
+C<L<ModPerl::Registry|docs::2.0::api::ModPerl::Registry>> and friends.
+
+The L<Cleaning up|/Cleaning_up> section explains how to deal with
+cleanups for non-Registry handlers.
+
+C<L<ModPerl::Global|docs::2.0::api::ModPerl::Global>> API:
+C<L<special_list_register|docs::2.0::api::ModPerl::Global/C_special_list_register_>>,
+C<L<special_list_call|docs::2.0::api::ModPerl::Global/C_special_list_call_>>
+and
+C<L<special_list_clear|docs::2.0::api::ModPerl::Global/C_special_list_clear_>>,
+internally used by registry handlers, can be used to run C<END> blocks
+at arbitrary times.
+
+
=head2 Request-localized Globals
mod_perl 2.0 provides two types of C<SetHandler> handlers:
@@ -370,7 +542,9 @@
localize all special Perl variables so the local changes won't affect
other handlers.
-=head2 exit()
+
+
+=head2 C<exit>
In the normal Perl code exit() is used to stop the program flow and
exit the Perl interpreter. However under mod_perl we only want the
@@ -378,9 +552,9 @@
You should take no action if your code includes exit() calls and it's
OK to continue using them. mod_perl worries to override the exit()
-function with its own version which stops the program flow, and
-performs all the necessary cleanups, but doesn't kill the server. This
-is done by overriding:
+function with L<its own version|docs::2.0::api::ModPerl::Util/C_exit_>
+which stops the program flow, and performs all the necessary cleanups,
+but doesn't kill the server. This is done by overriding:
*CORE::GLOBAL::exit = \&ModPerl::Util::exit;
@@ -389,6 +563,13 @@
You can still call C<CORE::exit> to kill the interpreter, again if you
know what you are doing.
+
+One caveat is when C<exit> is called inside C<eval> -- L<the
+ModPerl::Util::exit
+documentation|docs::2.0::api::ModPerl::Util/C_exit_> explains how to
+deal with this situation.
+
+
1.32 +4 -2 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.31
retrieving revision 1.32
diff -u -u -r1.31 -r1.32
--- http.pod 4 Mar 2004 03:00:29 -0000 1.31
+++ http.pod 7 May 2004 22:11:59 -0000 1.32
@@ -1300,8 +1300,10 @@
=item 2 Using C<cleanup_register()> acting on the request object's pool
Since a request object pool is destroyed at the end of each request,
-we can register a cleanup callback which will be executed just before
-the pool is destroyed. For example:
+we can use
+C<L<cleanup_register|docs::2.0::api::APR::Pool/C_cleanup_register_>>
+to register a cleanup callback which will be executed just before the
+pool is destroyed. For example:
$r->pool->cleanup_register(\&cleanup, $arg);
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
