perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/user/handlers http.pod
Date Fri, 07 May 2004 22:11:59 GMT
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, \@args);
  +  }
  +  
  +  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: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message