EVOLUTION-MANAGER

Edit File: design.pod

=head1 NAME Notes on the design and goals of mod_perl-2.0 =head1 Description Notes on the design and goals of mod_perl-2.0. We try to keep this doc in sync with the development, so some items discussed here were already implemented, while others are only planned. If you find some inconsistencies in this document please let the list know. =head1 Introduction In version 2.0 of mod_perl, the basic concept of 1.0 still applies: Provide complete access to the Apache C API via the Perl programming language. Rather than "porting" mod_perl-1.0 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 L<Overview|docs::2.0::user::intro::overview>. =head1 Interpreter Management In order to support mod_perl in a multi-threaded environment, mod_perl-2.0 will take advantage of Perl's I<ithreads> feature, new to Perl version 5.6.0. This feature encapsulates the Perl runtime inside a thread-safe I<PerlInterpreter> structure. Each thread which needs to serve a mod_perl request will need its own I<PerlInterpreter> instance. Rather than create a one-to-one mapping of I<PerlInterpreter> per-thread, a configurable pool of interpreters is managed by mod_perl. This approach will cut down on memory usage simply by maintaining a minimal number of intepreters. It will also allow re-use of allocations made within each interpreter by recycling those which have already been used. This was not possible in the 1.3.x model, where each child has its own interpreter and no control over which child Apache dispatches the request to. The interpreter pool is only enabled if Perl is built with -Dusethreads otherwise, mod_perl will behave just as 1.0, using a single interpreter, which is only useful when Apache is configured with the prefork mpm. When the server is started, a Perl interpreter is constructed, compiling any code specified in the configuration, just as 1.0 does. This interpreter is referred to as the "parent" interpreter. Then, for the number of I<PerlInterpStart> configured, a (thread-safe) clone of the 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 I<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. NOTE: These measurements were made prior to finding memory leaks related to perl_clone() in 5.6.0 and the GvSHARED optimization. At request time, If any Perl*Handlers are configured, an available interpreter is selected from the pool. As there is a I<conn_rec> and 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 (C<PerlChild{Init,Exit}Handler>), the parent interpreter is used. Several configuration directives control the interpreter pool management: =over 4 =item PerlInterpStart The number of intepreters to clone at startup time. =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 C<PerlInterpMax> 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 C<PerlInterpMax>, 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. A Perl interface will be provided for the I<TIPool> mechanism, which, for example, will make it possible to share a pool of DBI connections. =head2 Virtual Hosts The interpreter management has been implemented in a way such that 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 =over 4 =item * The interpreter pool management could be moved into its own thread. =item * 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. =back =head1 Hook Code and Callbacks The code for hooking mod_perl in the various phases, including 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 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.0 did. The handlers are also now stored in an apr_array_header_t, which is much lighter and faster than using a Perl AV, as 1.0 did. And more importantly, keeps us out of the Perl runtime until we're sure we need to be there. 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"; return OK }' are only parsed once, unlike 1.0 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 threads, as each clone needs its own copy of Perl structures. A "method handler" is now specified using the `method' sub attribute, e.g. sub handler : method {}; instead of 1.0's sub handler ($$) {} =head1 Perl interface to the Apache API and Data Structures In 1.0, the Perl interface back into the Apache API and data structures was done piecemeal. As functions and structure members were found to be useful or new features were added to the Apache API, the xs code was written for them here and there. 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 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 C<Apache2::FunctionTable> and C<Apache2::StructureTable> modules. For example, the following function prototype: AP_DECLARE(int) ap_meets_conditions(request_rec *r); is parsed into the following Perl structure: { 'name' => 'ap_meets_conditions' 'return_type' => 'int', 'args' => [ { 'name' => 'r', 'type' => 'request_rec *' } ], }, and the following structure: typedef struct { uid_t uid; gid_t gid; } ap_unix_identity_t; is parsed into: { 'type' => 'ap_unix_identity_t' 'elts' => [ { 'name' => 'uid', 'type' => 'uid_t' }, { 'name' => 'gid', 'type' => 'gid_t' } ], } Similar is done for the mod_perl source tree, building C<ModPerl::FunctionTable> and C<ModPerl::StructureTable>. Three files are used to drive these Perl structures into the generated xs code: =over 4 =item lib/ModPerl/function.map Specifies which functions are made available to Perl, along with which modules and classes they reside in. Many functions will map directly to Perl, for example the following C code: static int handler (request_rec *r) { int rc = ap_meets_conditions(r); ... maps to Perl like so: sub handler { my $r = shift; my $rc = $r->meets_conditions; ... The function map is also used to dispatch Apache/APR functions to thin wrappers, rewrite arguments and rename functions which make the API more Perlish where applicable. For example, C code such as: char uuid_buf[APR_UUID_FORMATTED_LENGTH+1]; apr_uuid_t uuid; apr_uuid_get(&uuid) apr_uuid_format(uuid_buf, &uuid); printf("uuid=%s\n", uuid_buf); is remapped to a more Perlish convention: printf "uuid=%s\n", APR::UUID->new->format; =item lib/ModPerl/structure.map Specifies which structures and members of each are made available to Perl, along with which modules and classes they reside in. =item lib/ModPerl/type.map This file defines how Apache/APR types are mapped to Perl types and vice-versa. For example: apr_int32_t => SvIV apr_int64_t => SvNV server_rec => SvRV (Perl object blessed into the Apache2::ServerRec class) =back =head2 Advantages to generating XS code =over 4 =item * Not tied tightly to xsubpp =item * Easy adjustment to Apache 2.0 API/structure changes =item * Easy adjustment to Perl changes (e.g., Perl 6) =item * Ability to "discover" hookable third-party C modules. =item * Cleanly take advantage of features in newer Perls =item * Optimizations can happen across-the-board with one-shot =item * Possible to AUTOLOAD XSUBs =item * Documentation can be generated from code =item * Code can be generated from documentation =back =head2 Lvalue methods A new feature to Perl 5.6.0 is I<lvalue subroutines>, where the return value of a subroutine can be directly modified. For example, rather than the following code to modify the uri: $r->uri($new_uri); the same result can be accomplished with the following syntax: $r->uri = $new_uri; mod_perl-2.0 will support I<lvalue subroutines> for all methods which access Apache and APR data structures. =head1 Filter Hooks mod_perl 2.0 provides two interfaces to filtering, a direct mapping to buckets and bucket brigades and a simpler, stream-oriented interface. This is discussed in the L<Chapter on filters|docs::2.0::user::handlers::filters>. =head1 Directive Handlers mod_perl 1.0 provides a mechanism for Perl modules to implement first-class directive handlers, but requires an XS file to be generated and compiled. The 2.0 version provides the same functionality, but does not require the generated XS module (i.e. everything is implemented in pure Perl). =head1 E<lt>PerlE<gt> Configuration Sections The ability to write configuration in Perl carries over from 1.0, but but implemented much different internally. The mapping of a Perl symbol table fits cleanly into the new I<ap_directive_t> API, unlike the hoop jumping required in mod_perl 1.0. =head1 Protocol Module Support L<Protocol module|docs::2.0::user::handlers::protocols> support is provided out-of-the-box, as the hooks and API are covered by the generated code blankets. Any functionality for assisting protocol modules should be folded back into Apache if possible. =head1 mod_perl MPM It will be possible to write an MPM (Multi-Processing Module) in Perl. mod_perl will provide a mod_perl_mpm.c framework which fits into the server/mpm standard convention. The rest of the functionality needed to write an MPM in Perl will be covered by the generated xs code blanket. =head1 Build System The biggest mess in 1.0 is mod_perl's Makefile.PL, the majority of logic has been broken down and moved to the C<Apache2::Build> module. The I<Makefile.PL> will construct an C<Apache2::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 to the mod_perl Makefiles. For platforms such as Win32, the build files are generated similar to how unix-flavor I<Makefile>s are. =head1 Test Framework Similar to 1.0, mod_perl-2.0 provides a 'make test' target to exercise as many areas of the API and module features as possible. The test framework in 1.0, like several other areas of mod_perl, was cobbled together over the years. mod_perl 2.0 provides a test framework that is usable not only for mod_perl, but for third-party C<Apache2::*> modules and Apache itself. See C<L<Apache::Test|docs::general::testing::testing>>. =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 C<%ENV> environment variable table, C<END> blocks, C<@INC> include paths, etc. CGI emulation is supported in mod_perl 2.0, but done so in a way that it is encapsulated in its own handler. Rather than 1.0 which uses the same response handler, regardless if the module requires CGI emulation or not. With an I<ithreads> enabled Perl, it's also possible to provide more robust namespace protection. Notice that C<ModPerl::Registry> is used instead of 1.0's C<Apache::Registry>, and similar for other registry groups. C<ModPerl::RegistryCooker> makes it easy to write your own customizable registry handler. =head1 Apache2::* Library The majority of the standard C<Apache2::*> modules in 1.0 are supported in 2.0. The main goal being that the non-core CGI emulation components of these modules are broken into small, re-usable pieces to subclass Apache::Registry like behavior. =head1 Perl Enhancements Most of the following items were projected for inclusion in perl 5.8.0, but that didn't happen. While these enhancements do not preclude the design of mod_perl-2.0, they could make an impact if they were implemented/accepted into the Perl development track. =head2 GvSHARED (Note: This item wasn't implemented in Perl 5.8.0) As mentioned, the perl_clone() API will create a thread-safe interpreter clone, which is a copy of all mutable data and a shared syntax tree. The copying includes subroutines, each of which take up 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 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 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 not copied. However, we do not want to introduce locking of these 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 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 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 in the Perl core with little performance overhead. =head2 Compile-time method lookups A known disadvantage to Perl method calls is that they are slower than direct function calls. It is possible to resolve method calls at compile time, rather than runtime, making method calls just as fast as subroutine calls. However, there is certain information required for method look ups that are only known at runtime. To work around this, compile-time hints can be used, for example: my Apache2::Request $r = shift; Tells the Perl compiler to expect an object in the C<Apache2::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, it would be advantageous to re-visit the patch to find an acceptable solution. =head2 Memory management hooks Perl has its own memory management system, implemented in terms of I<malloc> and I<free>. As an optimization, Perl will hang onto allocations made for variables, for example, the string slot of a scalar variable. If a variable is assigned, for example, a 5k chunk of HTML, Perl will not release that memory unless the variable is explicitly I<undef>ed. It would be possible to modify Perl in such a way that the management of these strings are pluggable, and Perl could be made to allocate from an APR memory pool. Such a feature would maintain the optimization Perl attempts (to avoid malloc/free), but would greatly reduce the process size as pool resources are able to be re-used elsewhere. =head2 Opcode hooks Perl already has internal hooks for optimizing opcode trees (syntax tree). It would be quite possible for extensions to add their own optimizations if these hooks were plugable, for example, optimizing calls to I<print>, so they directly call the Apache I<ap_rwrite> function, rather than proxy via a I<tied filehandle>. Another optimization that was implemented is "inlined" XSUB calls. Perl has a generic opcode for calling subroutines, one which does not know the number of arguments coming into and being passed out of a subroutine. As the majority of mod_perl API methods have known in/out argument lists, mod_perl implements a much faster version of the Perl I<pp_entersub> routine. =head1 Maintainers Maintainer is the person(s) you should contact with updates, corrections and patches. Doug MacEachern E<lt>dougm (at) covalent.netE<gt> =head1 Authors =over =item * Doug MacEachern E<lt>dougm (at) covalent.netE<gt> =back Only the major authors are listed above. For contributors see the Changes file. =cut