dougm 01/01/02 11:53:13
Added: pod modperl_design.pod
Log:
design doc
Revision Changes Path
1.1 modperl-2.0/pod/modperl_design.pod
Index: modperl_design.pod
===================================================================
=head1 NAME
mod_perl_design - notes on the design and goals of mod_perl-2.0
=head1 SYNOPSIS
perldoc mod_perl_design
=head1 DESCRIPTION
notes on the design and goals of mod_perl-2.0
=head1 The Interpreter Pool
this logic is only enabled if Perl is built with -Dusethreads
otherwise, mod_perl will behave just as 1.xx, using a single
interpreter, which is only useful if you're using the prefork mpm.
when the server is started, a Perl interpreter is constructed, parsing
any code specified in the configuration, just as 1.xx does. this
interpreter is refered to as the "parent" interpreter. then, for
the number of PerlInterpStart configured, a (thread-safe) clone of the
parent interpreter is made (via perl_clone()) and added to a 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:
use CGI ();
use POSIX ();
use IO ();
use SelfLoader ();
use AutoLoader ();
use B::Deparse ();
use B::Terse ();
use B ();
use B::C ();
the parent adds 6M size to the process, each clone adds less than half
that size, ~2.3M, thanks to the shared syntax tree. at request time,
if any Perl*Handlers are configured, an available interpreter is
selected from the pool. as there is a request_rec per thread, a
pointer is saved in either the conn_rec->pool or request_rec->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 is used.
several configuration parameters control the interpreter pool management:
=over 4
=item PerlInterpStart
happens at startup time, the number of intepreters to clone
=item PerlInterpMax
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 Max is reached, mod_perl will block (via
COND_WAIT()) until one becomes available (signaled via COND_SIGNAL())
=item PerlInterpMinSpare
the minimum number of available interpreters this parameter will clone
interpreters up to Max, before a request comes in
=item PerlInterpMaxSpare
mod_perl will throttle down the number of interpreters to this number
as those in use become available
=item PerlInterpMaxRequests
the maximum number of requests an interpreter should serve, the
interpreter is destroyed when the number is reached and replaced with
a fresh one.
=back
=head2 tipool
the interpreter pool is implemented in terms of a "tipool" (thread
item pool), a generic api which can be reused for other data such as
database connections.
=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.
it is also possible to disable mod_perl for a given virtual host.
=head2 Future
at the moment, the interpreter pool is just a proof-of-concept
implementation, to test that requests can be handled concurrently.
the link-list implementation will certainly be optimized. and, some
of the interpreter pool management might be moved into it's own thread.
but the concept of mapping an interpreter clone to a thread will
likely remain.
a "garbage collector", which could also run in it's 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.
=head1 Glue Code and Callbacks
the code for hooking mod_perl in the various phases, including
Perl*Handler directives is generated by the ModPerl::Code module.
when a mod_perl hook is called for a given phase, the glue code has an
index into the array of handlers, so it knows to return DECLINED right
away if no handlers are configured, without entering the Perl runtime
as 1.xx did. the handlers are also now stored in an
ap_array_header_t, which is might lighter and faster than using a Perl
AV, as 1.xx did. and again, 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:
PerlHandler MyModule (defaults to MyModule::handler or MyModule->handler)
PerlHandler MyModule->handler
PerlHandler $MyObject->handler
PerlHandler 'sub { print "foo\n" }'
are only parsed once, unlike 1.xx which parsed everytime 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
threads, as each clone needs its own copy of Perl structures.
a "method handler" is now specifed using the `method' sub attribute,
e.g.
sub handler : method {};
instead of 1.xx's
sub handler ($$) {}
=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.
the current state of the build system is far from complete, but just
enough to build a libmodperl.a or libmodperl.so
see 00README_FIRST if you're interested in giving it a whirl.
=head1 SEE ALSO
perlguts(1), perlembed(1), perlxs(1)
=head1 AUTHOR
Doug MacEachern
