You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by st...@apache.org on 2002/01/16 06:36:53 UTC
cvs commit: modperl-docs/src/docs/2.0/user/design design.pod
stas 02/01/15 21:36:53
Modified: src/docs/2.0/user/design design.pod
Log:
- markup and code spacing corrections
- fixed a few typos
Revision Changes Path
1.3 +77 -72 modperl-docs/src/docs/2.0/user/design/design.pod
Index: design.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/design/design.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- design.pod 9 Jan 2002 18:09:49 -0000 1.2
+++ design.pod 16 Jan 2002 05:36:53 -0000 1.3
@@ -14,13 +14,14 @@
In version 2.0 of mod_perl, the basic concept of 1.x still applies:
- Provide complete access to the Apache C API via the Perl programming language.
+ Provide complete access to the Apache C API
+ via the Perl programming language.
Rather than "porting" mod_perl-1.x to Apache 2.0, mod_perl-2.0 is
being implemented as a complete re-write from scratch.
For a more detailed introduction and functionality overview, see
-I<modperl_2.0>.
+L<Overview|overview/overview/"test">.
=head1 Interpreter Management
@@ -52,7 +53,7 @@
parent interpreter is made (via perl_clone()) and added to the pool of
interpreters. This clone copies any writeable data (e.g. the symbol
table) and shares the compiled syntax tree. From my measurements of a
-startup.pl including a few random modules:
+I<startup.pl> including a few random modules:
use CGI ();
use POSIX ();
@@ -75,7 +76,7 @@
I<request_rec> per thread, a pointer is saved in either the
conn_rec-E<gt>pool or request_rec-E<gt>pool, which will be used for the
lifetime of that request. For handlers that are called when threads
-are not running (PerlChild{Init,Exit}Handler), the parent interpreter
+are not running (C<PerlChild{Init,Exit}Handler>), the parent interpreter
is used. Several configuration directives control the interpreter
pool management:
@@ -89,8 +90,8 @@
If all running interpreters are in use, mod_perl will clone new
interpreters to handle the request, up until this number of
-interpreters is reached. when PerlInterpMax is reached, mod_perl will
-block (via COND_WAIT()) until one becomes available (signaled via
+interpreters is reached. when C<PerlInterpMax> is reached, mod_perl
+will block (via COND_WAIT()) until one becomes available (signaled via
COND_SIGNAL())
=item PerlInterpMinSpare
@@ -122,9 +123,9 @@
=head2 Virtual Hosts
The interpreter management has been implemented in a way such that
-each VirtualHost can have its own parent Perl interpreter and/or MIP
-(Mod_perl Interpreter Pool).
-It is also possible to disable mod_perl for a given virtual host.
+each C<E<lt>VirtualHostE<gt>> can have its own parent Perl interpreter
+and/or MIP (Mod_perl Interpreter Pool). It is also possible to
+disable mod_perl for a given virtual host.
=head2 Further Enhancements
@@ -132,11 +133,11 @@
=item *
-The interpreter pool management could be moved into it's own thread.
+The interpreter pool management could be moved into its own thread.
=item *
-A "garbage collector", which could also run in it's own thread,
+A "garbage collector", which could also run in its own thread,
examining the padlists of idle interpreters and deciding to release
and/or report large strings, array/hash sizes, etc., that Perl is
keeping around as an optimization.
@@ -146,9 +147,9 @@
=head1 Hook Code and Callbacks
The code for hooking mod_perl in the various phases, including
-Perl*Handler directives is generated by the ModPerl::Code module.
-Access to all hooks will be provided by mod_perl in both the
-traditional Perl*Handler configuration fashion and via dynamic
+C<Perl*Handler> directives is generated by the C<ModPerl::Code>
+module. Access to all hooks will be provided by mod_perl in both the
+traditional C<Perl*Handler> configuration fashion and via dynamic
registration methods (the ap_hook_* functions).
When a mod_perl hook is called for a given phase, the glue code has an
@@ -159,17 +160,17 @@
Perl AV, as 1.xx did. And more importantly, keeps us out of the Perl
runtime until we're sure we need to be there.
-Perl*Handlers are now "compiled", that is, the various forms of:
+C<Perl*Handler>s are now "compiled", that is, the various forms of:
PerlResponseHandler MyModule->handler
# defaults to MyModule::handler or MyModule->handler
PerlResponseHandler MyModule
PerlResponseHandler $MyObject->handler
- PerlResponseHandler 'sub { print "foo\n" }'
+ PerlResponseHandler 'sub { print "foo\n"; return OK }'
are only parsed once, unlike 1.xx which parsed every time the handler
-was used. there will also be an option to parse the handlers at
-startup time. note: this feature is currently not enabled with
+was used. There will also be an option to parse the handlers at
+startup time. Note: this feature is currently not enabled with
threads, as each clone needs its own copy of Perl structures.
A "method handler" is now specified using the `method' sub attribute,
@@ -191,13 +192,13 @@
The goal for 2.0 is to generate the majority of xs code and provide
thin wrappers where needed to make the API more Perlish. As part of
this goal, nearly the entire APR and Apache API, along with their
-public data structures will covered from the get-go. Certain
-functions and structures which are considered "private" to Apache or
-otherwise un-useful to Perl will not be glued.
+public data structures is covered from the get-go. Certain functions
+and structures which are considered "private" to Apache or otherwise
+un-useful to Perl don't get glued.
The Apache header tree is parsed into Perl data structures which live
-in the generated I<Apache::FunctionTable> and
-I<Apache::StructureTable> modules. For example, the following
+in the generated C<Apache::FunctionTable> and
+C<Apache::StructureTable> modules. For example, the following
function prototype:
AP_DECLARE(int) ap_meets_conditions(request_rec *r);
@@ -239,7 +240,7 @@
}
Similar is done for the mod_perl source tree, building
-I<ModPerl::FunctionTable> and I<ModPerl::StructureTable>.
+C<ModPerl::FunctionTable> and C<ModPerl::StructureTable>.
Three files are used to drive these Perl structures into the generated
xs code:
@@ -357,23 +358,26 @@
Example of the stream oriented interface:
- #httpd.conf
- PerlOutputFilterHandler Apache::ReverseFilter
-
- #Apache/ReverseFilter.pm
- package Apache::ReverseFilter;
-
- use strict;
-
- sub handler {
- my $filter = shift;
-
- while ($filter->read(my $buffer, 1024)) {
- $filter->write(scalar reverse $buffer);
- }
-
- return Apache::OK;
- }
+ file:httpd.conf
+ ---------------
+ PerlOutputFilterHandler Apache::ReverseFilter
+
+ file:Apache/ReverseFilter.pm
+ ----------------------------
+ package Apache::ReverseFilter;
+
+ use strict;
+
+ sub handler {
+ my $filter = shift;
+
+ while ($filter->read(my $buffer, 1024)) {
+ $filter->write(scalar reverse $buffer);
+ }
+
+ return Apache::OK;
+ }
+ 1;
=head1 Directive Handlers
@@ -407,26 +411,27 @@
=head1 Build System
The biggest mess in 1.xx is mod_perl's Makefile.PL, the majority of
-logic has been broken down and moved to the Apache::Build module.
-The Makefile.PL will construct an Apache::Build object which will have
-all the info it needs to generate scripts and Makefiles that
-apache-2.0 needs. Regardless of what that scheme may be or change to,
-it will be easy to adapt to with build logic/variables/etc., divorced
-from the actual Makefiles and configure scripts. In fact, the new
-build will stay as far away from the Apache build system as possible.
-The module library (libmodperl.so or libmodperl.a) is built with as
-little help from Apache as possible, using only the B<INCLUDEDIR>
-provided by I<apxs>.
+logic has been broken down and moved to the C<Apache::Build> module.
+The I<Makefile.PL> will construct an C<Apache::Build> object which
+will have all the info it needs to generate scripts and I<Makefile>s
+that apache-2.0 needs. Regardless of what that scheme may be or
+change to, it will be easy to adapt to with build
+logic/variables/etc., divorced from the actual I<Makefile>s and
+configure scripts. In fact, the new build will stay as far away from
+the Apache build system as possible. The module library
+(I<libmodperl.so> or I<libmodperl.a>) is built with as little help
+from Apache as possible, using only the C<INCLUDEDIR> provided by
+I<apxs>.
The new build system will also "discover" XS modules, rather than
hard-coding the XS module names. This allows for switchabilty between
static and dynamic builds, no matter where the xs modules live in the
source tree. This also allows for third-party xs modules to be
unpacked inside the mod_perl tree and built static without
-modification the mod_perl Makefiles.
+modification to the mod_perl Makefiles.
-For platforms such as Win32, the build files will be generated
-similar to how unix-flavor Makefiles are.
+For platforms such as Win32, the build files will be generated similar
+to how unix-flavor I<Makefile>s are.
=head1 Test Framework
@@ -434,18 +439,18 @@
exercise as many areas of the API and module features as possible.
The test framework in 1.x, like several other areas of mod_perl, was
-cobbled together over the years. The goal of 2.0 is to provide a
-test framework that will be usable not only for mod_perl, but for
-third-party Apache::* modules and Apache itself.
+cobbled together over the years. The goal of 2.0 is to provide a test
+framework that will be usable not only for mod_perl, but for
+third-party C<Apache::*> modules and Apache itself.
=head1 CGI Emulation
-As a side-effect of embedding Perl inside Apache and caching
-compiled code, mod_perl has been popular as a CGI accelerator. In
-order to provide a CGI-like environment, mod_perl must manage areas of
-the runtime which have a longer lifetime than when running under
-mod_cgi. For example, the B<%ENV> environment variable table, B<END>
-blocks, B<@INC> include paths, etc.
+As a side-effect of embedding Perl inside Apache and caching compiled
+code, mod_perl has been popular as a CGI accelerator. In order to
+provide a CGI-like environment, mod_perl must manage areas of the
+runtime which have a longer lifetime than when running under mod_cgi.
+For example, the C<%ENV> environment variable table, C<END> blocks,
+C<@INC> include paths, etc.
CGI emulation will be supported in 2.0, but done so in a way that it
is encapsulated in its own handler. Rather that 1.x which uses the
@@ -478,12 +483,12 @@
around 255 bytes, including the symbol table entry. Multiply that
number times, say 1200, is around 300K, times 10 interpreter clones,
we have 3Mb, times 20 clones, 6Mb, and so on. Pure perl subroutines
-must be copied, as the structure includes the B<PADLIST> of lexical
+must be copied, as the structure includes the C<PADLIST> of lexical
variables used within that subroutine. However, for XSUBs, there is
no PADLIST, which means that in the general case, perl_clone() will
copy the subroutine, but the structure will never be written to at
-runtime. Other common global variables, such as B<@EXPORT> and
-B<%EXPORT_OK> are built at compile time and never modified during
+runtime. Other common global variables, such as C<@EXPORT> and
+C<%EXPORT_OK> are built at compile time and never modified during
runtime.
Clearly it would be a big win if XSUBs and such global variables were
@@ -491,13 +496,13 @@
structures for performance reasons. Perl already supports the concept
of a read-only variable, a flag which is checked whenever a Perl variable
will be written to. A patch has been submitted to the Perl
-development track to support a feature known as B<GvSHARED>. This
+development track to support a feature known as C<GvSHARED>. This
mechanism allows XSUBs and global variables to be marked as shared, so
perl_clone() will not copy these structures, but rather point to them.
=head2 Shared SvPVX
-The string slot of a Perl scalar is known as the B<SvPVX>. As Perl
+The string slot of a Perl scalar is known as the C<SvPVX>. As Perl
typically manages the string a variable points to, it must make a copy
of it. However, it is often the case that these strings are never
written to. It would be possible to implement copy-on-write strings
@@ -514,8 +519,8 @@
my Apache::Request $r = shift;
-Tells the Perl compiler to expect an object in the I<Apache::Request>
-class to be assigned to B<$r>. A patch has already been submitted to
+Tells the Perl compiler to expect an object in the C<Apache::Request>
+class to be assigned to C<$r>. A patch has already been submitted to
use this information so method calls can be resolved at compile time.
However, the implementation does not take into account sub-classing of
the typed object. Since the mod_perl API consists mainly of methods,
@@ -559,8 +564,8 @@
which is global across all interpreters. Such a feature would of
course require mutex locking, something we do not want to introduce
for normal Perl variables. It might be possible to again piggy-back
-the B<SvREADONLY> flag, which if true, checking for another flag
-B<SvSOLAR> which implements the proper locking for concurrent access
+the C<SvREADONLY> flag, which if true, checking for another flag
+C<SvSOLAR> which implements the proper locking for concurrent access
to cross-interpreter globals.
=head1 Maintainers
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org