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/intro overview.pod start_fast.pod
Date Mon, 27 Jan 2003 04:05:13 GMT
stas        2003/01/26 20:05:13

  Modified:    src/docs/2.0/api config.cfg
               src/docs/2.0/user/compat compat.pod
               src/docs/2.0/user/config custom.pod
               src/docs/2.0/user/handlers http.pod
               src/docs/2.0/user/intro overview.pod start_fast.pod
  Added:       src/docs/2.0/api/APR PerlIO.pod Table.pod
               src/docs/2.0/api/Apache Log.pod Reload.pod RequestRec.pod
                        ServerUtil.pod SubProcess.pod compat.pod
               src/docs/2.0/api/ModPerl PerlRun.pod Registry.pod
                        RegistryBB.pod RegistryCooker.pod
                        RegistryLoader.pod
  Removed:     src/docs/2.0/api/ModPerl-Registry/ModPerl PerlRun.pod
                        Registry.pod RegistryBB.pod RegistryCooker.pod
                        RegistryLoader.pod
               src/docs/2.0/api/mod_perl-2.0 .cvsignore Makefile.PL
               src/docs/2.0/api/mod_perl-2.0/APR PerlIO.pod Table.pod
               src/docs/2.0/api/mod_perl-2.0/Apache Log.pod Reload.pod
                        RequestRec.pod ServerUtil.pod SubProcess.pod
                        compat.pod
  Log:
  drop the extra sub-dirs ModPerl-Registry and mod_perl-2.0, we can control
  what goes where programmatically if needed. In any case registry is a part
  of the core
  
  Revision  Changes    Path
  1.12      +13 -13    modperl-docs/src/docs/2.0/api/config.cfg
  
  Index: config.cfg
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/config.cfg,v
  retrieving revision 1.11
  retrieving revision 1.12
  diff -u -r1.11 -r1.12
  --- config.cfg	8 Nov 2002 04:10:36 -0000	1.11
  +++ config.cfg	27 Jan 2003 04:05:12 -0000	1.12
  @@ -15,27 +15,27 @@
   
       group    => 'Apache::',
       chapters => [qw(
  -        mod_perl-2.0/Apache/Log.pod
  -        mod_perl-2.0/Apache/Reload.pod
  -        mod_perl-2.0/Apache/RequestRec.pod
  -        mod_perl-2.0/Apache/ServerUtil.pod
  -        mod_perl-2.0/Apache/SubProcess.pod
  -        mod_perl-2.0/Apache/compat.pod
  +        Apache/Log.pod
  +        Apache/Reload.pod
  +        Apache/RequestRec.pod
  +        Apache/ServerUtil.pod
  +        Apache/SubProcess.pod
  +        Apache/compat.pod
       )],
   
       group    => 'APR::',
       chapters => [qw(
  -        mod_perl-2.0/APR/PerlIO.pod
  -        mod_perl-2.0/APR/Table.pod
  +        APR/PerlIO.pod
  +        APR/Table.pod
       )],
   
       group    => 'ModPerl::',
       chapters => [qw(
  -        ModPerl-Registry/ModPerl/PerlRun.pod
  -        ModPerl-Registry/ModPerl/Registry.pod
  -        ModPerl-Registry/ModPerl/RegistryBB.pod
  -        ModPerl-Registry/ModPerl/RegistryCooker.pod
  -        ModPerl-Registry/ModPerl/RegistryLoader.pod
  +        ModPerl/PerlRun.pod
  +        ModPerl/Registry.pod
  +        ModPerl/RegistryBB.pod
  +        ModPerl/RegistryCooker.pod
  +        ModPerl/RegistryLoader.pod
       )],
   
   
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/APR/PerlIO.pod
  
  Index: PerlIO.pod
  ===================================================================
  =head1 NAME
  
  APR:PerlIO -- An APR Perl IO layer
  
  =head1 SYNOPSIS
  
    use APR::PerlIO ();
    
    sub handler {
        my $r = shift;
    
        open my $fh, ">:APR", $filename, $r or die $!;
        # work with $fh as normal $fh
        close $fh;
    
        return Apache::OK;
    }
  
  =head1 DESCRIPTION
  
  C<APR::PerlIO> implements a Perl IO layer using APR's file
  manipulation as its internals.
  
  Why do you want to use this? Normally you shouldn't, probably it won't
  be faster than Perl's default layer. It's only useful when you need to
  manipulate a filehandle opened at the APR side, while using Perl.
  
  Normally you won't call open() with APR layer attribute, but some
  mod_perl functions will return a filehandle which is internally hooked
  to APR. But you can use APR Perl IO directly if you want.
  
  =head1 METHODS
  
  Perl Interface:
  
  =over
  
  =item open()
  
  To use APR Perl IO to open a file the four arguments open() should be
  used. For example:
  
    open my $fh, ">:APR", $filename, $r or die $!;
  
  where:
  
  the second argument is the mode to open the file, constructed from two
  sections separated by the C<:> character: the first section is the
  mode to open the file under (E<gt>, E<lt>, etc) and the second section
  must be a string I<APR>.
  
  the fourth argument can be a C<Apache::RequestRec> or
  C<Apache::ServerRec> object.
  
  the rest of the arguments are the same as described by the I<open()>
  manpage.
  
  =item seek()
  
    seek($fh, $offset, $whence);
  
  If C<$offset> is zero, C<seek()> works normally.
  
  However if C<$offset> is non-zero and Perl has been compiled with with
  large files support (C<-Duselargefiles>), whereas APR wasn't, this
  function will croak. This is because largefile size C<Off_t> simply
  cannot fit into a non-largefile size C<apr_off_t>.
  
  To solve the problem, rebuild Perl with C<-Uuselargefiles>. Currently
  there is no way to force APR to build with large files support.
  
  =back
  
  The C interface provides functions to convert between Perl IO and
  APR Perl IO filehandles.
  
  =head1 SEE ALSO
  
  The I<perliol(1)>, I<perlapio(1)> and I<perl(1)> manpages.
  
  =cut
  
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/APR/Table.pod
  
  Index: Table.pod
  ===================================================================
  =head1 NAME
  
  APR::Table -- A Perl API for manipulating opaque string-content table
  
  =head1 SYNOPSIS
  
    use APR::Table;
    
    $table = make($pool, $nelts);
    $table_copy = $table->copy($pool);
    
    $table->clear();
    
    $table->set($key => $val);
    $table->unset($key);
    $table->add($key, $val);
    
    $val = $table->get($key);
    @val = $table->get($key);
    
    $table->merge($key => $val);
    overlap($table_a, $table_b, $flags);
    $new_table = overlay($table_base, $table_overlay, $pool);
    
    $table->do(sub {print "key $_[0], value $_[1]\n"}, @valid_keys);
    
    #Tied Interface
    $value = $table->{$key};
    $table->{$key} = $value;
    $table->{$key} = $value;
    exists $table->{$key};
    
    foreach my $key (keys %{$table}) {
        print "$key = $table->{$key}\n";
    }
  
  =head1 DESCRIPTION
  
  C<APR::Table> allows its users to manipulate opaque string-content
  tables.
  
  The table's structure is somewhat similar to the Perl's hash
  structure, but allows multiply values for the same key.  An access to
  the records stored in the table always requires a key.
  
  The key-value pairs are stored in the order they are added.
  
  The keys are case-insensitive.
  
  However as of the current implementation if more than value for the
  same key is requested, the whole table is lineary searched, which is
  very inefficient unless the table is very small.
  
  C<APR::Table> provides a L<TIE Interface|/TIE_Interface>.
  
  See I<apr/include/apr_tables.h> in ASF's I<apr> project for low level
  details.
  
  =head1 API
  
  The variables used in the API definition have the following
  I<"types">:
  
  =over
  
  =item * APR::Table
  
  C<$table_*>
  
  =item * APR::Pool
  
  C<$pool>
  
  =item * scalars: unsigned integers only (SVIV) (as C expects them)
  
  C<$nelts>, C<$flags>
  
  =item * scalars: (numerical (SVIV/SVNV) and strings (SVPV))
  
  C<$key>, C<$val>
  
  =back
  
  Function arguments (if any) and return values are shown in the
  function's synopsis.
  
  =over
  
  =item * make()
  
    $table = make($pool, $nelts);
  
  Make a new table.
  
  param C<$pool>: The pool to allocate the pool out of.
  
  param C<$nelts>: The number of elements in the initial table.
  
  return: a new table.
  
  warning: This table can only store text data
  
  =item * copy()
  
    $table_copy = $table->copy($pool);
  
  Create a new table and copy another table into it
  
  param C<$pool>: The pool to allocate the new table out of
  
  param C<$table>: The table to copy
  
  return: A copy of the table passed in
  
  =item * clear()
  
    $table->clear();
  
  Delete all of the elements from a table.
  
  param C<$table>: A copy of the table passed in
  
  =item * set();
  
    $table->set($key => $val);
  
  Add a key/value pair to a table, if another element already exists
  with the same key, this will over-write the old data.
  
  param C<$table>: The table to add the data to.
  
  param C<$key>: The key fo use.
  
  param C<$val>: The value to add.
  
  =item * add()
  
    $table->add($key, $val);
  
  Add data to a table, regardless of whether there is another element
  with the same key.
  
  param C<$table>: The table to add to
  
  param C<$key>: The key to use
  
  param C<$val>: The value to add.
  
  =item * do()
  
    $table->do(sub {[...]}, [@filter]);
  
  Iterate over all the elements of the table, invoking provided
  subroutine for each element.  The subroutine gets passed as argument,
  a key-value pair.
  
  The subroutine can abort the iteration by returning 0 and should
  always return 1 otherwise.
  
  param C<sub>: A subroutine reference or name to be called on each item
  in the table
  
  param C<@filter>: Only keys matching one of the entries in the filter
  will be processed
   
  
  
  =item * get()
  
    $val = $table->get($key);
    @val = $table->get($key);
  
  Get the value(s) associated with a given key.
  
  After this call, the data is still in the table.
  
  param C<$table>: The table to search for the key
  
  param C<$key>: The key to search for
  
  return: In the scalar context the first matching value returned. (The
  oldest in the table, if there is more than one value.) In the list
  context the whole table is traversed and all matching values are
  returned. If nothing matches I<undef> is returned.
  
  =item * unset();
  
    $table->unset($key);
  
  Remove data from the table
  
  param C<$table>: The table to remove data from
  
  param C<$key>: The key of the data being removed
  
  
  =item * merge()
  
    $table->merge($key => $val);
  
  Add data to a table by merging the value with data that has already
  been stored
  
  param C<$table>: The table to search for the data
  
  param C<$key>: The key to merge data for
  
  param C<$val>: The data to add
  
  remark: If the key is not found, then this function acts like add()
  
  =item * overlap()
  
    overlap($table_a, $table_b, $flags);
  
  For each key/value pair in C<$table_b>, add the data to
  C<$table_a>. The definition of C<$flags> explains how C<$flags> define
  the overlapping method.
  
  param C<$table_a>: The table to add the data to.
  
  param C<$table_b>: The table to iterate over, adding its data to
  C<%table_a>.
  
  param C<$flags>: How to add the C<$table_b> to C<$table_a>.
  
  When C<$flags> == C<APR_OVERLAP_TABLES_SET>, if another element
  already exists with the same key, this will over-write the old data.
  
  When C<$flags> == C<APR_OVERLAP_TABLES_MERGE>, the key/value pair from
  C<$table_b> is added, regardless of whether there is another element
  with the same key in C<$table_a>.
  
  remark: This function is highly optimized, and uses less memory and
  CPU cycles than a function that just loops through table b calling
  other functions.
  
  =item * overlay()
  
    $new_table = overlay($table_base, $table_overlay, $pool);
  
  Merge two tables into one new table. The resulting table may have more
  than one value for the same key.
  
  param C<$pool>: The pool to use for the new table
  
  param C<$table_overlay>: The first table to put in the new table
  
  param C<$table_base>: The table to add at the end of the new table
  
  return: A new table containing all of the data from the two passed in
  
  =back
  
  =head2 TIE Interface
  
  C<APR::Table> also implements a tied interface, so you can work with the
  C<$table> object as a hash reference.
  
  The following tied-hash function are supported: FETCH, STORE, DELETE,
  CLEAR, EXISTS, FIRSTKEY, NEXTKEY and DESTROY.
  
  remark: C<APR::Table> can hold more than one key-value pair sharing
  the same key, so when using a table through the tied interface, the
  first entry found with the right key will be used, completely
  disregarding possible other entries with the same key.  The only
  exception to this is if you iterate over the list with I<each>, then
  you can access all key-value pairs that share the same key.
  
  
  
  =cut
  
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/Apache/Log.pod
  
  Index: Log.pod
  ===================================================================
  =head1 NAME
  
  Apache::Log -- Perl API for Apache Logging Methods
  
  
  
  =head1 Synopsis
  
    #in startup.pl
    #-------------
    use Apache::Log;
    my $s = Apache->server;
    
    $s->log_error("server: log_error");
    $s->log_serror(Apache::LOG_MARK, Apache::LOG_ERR,
                   0, "log_serror logging at err level");
    $s->log_serror(Apache::LOG_MARK, Apache::LOG_DEBUG,
                   APR::ENOTIME, "debug print");
    Apache::Server->log_error("routine warning");
    
    Apache->warn("routine warning");
    Apache::warn("routine warning");
    Apache::Server->warn("routine warning");
  
    #in a handler
    #------------
    use Apache::Log;
    sub handler{
        my $r = shift;
        $r->log_error("request: log_error");
        $r->warn("whoah!");
    
        my $rlog = $r->log;
        for my $level qw(emerg alert crit error warn notice info debug) {
            no strict 'refs';
            $rlog->$level($package, "request: $level log level");
        }
    
        # can use server methods as well
        my $s = $r->server;
        $s->log_error("server: log_error");
    
        $r->log_rerror(Apache::LOG_MARK, Apache::LOG_DEBUG,
                       APR::ENOTIME, "in debug");
    
        $s->log_serror(Apache::LOG_MARK, Apache::LOG_INFO, 0,
                       "server info");
    
        $s->log_serror(Apache::LOG_MARK, Apache::LOG_ERR,
                       APR::ENOTIME, "fatal error");
  
        $s->warn('routine server warning');
    }
  
  
  
  =head1 Description
  
  C<Apache::Log> provides the Perl API for Apache logging methods.
  
  
  
  
  =head1 Constants
  
  The following constants (sorted from the most severe level to the
  least severe) are used in logging methods to specify the log level at
  which the message should be logged:
  
  =over 
  
  =item * C<Apache::LOG_EMERG>
  
  =item * C<Apache::LOG_ALERT>
  
  =item * C<Apache::LOG_CRIT>
  
  =item * C<Apache::LOG_ERR>
  
  =item * C<Apache::LOG_WARNING>
  
  =item * C<Apache::LOG_NOTICE>
  
  =item * C<Apache::LOG_INFO>
  
  =item * C<Apache::LOG_DEBUG>
  
  =back
  
  For example if the current C<LogLevel> is set to I<warning>, only
  messages with log level of the level I<warning> or higher (I<err>,
  I<crit>, I<elert> and I<emerg>) will be logged. Therefore this:
  
    $r->log_rerror(Apache::LOG_MARK, Apache::LOG_WARNING,
                   APR::ENOTIME, "warning!");
  
  will log the message, but this one won't:
  
    $r->log_rerror(Apache::LOG_MARK, Apache::LOG_INFO,
                   APR::ENOTIME, "just an info");
  
  It will be logged only if the server log level is set to I<info> or
  I<debug>. (either in the configuration file or using the
  C<$s-E<gt>loglevel()> method.)
  
  Other constants:
  
  =over 
  
  =item * C<Apache::LOG_LEVELMASK>
  
  used to mask off the level value, to make sure that the log level's
  value is within the proper bits range. e.g.:
  
   $loglevel &= LOG_LEVELMASK;
  
  =item * C<Apache::LOG_TOCLIENT>
  
  used to give content handlers the option of including the error text
  in the C<ErrorDocument> sent back to the client. When
  C<Apache::LOG_TOCLIENT> is passed to C<log_rerror()> the error message
  will be saved in the C<$r>'s notes table, keyed to the string
  I<"error-notes">, if and only if the severity level of the message is
  C<Apache::LOG_WARNING> or greater and there are no other
  I<"error-notes"> entry already set in the request record's notes
  table. Once the I<"error-notes"> entry is set, it is up to the error
  handler to determine whether this text should be sent back to the
  client.  For example:
  
    $r->log_rerror(Apache::LOG_MARK, Apache::LOG_ERR|Apache::LOG_TOCLIENT,
                   APR::ENOTIME, "request log_rerror");
  
  now the log message can be retrieved via:
  
    $r->notes->get("error-notes");
  
  Remember that client generated text streams sent back to the client
  MUST be escaped to prevent CSS attacks.
  
  =item * C<Apache::LOG_STARTUP>
  
  is set only during the startup.
  
  =back
  
  
  
  
  
  
  
  =head1 Server Logging Methods
  
  =head2 C<$s-E<gt>log_error()>
  
    $s->log_error(@message);
  
  just logs the supplied message. For example:
  
    $s->log_error("running low on memory");
  
  =head2 C<$s-E<gt>log_serror()>
  
    log_serror($file, $line, $level, $status, @message);
  
  where:
  
   * $file    The file in which this function is called
   * $line    The line number on which this function is called
   * $level   The level of this error message
   * $status  The status code from the previous command
   * @message The log message
  
  This function provides a fine control of when the message is logged,
  gives an access to built-in status codes.
  
  For example:
  
    $s->log_serror(Apache::LOG_MARK, Apache::LOG_ERR,
                   0, "log_serror logging at err level");
    
    $s->log_serror(Apache::LOG_MARK, Apache::LOG_DEBUG,
                   APR::ENOTIME, "debug print");
  
  =head2 C<$s-E<gt>log()>
  
    my $slog = $s->log;
  
  returns a handle which can be used to log messages of different
  level. See the next entry.
  
  =head2 emerg(), alert(), crit(), error(), warn(), notice(), info(), debug()
  
    $s->log->emerg(@message);
  
  after getting the log handle with C<$s-E<gt>log>, use these methods to
  control when messages should be logged.
  
  For example:
  
    my $slog = $s->log;
    $slog->debug("just ", "some debug info");
    $slog->warn(@warnings);
    $slog->crit("dying");
  
  
  
  
  
  
  
  =head1 Request Logging Methods
  
  =head2 C<$r-E<gt>log_error()>
  
    $r->log_error(@message);
  
  logs the supplied message (similar to C<$s-E<gt>log_error>). For
  example:
  
    $r->log_error("the request is about to end");
  
  the same as C<$s-E<gt>log_error>.
  
  =head2 C<$r-E<gt>log_rerror()>
  
    log_rerror($file, $line, $level, $status, @message);
  
  same as C<$s-E<gt>log_rerror>. For example:
  
    $s->log_rerror(Apache::LOG_MARK, Apache::LOG_ERR,
                   0, "log_rerror logging at err level");
    
    $s->log_rerror(Apache::LOG_MARK, Apache::LOG_DEBUG,
                   APR::ENOTIME, "debug print");
  
  =head2 C<$r-E<gt>log()>
  
    my $rlog = $r->log;
  
  Similar to C<$s-E<gt>log()>
  
  =head2 the emerg(), alert(), crit(), error(), warn(), notice(), info(), debug() methods
  
  Similar to the server's log functions with the same names.
  
  For example:
  
    $rlog->debug("just ", "some debug info");
    $rlog->warn(@req_warnings);
    $rlog->crit("dying");
  
  
  
  
  =head1 General Functions
  
  =head2 C<Apache::LOG_MARK()>
  
    my($file, $line) = Apache::LOG_MARK();
  
  Though looking like a constant, this is a function, which returns a
  list of two items: C<(__FILE__, __LINE__)>, i.e. the file and the line
  where the function was called from.
  
  
  
  
  
  
  =head1 Aliases
  
  =head2 C<$s-E<gt>warn()>
  
    $s->warn(@warnings);
  
  is the same as:
  
    $s->log_error(Apache::LOG_MARK, Apache::LOG_WARNING, 0, @warnings)
  
  For example:
  
    $s->warn('routine server warning');
  
  =head2 C<Apache-E<gt>warn()>
  
  =head2 C<Apache::warn()>
  
    Apache->warn(@warnings);
  
  
  
  
  =cut
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/Apache/Reload.pod
  
  Index: Reload.pod
  ===================================================================
  =head1 NAME
  
  Apache::Reload - Reload Perl Modules when Changed on Disk
  
  =head1 Synopsis
  
    # Monitor and reload all modules in %INC:
    # httpd.conf:
    PerlModule Apache::Reload
    PerlInitHandler Apache::Reload
  
    # Reload groups of modules:
    # httpd.conf:
    PerlModule Apache::Reload
    PerlInitHandler Apache::Reload
    PerlSetVar ReloadAll Off
    PerlSetVar ReloadModules "ModPerl::* Apache::*"
    #PerlSetVar ReloadDebug On
  
    # Reload a single module from within itself:
    package My::Apache::Module;
    use Apache::Reload;
    sub handler { ... }
    1;
  
  =head1 Description
  
  C<Apache::Reload> reloads modules that change on the disk.
  
  When Perl pulls a file via C<require>, it stores the filename in the
  global hash C<%INC>.  The next time Perl tries to C<require> the same
  file, it sees the file in C<%INC> and does not reload from disk.  This
  module's handler can be configured to iterate over the modules in
  C<%INC> and reload those that have changed on disk or only specific
  modules that have registered themselves with C<Apache::Reload>. It can
  also do the check for modified modules, when a special touch-file has
  been modified.
  
  Note that C<Apache::Reload> operates on the current context of
  C<@INC>.  Which means, when called as a C<Perl*Handler> it will not
  see C<@INC> paths added or removed by C<Apache::Registry> scripts, as
  the value of C<@INC> is saved on server startup and restored to that
  value after each request.  In other words, if you want
  C<Apache::Reload> to work with modules that live in custom C<@INC>
  paths, you should modify C<@INC> when the server is started.  Besides,
  C<'use lib'> in the startup script, you can also set the C<PERL5LIB>
  variable in the httpd's environment to include any non-standard 'lib'
  directories that you choose.  For example, to accomplish that you can
  include a line:
  
    PERL5LIB=/home/httpd/perl/extra; export PERL5LIB
  
  in the script that starts Apache. Alternatively, you can set this
  environment variable in I<httpd.conf>:
  
    PerlSetEnv PERL5LIB /home/httpd/perl/extra
  
  =head2 Monitor All Modules in C<%INC>
  
  To monitor and reload all modules in C<%INC>, simply add the following
  configuration to your I<httpd.conf>:
  
    PerlModule Apache::Reload
    PerlInitHandler Apache::Reload
  
  =head2 Register Modules Implicitly
  
  To only reload modules that have registered with C<Apache::Reload>,
  add the following to the I<httpd.conf>:
  
    PerlModule Apache::Reload
    PerlInitHandler Apache::Reload
    PerlSetVar ReloadAll Off
    # ReloadAll defaults to On
  
  Then any modules with the line:
  
    use Apache::Reload;
  
  Will be reloaded when they change.
  
  =head2 Register Modules Explicitly
  
  You can also register modules explicitly in your I<httpd.conf> file
  that you want to be reloaded on change:
  
    PerlModule Apache::Reload
    PerlInitHandler Apache::Reload
    PerlSetVar ReloadAll Off
    PerlSetVar ReloadModules "My::Foo My::Bar Foo::Bar::Test"
  
  Note that these are split on whitespace, but the module list B<must>
  be in quotes, otherwise Apache tries to parse the parameter list.
  
  The C<*> wild character can be used to register groups of files under
  the same namespace. For example the setting:
  
    PerlSetVar ReloadModules "ModPerl::* Apache::*"
  
  will monitor all modules under the namespaces C<ModPerl::> and
  C<Apache::>.
  
  =head2 Monitor Only Certain Sub Directories
  
  To reload modules only in certain directories (and their
  subdirectories) add the following to the I<httpd.conf>:
  
    PerlModule Apache::Reload
    PerlInitHandler Apache::Reload
    PerlSetVar ReloadDirectories "/tmp/project1 /tmp/project2"
  
  You can further narrow the list of modules to be reloaded from the
  chosen directories with C<ReloadModules> as in:
  
    PerlModule Apache::Reload
    PerlInitHandler Apache::Reload
    PerlSetVar ReloadDirectories "/tmp/project1 /tmp/project2"
    PerlSetVar ReloadAll Off
    PerlSetVar ReloadModules "MyApache::*"
  
  In this configuration example only modules from the namespace
  C<MyApache::> found in the directories I</tmp/project1/> and
  I</tmp/project2/> (and their subdirectories) will be reloaded.
  
  =head2 Special "Touch" File
  
  You can also declare a file, which when gets C<touch(1)>ed, causes the
  reloads to be performed. For example if you set:
  
    PerlSetVar ReloadTouchFile /tmp/reload_modules
  
  and don't C<touch(1)> the file I</tmp/reload_modules>, the reloads
  won't happen until you go to the command line and type:
  
    % touch /tmp/reload_modules
  
  When you do that, the modules that have been changed, will be
  magically reloaded on the next request. This option works with any
  mode described before.
  
  =head1 Performance Issues
  
  This modules is perfectly suited for a development environment. Though
  it's possible that you would like to use it in a production
  environment, since with C<Apache::Reload> you don't have to restart
  the server in order to reload changed modules during software
  updates. Though this convenience comes at a price:
  
  =over
  
  =item *
  
  If the "touch" file feature is used, C<Apache::Reload> has to stat(2)
  the touch file on each request, which adds a slight but most likely
  insignificant overhead to response times. Otherwise C<Apache::Reload>
  will stat(2) each registered module or even worse--all modules in
  C<%INC>, which will significantly slow everything down.
  
  =item *
  
  Once the child process reloads the modules, the memory used by these
  modules is not shared with the parent process anymore. Therefore the
  memory consumption may grow significantly.
  
  =back
  
  Therefore doing a full server stop and restart is probably a better
  solution.
  
  =head1 Debug
  
  If you aren't sure whether the modules that are supposed to be
  reloaded, are actually getting reloaded, turn the debug mode on:
  
    PerlSetVar ReloadDebug On
  
  =head1 Problems With Reloading Modules Which Do Not Declare Their Package Name
  
  If you modify modules which don't declare their C<package> and rely on
  C<Apache::Reload> to reload them you may encounter problems: i.e.,
  it'll appear as if the module wasn't reloaded when in fact it
  was. This happens because when C<Apache::Reload> C<require()>s such a
  module all the global symbols end up in the C<Apache::Reload>
  namespace!  So the module does get reloaded and you see the compile
  time errors if there are any, but the symbols don't get imported to
  the right namespace. Therefore the old version of the code is running.
  
  =head1 Threaded MPM and Multiple Perl Interpreters
  
  If you use C<Apache::Reload> with a threaded MPM and multiple Perl
  interpreters, the modules will be reloaded by each interpreter as they
  are used, not every interpreters at once.  Similar to mod_perl 1.0
  where each child has its own Perl interpreter, the modules are
  reloaded as each child is hit with a request.
  
  If a module is loaded at startup, the syntax tree of each subroutine
  is shared between interpreters (big win), but each subroutine has its
  own padlist (where lexical my variables are stored).  Once
  C<Apache::Reload> reloads a module, this sharing goes away and each
  Perl interpreter will have its own copy of the syntax tree for the
  reloaded subroutines.
  
  
  =head1 Pseudo-hashes
  
  The short summary of this is: Don't use pseudo-hashes. They are
  deprecated since Perl 5.8 and are removed in 5.9.
  
  Use an array with constant indexes. Its faster in the general case,
  its more guaranteed, and generally, it works.
  
  The long summary is that some work has been done to get this module
  working with modules that use pseudo-hashes, but it's still broken in
  the case of a single module that contains multiple packages that all
  use pseudo-hashes.
  
  So don't do that.
  
  =head1 Authors
  
  Matt Sergeant, matt@sergeant.org
  
  Stas Bekman (porting to mod_perl 2.0)
  
  A few concepts borrowed from C<Stonehenge::Reload> by Randal Schwartz
  and C<Apache::StatINC> (mod_perl 1.x) by Doug MacEachern and Ask
  Bjoern Hansen.
  
  =head1 See Also
  
  C<Stonehenge::Reload>
  
  =cut
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/Apache/RequestRec.pod
  
  Index: RequestRec.pod
  ===================================================================
  =head1 NAME
  
  Apache::RequestRec -- A Perl API for Apache request object
  
  =head1 SYNOPSIS
  
    use Apache::RequestRec;
    sub handler{
        my $r = shift;
        
        my $s = $r->server;
        my $dir_config = $r->dir_config;
        ...
    }
  
  =head1 DESCRIPTION
  
  C<Apache::RequestRec> provides the Perl API for Apache request object.
  
  =head1 API
  
  Function arguments (if any) and return values are shown in the
  function's synopsis.
  
  =over
  
  =item * server()
  
    $s = $r->server;
  
  Gets the C<Apache::Server> object for the server the request C<$r> is
  running under.
  
  =item * dir_config()
  
  dir_config() provides an interface for the per-directory variable
  specified by the C<PerlSetVar> and C<PerlAddVar> directives, and also
  can be manipulated via the C<APR::Table> methods.
  
  The keys are case-insensitive.
  
    $apr_table = $r->dir_config();
  
  dir_config() called in a scalar context without the C<$key> argument
  returns a I<HASH> reference blessed into the I<APR::Table> class. This
  object can be manipulated via the I<APR::Table> methods. For available
  methods see I<APR::Table>.
  
    @values = $r->dir_config($key);
  
  If the C<$key> argument is passed in the list context a list of all
  matching values will be returned. This method is ineffective for big
  tables, as it does a linear search of the table. Thefore avoid using
  this way of calling dir_config() unless you know that there could be
  more than one value for the wanted key and all the values are wanted.
  
    $value = $r->dir_config($key);
  
  If the C<$key> argument is passed in the scalar context only a single
  value will be returned. Since the table preserves the insertion order,
  if there is more than one value for the same key, the oldest value
  assosiated with the desired key is returned. Calling in the scalar
  context is also much faster, as it'll stop searching the table as soon
  as the first match happens.
  
    $r->dir_config($key => $val);
  
  If the C<$key> and the C<$val> arguments are used, the set() operation
  will happen: all existing values associated with the key C<$key> (and
  the key itself) will be deleted and C<$value> will be placed instead.
  
    $r->dir_config($key => undef);
  
  If C<$val> is I<undef> the unset() operation will happen: all existing
  values associated with the key C<$key> (and the key itself) will be
  deleted.
  
  =item *
  
  =back
  
  
  =cut
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/Apache/ServerUtil.pod
  
  Index: ServerUtil.pod
  ===================================================================
  =head1 NAME
  
  Apache::ServerUtil -- Methods for work with Apache::Server object
  
  =head1 SYNOPSIS
  
    use Apache::ServerUtil;
    
    $s = Apache->server;
    my $srv_cfg = $s->dir_config;
  
    # get 'conf/' dir path using $r
    my $conf_dir = Apache::server_root_relative('conf', $r->pool);
  
    # get 'log/' dir path using default server startup pool
    my $log_dir = Apache::server_root_relative('log');
  
  =head1 DESCRIPTION
  
  C<Apache::ServerUtil> provides the Perl API for Apache server object.
  
  META: complete
  
  =head1 API
  
  Function arguments (if any) and return values are shown in the
  function's synopsis.
  
  =head2 CONSTANTS
  
  =over
  
  =item * server_root
  
  returns the value set by the C<ServerRoot> directive.
  
  =back
  
  =head2 FUNCTIONS
  
  =over
  
  =item * server_root_relative()
  
  Returns the canonical form of the filename made absolute to
  C<ServerRoot>:
  
    Apache::server_root_relative($pool, $fname);
  
  C<$fname> is appended to the value of C<ServerRoot> and return
  it. e.g.:
  
    my $log_dir = Apache::server_root_relative($r->pool, 'logs');
  
  If C<$fname> is not specified, the value of C<ServerRoot> is returned
  with a trailing C</>. (it's the same as using C<''> as C<$fname>'s
  value).
  
  Also see the C<server_root> constant.
  
  =back
  
  =head2 METHODS
  
  =over
  
  =item * server()
  
  The main server's object can be retrieved with:
  
    $s = Apache->server;
  
  Gets the C<Apache::Server> object for the main server.
  
  =item * dir_config()
  
  dir_config() provides an interface for the per-server variables
  specified by the C<PerlSetVar> and C<PerlAddVar> directives, and also
  can be manipulated via the C<APR::Table> methods.
  
  The keys are case-insensitive.
  
    $t = $s->dir_config();
  
  dir_config() called in a scalar context without the C<$key> argument
  returns a I<HASH> reference blessed into the I<APR::Table> class. This
  object can be manipulated via the I<APR::Table> methods. For available
  methods see I<APR::Table>.
  
    @values = $s->dir_config($key);
  
  If the C<$key> argument is passed in the list context a list of all
  matching values will be returned. This method is ineffective for big
  tables, as it does a linear search of the table. Thefore avoid using
  this way of calling dir_config() unless you know that there could be
  more than one value for the wanted key and all the values are wanted.
  
    $value = $s->dir_config($key);
  
  If the C<$key> argument is passed in the scalar context only a single
  value will be returned. Since the table preserves the insertion order,
  if there is more than one value for the same key, the oldest value
  assosiated with the desired key is returned. Calling in the scalar
  context is also much faster, as it'll stop searching the table as soon
  as the first match happens.
  
    $s->dir_config($key => $val);
  
  If the C<$key> and the C<$val> arguments are used, the set() operation
  will happen: all existing values associated with the key C<$key> (and
  the key itself) will be deleted and C<$value> will be placed instead.
  
    $s->dir_config($key => undef);
  
  If C<$val> is I<undef> the unset() operation will happen: all existing
  values associated with the key C<$key> (and the key itself) will be
  deleted.
  
  =item * push_handlers()
  
  =item * add_handlers()
  
  =item * get_handlers()
  
  
  =back
  
  
  =cut
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/Apache/SubProcess.pod
  
  Index: SubProcess.pod
  ===================================================================
  =head1 NAME
  
  Apache::SubProcess -- Executing SubProcesses from mod_perl
  
  =head1 SYNOPSIS
  
    use Apache::SubProcess ();
    
    use Config;
    use constant PERLIO_IS_ENABLED => $Config{useperlio};
    
    # pass @ARGV / read from the process
    $command = "/tmp/argv.pl";
    @argv = qw(foo bar);
    $out_fh = Apache::SubProcess::spawn_proc_prog($r, $command, \@argv);
    $output = read_data($out_fh);
    
    # pass environment / read from the process
    $command = "/tmp/env.pl";
    $r->subprocess_env->set(foo => "bar");
    $out_fh = Apache::SubProcess::spawn_proc_prog($r, $command);
    $output = read_data($out_fh);
    
    # write to/read from the process
    $command = "/tmp/in_out_err.pl";
    ($in_fh, $out_fh, $err_fh) = 
        Apache::SubProcess::spawn_proc_prog($r, $command);
    print $in_fh "hello\n";
    $output = read_data($out_fh);
    $error  = read_data($err_fh);
    
    # helper function to work w/ and w/o perlio-enabled Perl
    sub read_data {
        my($fh) = @_;
        my $data;
        if (PERLIO_IS_ENABLED || IO::Select->new($fh)->can_read(10)) {
            $data = <$fh>;
        }
        return defined $data ? $data : '';
    }
  
  =head1 DESCRIPTION
  
  C<Apache::SubProcess> provides the Perl API for running and
  communicating with processes spawned from mod_perl handlers.
  
  =head1 API
  
  =head2 spawn_proc_prog()
  
    $out_fh = 
        Apache::SubProcess::spawn_proc_prog($r, $command, [\@argv]);
    ($in_fh, $out_fh, $err_fh) = 
        Apache::SubProcess::spawn_proc_prog($r, $command, [\@argv]);
  
  spawn_proc_prog() spawns a sub-process which exec()'s C<$command> and
  returns the output pipe filehandle in the scalar context, or input,
  output and error pipe filehandles in the list context. Using these
  three pipes it's possible to communicate with the spawned process.
  
  The third optional argument is a reference to an array which if passed
  becomes ARGV to the spawned program.
  
  It's possible to pass environment variables as well, by calling:
  
    $r->subprocess_env->set($key => $value);
  
  before spawning the subprocess.
  
  There is an issue with reading from the read filehandle (C<$in_fh>)):
  
  A pipe filehandle returned under perlio-disabled Perl needs to call
  select() if the other end is not fast enough to send the data, since
  the read is non-blocking.
  
  A pipe filehandle returned under perlio-enabled Perl on the other hand
  does the select() internally, because it's really a filehandle opened
  via C<:APR> layer, which internally uses APR to communicate with the
  pipe. The way APR is implemented Perl's select() cannot be used with
  it (mainly because select() wants fileno() and APR is a crossplatform
  implementation which hides the internal datastructure).
  
  Therefore to write a portable code, you want to use select for
  perlio-disabled Perl and do nothing for perlio-enabled Perl, hence you
  can use something similar to the read_data() wrapper shown in the
  L<SYNOPSIS|/SYNOPSIS> section.
  
  =cut
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/Apache/compat.pod
  
  Index: compat.pod
  ===================================================================
  =head1 NAME
  
  Apache::compat -- 1.0 backward compatibility functions deprecated in 2.0
  
  =head1 SYNOPSIS
  
    use Apache::compat;
  
  =head1 DESCRIPTION
  
  C<Apache::compat> provides mod_perl 1.0 compatibility layer.
  
  It includes most of the functions that are deprecated in mod_perl
  2.0. If your code uses any of these functions you should just load
  this module at the server startup, and chances are that everything
  should work as it did in 1.0.
  
  However, certain functionality is not optimized and therefore it's the
  best to try to port your code not to use deprecated functions and stop
  using the compatibility layer.
  
  =head1 API
  
  META: complete
  
  Function arguments (if any) and return values are shown in the
  function's synopsis.
  
  =over
  
  =item * $r-E<gt>header_in()
  
    $r->header_in( $header_name, [$value] )
  
  Return the value of a client header:
  
     $ct = $r->header_in($key);
  
  Set or modify the value of a client header:
  
     $r->header_in($key, $val);
  
  =item * $r-E<gt>header_out()
  
    $r->header_out( $header, $value )
  
  Return the value of a response header:
  
     $ct = $r->header_out($key);
  
  Set or modify the value of a response header:
  
     $r->header_out($key, $val);
  
  You should not define any I<"Content-XXX"> headers by calling this
  method, because these headers use their own specific methods.
  
  =item *
  
  =back
  
  =cut
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/ModPerl/PerlRun.pod
  
  Index: PerlRun.pod
  ===================================================================
  =head1 NAME
  
  ModPerl::PerlRun - Run unaltered CGI scripts under mod_perl
  
  =head1 SYNOPSIS
  
  =head1 DESCRIPTION
  
  =head1 AUTHORS
  
  Doug MacEachern
  
  Stas Bekman
  
  =head1 SEE ALSO
  
  ModPerl::RegistryCooker(3), Apache(3), mod_perl(3)
  
  =cut
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/ModPerl/Registry.pod
  
  Index: Registry.pod
  ===================================================================
  =head1 NAME
  
  ModPerl::Registry - Run unaltered CGI scripts persistently under mod_perl
  
  =head1 Synopsis
  
    # httpd.conf
    PerlModule ModPerl::Registry
    Alias /perl/ /home/httpd/perl/
    <Location /perl>
        SetHandler perl-script
        PerlResponseHandler ModPerl::Registry
        #PerlOptions +ParseHeaders
        #PerlOptions -GlobalRequest
        Options +ExecCGI
    </Location>
  
  =head1 Description
  
  URIs in the form of C<http://example.com/perl/test.pl> will be
  compiled as the body of a Perl subroutine and executed.  Each child
  process will compile the subroutine once and store it in memory. It
  will recompile it whenever the file (e.g. I<test.pl> in our example)
  is updated on disk.  Think of it as an object oriented server with
  each script implementing a class loaded at runtime.
  
  The file looks much like a "normal" script, but it is compiled into a
  subroutine.
  
  For example:
  
    my $r = Apache->request;
    $r->content_type("text/html");
    $r->send_http_header;
    $r->print("mod_perl rules!");
  
  XXX: STOPPED here
  
  META: document that for now we don't chdir() into the script's dir,
  because it affects the whole process under threads.
  
  
  This module emulates the CGI environment, allowing programmers to
  write scripts that run under CGI or mod_perl without change.  Existing
  CGI scripts may require some changes, simply because a CGI script has
  a very short lifetime of one HTTP request, allowing you to get away
  with "quick and dirty" scripting.  Using mod_perl and Apache::Registry
  requires you to be more careful, but it also gives new meaning to the
  word "quick"!
  
  Be sure to read all mod_perl related documentation for more details,
  including instructions for setting up an environment that looks
  exactly like CGI:
  
   print "Content-type: text/html\n\n";
   print "Hi There!";
  
  Note that each httpd process or "child" must compile each script once,
  so the first request to one server may seem slow, but each request
  there after will be faster.  If your scripts are large and/or make use
  of many Perl modules, this difference should be noticeable to the
  human eye.
  
  =head1 SECURITY
  
  Apache::Registry::handler will preform the same checks as mod_cgi
  before running the script.
  
  =head1 ENVIRONMENT
  
  The Apache function `exit' overrides the Perl core built-in function.
  
  The environment variable B<GATEWAY_INTERFACE> is set to C<CGI-Perl/1.1>.
  
  =head1 COMMANDLINE SWITCHES IN FIRST LINE
  
  Normally when a Perl script is run from the command line or under CGI,
  arguments on the `#!' line are passed to the perl interpreter for processing.
  
  Apache::Registry currently only honors the B<-w> switch and will turn
  on warnings using the C<$^W> global variable.  Another common switch
  used with CGI scripts is B<-T> to turn on taint checking.  This can
  only be enabled when the server starts with the configuration
  directive:
  
   PerlTaintCheck On
  
  However, if taint checking is not enabled, but the B<-T> switch is seen,
  Apache::Registry will write a warning to the error_log.
  
  =head1 DEBUGGING
  
  You may set the debug level with the $Apache::Registry::Debug bitmask
  
   1 => log recompile in errorlog
   2 => Apache::Debug::dump in case of $@
   4 => trace pedantically
  
  =head1 CAVEATS
  
  Apache::Registry makes things look just the CGI environment, however, you
  must understand that this *is not CGI*.  Each httpd child will compile
  your script into memory and keep it there, whereas CGI will run it once,
  cleaning out the entire process space.  Many times you have heard
  "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.
  
  
  =head1 Authors
  
  Andreas J. Koenig, Doug MacEachern and Stas Bekman.
  
  =head1 See Also
  
  C<L<ModPerl::RegistryCooker>>, C<L<ModPerl::RegistryBB>>,
  C<L<ModPerl::PerlRun>>, Apache(3), mod_perl(3)
  
  =cut
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/ModPerl/RegistryBB.pod
  
  Index: RegistryBB.pod
  ===================================================================
  =head1 NAME
  
  ModPerl::RegistryBB - Run unaltered CGI scripts persistently under mod_perl
  
  =head1 Synopsis
  
    # httpd.conf
    PerlModule ModPerl::RegistryBB
    Alias /perl/ /home/httpd/perl/
    <Location /perl>
        SetHandler perl-script
        PerlResponseHandler ModPerl::RegistryBB
        #PerlOptions +ParseHeaders
        #PerlOptions -GlobalRequest
        Options +ExecCGI
    </Location>
  
  =head1 Description
  
  C<ModPerl::RegistryBB> is similar to C<L<ModPerl::Registry>>, but does
  the bare minimum (mnemonic: BB = Bare Bones) to compile a script file
  once and run it many times, in order to get the maximum
  performance. Whereas C<L<ModPerl::Registry>> does various checks,
  which add a slight overhead to response times.
  
  =head1 Authors
  
  Doug MacEachern
  
  Stas Bekman
  
  =head1 See Also
  
  C<L<ModPerl::RegistryCooker>>, C<L<ModPerl::Registry>>, Apache(3),
  mod_perl(3)
  
  =cut
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/ModPerl/RegistryCooker.pod
  
  Index: RegistryCooker.pod
  ===================================================================
  =head1 NAME
  
  ModPerl::RegistryCooker - Cook mod_perl 2.0 Registry Modules
  
  =head1 Synopsis
  
    # shouldn't be used as-is but sub-classed first
    # see ModPerl::Registry for an example
  
  =head1 Description
  
  C<ModPerl::RegistryCooker> is used to create flexible and overridable
  registry modules which emulate mod_cgi for Perl scripts. The concepts
  are discussed in the manpage of the following modules:
  C<L<ModPerl::Registry>>, C<L<ModPerl::Registry>> and
  C<L<ModPerl::RegistryBB>>.
  
  C<ModPerl::RegistryCooker> has two purposes:
  
  =over
  
  =item *
  
  Provide ingredients that can be used by registry sub-classes
  
  =item *
  
  Provide a default behavior, which can be overriden in sub-classed
  
  META: in the future this functionality may move into a separate class.
  
  =back
  
  Here are the current overridable methods:
  
  META: these are all documented in RegistryCooker.pm, though not using
  pod. please help to port these to pod and move the descriptions here.
  
  =over
  
  =item * new()
  
  create the class's object, bless it and return it
  
    my $obj = $class->new($r);
  
  C<$class> -- the registry class, usually C<__PACKAGE__> can be used.
  
  C<$r> -- C<L<Apache::Request>> object.
  
  default: new()
  
  =item * init()
  
  initializes the data object's fields: C<REQ>, C<FILENAME>,
  C<URI>. Called from the new().
  
  default: init()
  
  =item * default_handler()
  
  default:  default_handler()
  
  =item * run()
  
  default: run()
  
  =item * can_compile()
  
  default: can_compile()
  
  =item * make_namespace()
  
  default: make_namespace()
  
  =item * namespace_root()
  
  default: namespace_root()
  
  
  =item * namespace_from()
  
  If C<namespace_from_uri> is used and the script is called from the
  virtual host, by default the virtual host name is prepended to the uri
  when package name for the compiled script is created. Sometimes this
  behavior is undesirable, e.g., when the same (physical) script is
  accessed using the same path_info but different virtual hosts. In that
  case you can make the script compiled only once for all vhosts, by
  specifying:
  
    $ModPerl::RegistryCooker::NameWithVirtualHost = 0;
  
  The drawback is that it affects the global environment and all other
  scripts will be compiled ignoring virtual hosts.
  
  default: namespace_from()
  
  =item * is_cached()
  
  default: is_cached()
  
  =item * should_compile()
  
  default: should_compile()
  
  =item * flush_namespace()
  
  default: flush_namespace()
  
  
  =item * cache_table()
  
  default: cache_table()
  
  =item * cache_it()
  
  default: cache_it()
  
  =item * read_script()
  
  default: read_script()
  
  =item * rewrite_shebang()
  
  default: rewrite_shebang()
  
  =item * set_script_name()
  
  default: set_script_name()
  
  =item * chdir_file()
  
  default: chdir_file()
  
  =item * get_mark_line()
  
  default: get_mark_line()
  
  =item * compile()
  
  default: compile()
  
  
  =item * error_check()
  
  default: error_check()
  
  =item * strip_end_data_segment()
  
  default: strip_end_data_segment()
  
  =item * convert_script_to_compiled_handler()
  
  default: convert_script_to_compiled_handler()
  
  =back
  
  
  
  
  =head2 Special Predefined Functions
  
  The following functions are implemented as constants.
  
  =over
  
  =item * NOP()
  
  Use when the function shouldn't do anything.
  
  =item * TRUE()
  
  Use when a function should always return a true value.
  
  =item * FALSE()
  
  Use when a function should always return a false value.
  
  =back
  
  
  
  
  =head1 Sub-classing Techniques
  
  To override the default C<ModPerl::RegistryCooker> methods, first,
  sub-class C<ModPerl::RegistryCooker> or one of its existing
  sub-classes, using C<use base>. Second, override the methods.
  
  Those methods that weren't overridden will be resolved at run time
  when used for the first time and cached for the future requests. One
  way to to shortcut this first run resolution is to use the symbol
  aliasing feature. For example to alias C<ModPerl::MyRegistry::flush_namespace>
  as C<ModPerl::RegistryCooker::flush_namespace>, you can do:
  
    package ModPerl::MyRegistry;
    use base qw(ModPerl::RegistryCooker);
    *ModPerl::MyRegistry::flush_namespace =
        \&ModPerl::RegistryCooker::flush_namespace;
    1;
  
  In fact, it's a good idea to explicitly alias all the methods so you
  know exactly what functions are used, rather then relying on the
  defaults. For that purpose C<ModPerl::RegistryCooker> class method
  install_aliases() can be used. Simply prepare a hash with method names
  in the current package as keys and corresponding fully qualified
  methods to be aliased for as values and pass it to
  install_aliases(). Continuing our example we could do:
  
    package ModPerl::MyRegistry;
    use base qw(ModPerl::RegistryCooker);
    my %aliases = (
        flush_namespace => 'ModPerl::RegistryCooker::flush_namespace',
    );
    __PACKAGE__->install_aliases(\%aliases);
    1;
  
  The values use fully qualified packages so you can mix methods from
  different classes.
  
  =head1 Examples
  
  The best examples are existing core registry modules:
  C<L<ModPerl::Registry>>, C<L<ModPerl::Registry>> and
  C<L<ModPerl::RegistryBB>>. Look at the source code and their manpages
  to see how they subclass C<ModPerl::RegistryCooker>.
  
  For example by default C<L<ModPerl::Registry>> uses the script's path
  when creating a package's namespace. If for example you want to use a
  uri instead you can override it with:
  
    *ModPerl::MyRegistry::namespace_from =
        \&ModPerl::RegistryCooker::namespace_from_uri;
    1;
  
  Since the C<namespace_from_uri> component already exists in
  C<ModPerl::RegistryCooker>. If you want to write your own method,
  e.g., that creates a namespace based on the inode, you can do:
  
    sub namespace_from_inode {
        my $self = shift;
        return (stat $self->[FILENAME])[1];
    }
  
  META: when $r-E<gt>finfo will be ported it'll be more effecient. 
  (stat $r-E<gt>finfo)[1]
  
  
  =head1 Authors
  
  Doug MacEachern
  
  Stas Bekman
  
  =head1 See Also
  
  C<L<ModPerl::Registry>>, C<L<ModPerl::RegistryBB>>,
  C<L<ModPerl::PerlRun>>, Apache(3), mod_perl(3)
  
  =cut
  
  
  
  1.1                  modperl-docs/src/docs/2.0/api/ModPerl/RegistryLoader.pod
  
  Index: RegistryLoader.pod
  ===================================================================
  =head1 NAME
  
  ModPerl::RegistryLoader - Compile ModPerl::RegistryCooker scripts at server startup
  
  =head1 Synopsis
  
    # in startup.pl
    use ModPerl::RegistryLoader ();
    
    # explicit uri => filename mapping 
    my $rlbb = ModPerl::RegistryLoader->new(
        package => 'ModPerl::RegistryBB',
        debug   => 1, # default 0
    );
  
    $rlbb->handler($uri, $filename);
    
    ###
    # uri => filename mapping using a helper function
    sub trans {
        my $uri = shift; 
        $uri =~ s|^/registry/|cgi-bin/|;
        return Apache::server_root_relative($uri);
    }
    my $rl = ModPerl::RegistryLoader->new(
        package => 'ModPerl::Registry',
        trans   => \&trans,
    );
    $rl->handler($uri);
    
    ###
    $rlbb->handler($uri, $filename, $virtual_hostname);
  
  
  =head1 Description
  
  This modules allows compilation of scripts, running under packages
  derived from C<ModPerl::RegistryCooker>, at server startup.  The
  script's handler routine is compiled by the parent server, of which
  children get a copy and thus saves some memory by initially sharing
  the compiled copy with the parent and saving the overhead of script's
  compilation on the first request in every httpd instance.
  
  This module is of course useless for those running the
  C<L<ModPerl::PerlRun>> handler, because the scripts get recompiled on
  each request under this handler.
  
  =head1 Methods
  
  =over
  
  =item new()
  
  When creating a new C<ModPerl::RegistryLoader> object, one has to
  specify which of the C<ModPerl::RegistryCooker> derived modules to
  use. For example if a script is going to run under
  C<ModPerl::RegistryBB> the object is initialized as:
  
    my $rlbb = ModPerl::RegistryLoader->new(
        package => 'ModPerl::RegistryBB',
    );
  
  If the package is not specified C<ModPerl::Registry> is assumed:
  
    my $rlbb = ModPerl::RegistryLoader->new();
  
  To turn the debugging on, set the I<debug> attribute to a true value:
  
    my $rlbb = ModPerl::RegistryLoader->new(
        package => 'ModPerl::RegistryBB',
        debug   => 1,
    );
  
  Instead of specifying explicitly a filename for each uri passed to
  handler(), a special attribute I<trans> can be set to a subroutine to
  perform automatic remapping.
  
    my $rlbb = ModPerl::RegistryLoader->new(
        package => 'ModPerl::RegistryBB',
        trans   => \&trans,
    );
  
  See the handler() item for an example of using the I<trans> attribute.
  
  =item handler()
  
    $rl->handler($uri, [$filename, [$virtual_hostname]]);
  
  The handler() method takes argument of C<uri> and optionally of
  C<filename> and of C<virtual_hostname>.
  
  URI to filename translation normally doesn't happen until HTTP request
  time, so we're forced to roll our own translation. If the filename is
  supplied it's used in translation.
  
  If the filename is omitted and a C<trans> subroutine was not set in
  new(), the loader will try using the C<uri> relative to the
  C<ServerRoot> configuration directive.  For example:
  
    httpd.conf:
    -----------
    ServerRoot /usr/local/apache
    Alias /registry/ /usr/local/apache/cgi-bin/
  
    startup.pl:
    -----------
    use ModPerl::RegistryLoader ();
    my $rl = ModPerl::RegistryLoader->new(
        package => 'ModPerl::Registry',
    );
    # preload /usr/local/apache/cgi-bin/test.pl
    $rl->handler(/registry/test.pl);
  
  To make the loader smarter about the URI-E<gt>filename translation,
  you may provide the C<new()> method with a C<trans()> function to
  translate the uri to filename.
  
  The following example will pre-load all files ending with I<.pl> in
  the I<cgi-bin> directory relative to C<ServerRoot>.
  
    httpd.conf:
    -----------
    ServerRoot /usr/local/apache
    Alias /registry/ /usr/local/apache/cgi-bin/
  
    startup.pl:
    -----------
    {
        # test the scripts pre-loading by using trans sub
        use ModPerl::RegistryLoader ();
        use DirHandle ();
        use strict;
    
        my $dir = Apache::server_root_relative("cgi-bin");
    
        sub trans {
            my $uri = shift; 
            $uri =~ s|^/registry/|cgi-bin/|;
            return Apache::server_root_relative($uri);
        }
    
        my $rl = ModPerl::RegistryLoader->new(
            package => "ModPerl::Registry",
            trans   => \&trans,
        );
        my $dh = DirHandle->new($dir) or die $!;
    
        for my $file ($dh->read) {
            next unless $file =~ /\.pl$/;
            $rl->handler("/registry/$file");
        }
    }
  
  If C<$virtual_hostname> argument is passed it'll be used in the
  creation of the package name the script will be compiled into for
  those registry handlers that use I<namespace_from_uri()> method.  See
  also the notes on C<$ModPerl::RegistryCooker::NameWithVirtualHost> in
  the C<L<ModPerl::RegistryCooker>> documentation.
  
  Also
  explained in the C<L<ModPerl::RegistryLoader>> documentation, this
  only has an effect at run time if
  C<$ModPerl::RegistryCooker::NameWithVirtualHost> is set to true,
  otherwise the C<$virtual_hostname> argument is ignored.
  
  =back
  
  
  =head1 Implementation Notes
  
  C<ModPerl::RegistryLoader> performs a very simple job, at run time it
  loads and sub-classes the module passed via the I<package> attribute
  and overrides some of its functions, to emulate the run-time
  environment. This allows to preload the same script into different
  registry environments.
  
  =head1 Authors
  
  The original C<Apache::RegistryLoader> implemented by Doug MacEachern.
  
  Stas Bekman did the porting to the new registry framework based on
  C<ModPerl::RegistryLoader>.
  
  =head1 SEE ALSO
  
  C<L<ModPerl::RegistryCooker>>, C<L<ModPerl::Registry>>,
  C<L<ModPerl::RegistryBB>>, C<L<ModPerl::PerlRun>>, Apache(3),
  mod_perl(3)
  
  
  
  1.41      +19 -19    modperl-docs/src/docs/2.0/user/compat/compat.pod
  
  Index: compat.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/compat/compat.pod,v
  retrieving revision 1.40
  retrieving revision 1.41
  diff -u -r1.40 -r1.41
  --- compat.pod	16 Jan 2003 01:06:43 -0000	1.40
  +++ compat.pod	27 Jan 2003 04:05:13 -0000	1.41
  @@ -203,15 +203,15 @@
   
   =over
   
  -=item C<L<Apache::Const|docs::2.0::api::mod_perl-2.0::Apache::Const>>
  +=item C<L<Apache::Const|docs::2.0::api::Apache::Const>>
   
   Apache constants
   
  -=item C<L<APR::Const|docs::2.0::api::mod_perl-2.0::APR::Const>>
  +=item C<L<APR::Const|docs::2.0::api::APR::Const>>
   
   Apache Portable Runtime constants
   
  -=item C<L<ModPerl::Const|docs::2.0::api::mod_perl-2.0::ModPerl::Const>>
  +=item C<L<ModPerl::Const|docs::2.0::api::ModPerl::Const>>
   
   mod_perl specific constants
   
  @@ -314,7 +314,7 @@
   C<Apache::ServerUtil>.
   
   See the
  -C<L<Apache::ServerUtil|docs::2.0::api::mod_perl-2.0::Apache::ServerUtil>>
  +C<L<Apache::ServerUtil|docs::2.0::api::Apache::ServerUtil>>
   manpage.
   
   =head2 C<Apache::exit()>
  @@ -324,7 +324,7 @@
   argument: status, whose default is 0 (== do nothing).
   
   See the
  -C<L<ModPerl::Util|docs::2.0::api::mod_perl-2.0::ModPerl::Util>>
  +C<L<ModPerl::Util|docs::2.0::api::ModPerl::Util>>
   manpage.
   
   =head2 C<Apache::gensym()>
  @@ -351,7 +351,7 @@
     Apache->server->log_error
   
   instead. See the
  -C<L<Apache::Log|docs::2.0::api::mod_perl-2.0::Apache::Log>> manpage.
  +C<L<Apache::Log|docs::2.0::api::Apache::Log>> manpage.
   
   
   =head1 C<Apache::Server::> Methods and Variables
  @@ -383,7 +383,7 @@
   where the last argument C<$data> is optional, and if supplied will be
   passed as the first argument to the callback function.
   
  -See the C<L<APR::Pool|docs::2.0::api::mod_perl-2.0::APR::Pool>> manpage.
  +See the C<L<APR::Pool|docs::2.0::api::APR::Pool>> manpage.
   
   
   
  @@ -400,7 +400,7 @@
   
   C<$r-E<gt>lookup_file> and C<$r-E<gt>lookup_uri> didn't change their
   functionality but moved into
  -C<L<Apache::SubRequest|docs::2.0::api::mod_perl-2.0::Apache::SubRequest>>.
  +C<L<Apache::SubRequest|docs::2.0::api::Apache::SubRequest>>.
   Before using them, add:
   
     use Apache::SubRequest;
  @@ -408,7 +408,7 @@
   =head2 C<$r-E<gt>get_remote_host>
   
   C<$r-E<gt>get_remote_host> has been renamed and moved into the package
  -C<L<Apache::Connection|docs::2.0::api::mod_perl-2.0::Apache::Connection>>:
  +C<L<Apache::Connection|docs::2.0::api::Apache::Connection>>:
   
     use Apache::Connection;
     $r->connection->get_remote_host();
  @@ -461,7 +461,7 @@
   =back
   
   Instead you should use C<Apache::Request>'s C<params()> and similar
  -methods to do the parsing for you. See the C<L<Apache::Request|docs::2.0::api::mod_perl-2.0::Apache::Request>>
  +methods to do the parsing for you. See the C<L<Apache::Request|docs::2.0::api::Apache::Request>>
   manpage.
   
   XXX: ...when Apache::Request will be ported to 2.0. For now you can
  @@ -523,12 +523,12 @@
   
   C<$r-E<gt>log_reason> is not available in mod_perl 2.0 API. Use the
   other standard logging functions provided by the
  -C<L<Apache::Log|docs::2.0::api::mod_perl-2.0::Apache::Log>>
  +C<L<Apache::Log|docs::2.0::api::Apache::Log>>
   module. For example:
   
     $r->log_error("it works!");
   
  -See the C<L<Apache::Log|docs::2.0::api::mod_perl-2.0::Apache::Log>>
  +See the C<L<Apache::Log|docs::2.0::api::Apache::Log>>
   manpage.
   
   
  @@ -650,32 +650,32 @@
   =head2 C<discard_request_body()>
   
   This function now belongs to the module
  -C<L<Apache::Response|docs::2.0::api::mod_perl-2.0::Apache::Response>>.
  +C<L<Apache::Response|docs::2.0::api::Apache::Response>>.
   
   =head2 C<meets_conditions()>
   
   This function now belongs to the module
  -C<L<Apache::Response|docs::2.0::api::mod_perl-2.0::Apache::Response>>.
  +C<L<Apache::Response|docs::2.0::api::Apache::Response>>.
   
   =head2 C<set_content_length()>
   
   This function now belongs to the module
  -C<L<Apache::Response|docs::2.0::api::mod_perl-2.0::Apache::Response>>.
  +C<L<Apache::Response|docs::2.0::api::Apache::Response>>.
   
   =head2 C<set_etag()>
   
   This function now belongs to the module
  -C<L<Apache::Response|docs::2.0::api::mod_perl-2.0::Apache::Response>>.
  +C<L<Apache::Response|docs::2.0::api::Apache::Response>>.
   
   =head2 C<set_last_modified()>
   
   This function now belongs to the module
  -C<L<Apache::Response|docs::2.0::api::mod_perl-2.0::Apache::Response>>.
  +C<L<Apache::Response|docs::2.0::api::Apache::Response>>.
   
   =head2 C<update_mtime()>
   
   This function now belongs to the module
  -C<L<Apache::Response|docs::2.0::api::mod_perl-2.0::Apache::Response>>.
  +C<L<Apache::Response|docs::2.0::api::Apache::Response>>.
   
   
   
  @@ -691,7 +691,7 @@
   C<Apache::Util::size_string()> has been replaced with
   C<APR::String::format_size()>, which returns formatted strings of only
   4 characters long. See the
  -C<L<APR::String|docs::2.0::api::mod_perl-2.0::APR::String>> manpage.
  +C<L<APR::String|docs::2.0::api::APR::String>> manpage.
   
   =head2 C<Apache::Util::escape_uri()>
   
  
  
  
  1.4       +7 -7      modperl-docs/src/docs/2.0/user/config/custom.pod
  
  Index: custom.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/config/custom.pod,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- custom.pod	13 Dec 2002 17:50:29 -0000	1.3
  +++ custom.pod	27 Jan 2003 04:05:13 -0000	1.4
  @@ -203,7 +203,7 @@
   appear. There are L<several
   constants|/Directive_Scope_Definition_Constants> which map onto the
   corresponding Apache macros. These constants should be imported from
  -the C<L<Apache::Const|docs::2.0::api::mod_perl-2.0::Apache::Const>>
  +the C<L<Apache::Const|docs::2.0::api::Apache::Const>>
   package.
   
   For example, to use the C<OR_ALL> constant, which allows directives to
  @@ -232,7 +232,7 @@
   Apache validate that the number of arguments is valid, the I<args_how>
   attribute should be set to the desired value. Similar to the
   I<L<req_override|/C_req_override_>> attribute, the
  -C<L<Apache::Const|docs::2.0::api::mod_perl-2.0::Apache::Const>>
  +C<L<Apache::Const|docs::2.0::api::Apache::Const>>
   package provides special constants which map to the corresponding
   Apache macros.  There are L<several
   constants|/Directive_Syntax_Definition_Constants> to choose from.
  @@ -406,14 +406,14 @@
   =item 2
   
   C<$parms> is an
  -C<L<Apache::CmdParms|docs::2.0::api::mod_perl-2.0::Apache::CmdParms>>
  +C<L<Apache::CmdParms|docs::2.0::api::Apache::CmdParms>>
   object from which you can retrieve various other information about the
   configuration. For example to retrieve the server object:
   
     my $s = $parms->server;
   
   See
  -C<L<Apache::CmdParms|docs::2.0::api::mod_perl-2.0::Apache::CmdParms>>
  +C<L<Apache::CmdParms|docs::2.0::api::Apache::CmdParms>>
   for more information.
   
   =item 3
  @@ -431,7 +431,7 @@
   The following values of the I<L<args_how|/C_args_how_>> attribute
   define how many arguments and what kind of arguments directives can
   accept. These values are constants that can be imported from the
  -C<L<Apache::Const|docs::2.0::api::mod_perl-2.0::Apache::Const>>
  +C<L<Apache::Const|docs::2.0::api::Apache::Const>>
   package. For example:
   
     use Apache::Const -compile => qw(TAKE1 TAKE23);
  @@ -668,7 +668,7 @@
   each virtual host defined in I<httpd.conf>. It's called with two
   arguments: C<$class>, the package name it was created in and C<$parms>
   the already familiar
  -C<L<Apache::CmdParms|docs::2.0::api::mod_perl-2.0::Apache::CmdParms>>
  +C<L<Apache::CmdParms|docs::2.0::api::Apache::CmdParms>>
   object. The object is expected to return a reference to a blessed
   hash, which will be used by configuration directives callbacks to set
   the values assigned in the configuration file. But it's possible to
  @@ -781,7 +781,7 @@
   
   The only difference in the retrieving the directory configuration
   object. Here the third argument C<$r-E<gt>per_dir_config> tells
  -C<L<Apache::Module|docs::2.0::api::mod_perl-2.0::Apache::Module>> to
  +C<L<Apache::Module|docs::2.0::api::Apache::Module>> to
   get the directory configuration object.
   
   =head3 C<DIR_MERGE>
  
  
  
  1.11      +3 -3      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.10
  retrieving revision 1.11
  diff -u -r1.10 -r1.11
  --- http.pod	10 Jan 2003 04:26:57 -0000	1.10
  +++ http.pod	27 Jan 2003 04:05:13 -0000	1.11
  @@ -466,9 +466,9 @@
   C<L<RUN_ALL|docs::2.0::user::handlers::intro/item_RUN_ALL>>.
   
   The best example here would be to use
  -C<L<Apache::Reload|docs::2.0::api::mod_perl-2.0::Apache::Reload>>
  +C<L<Apache::Reload|docs::2.0::api::Apache::Reload>>
   which takes the benefit of this directive. Usually
  -C<L<Apache::Reload|docs::2.0::api::mod_perl-2.0::Apache::Reload>> is
  +C<L<Apache::Reload|docs::2.0::api::Apache::Reload>> is
   configured as:
   
     PerlInitHandler Apache::Reload
  @@ -489,7 +489,7 @@
         Options +ExecCGI
     </Location>
   
  -C<L<Apache::Reload|docs::2.0::api::mod_perl-2.0::Apache::Reload>> will
  +C<L<Apache::Reload|docs::2.0::api::Apache::Reload>> will
   reload the modified modules, only when a request to the I</devel>
   namespace is issued, because C<L<PerlInitHandler|/PerlInitHandler>>
   plays the role of
  
  
  
  1.3       +1 -1      modperl-docs/src/docs/2.0/user/intro/overview.pod
  
  Index: overview.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/intro/overview.pod,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- overview.pod	23 Dec 2002 23:31:22 -0000	1.2
  +++ overview.pod	27 Jan 2003 04:05:13 -0000	1.3
  @@ -405,7 +405,7 @@
   
   For example this allows mod_perl to inter-operate with the APR IO
   layer and even use the APR IO layer in Perl code. See the
  -C<L<APR::PerlIO|docs::2.0::api::mod_perl-2.0::APR::PerlIO>> manpage.
  +C<L<APR::PerlIO|docs::2.0::api::APR::PerlIO>> manpage.
   
   Another example of using the new feature is the extension of the
   C<open()> functionality to create anonymous temporary files via:
  
  
  
  1.10      +1 -1      modperl-docs/src/docs/2.0/user/intro/start_fast.pod
  
  Index: start_fast.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/intro/start_fast.pod,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- start_fast.pod	15 Dec 2002 17:32:04 -0000	1.9
  +++ start_fast.pod	27 Jan 2003 04:05:13 -0000	1.10
  @@ -123,7 +123,7 @@
   If that didn't work check the I<error_log> file.
   
   For more information on the registry scripts refer to the
  -C<L<ModPerl::Registry|docs::2.0::api::ModPerl-Registry::ModPerl::Registry>>
  +C<L<ModPerl::Registry|docs::2.0::api::ModPerl::Registry>>
   manapage. (XXX: on day there will a tutorial on registry, should port
   it from 1.0's docs).
   
  
  
  

---------------------------------------------------------------------
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