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 {[...]}, [EMAIL PROTECTED]);
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, [EMAIL PROTECTED]
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, [EMAIL
PROTECTED]);
$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, [EMAIL PROTECTED]);
($in_fh, $out_fh, $err_fh) =
Apache::SubProcess::spawn_proc_prog($r, $command, [EMAIL PROTECTED]);
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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
