stas 02/01/09 10:09:49
Modified: src/docs/2.0/devel/help help.pod
src/docs/2.0/user/config config.pod
src/docs/2.0/user/design design.pod
src/docs/2.0/user/overview overview.pod
Log:
- lots of typos and pod markup fixes
Revision Changes Path
1.4 +2 -1 modperl-docs/src/docs/2.0/devel/help/help.pod
Index: help.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/help/help.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- help.pod 31 Dec 2001 10:33:02 -0000 1.3
+++ help.pod 9 Jan 2002 18:09:49 -0000 1.4
@@ -147,6 +147,7 @@
=item *
+=back
=head2 Apache Portable Runtime (APR)
@@ -211,7 +212,7 @@
=back
-
+=cut
1.3 +1 -1 modperl-docs/src/docs/2.0/user/config/config.pod
Index: config.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/config/config.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- config.pod 27 Dec 2001 11:51:54 -0000 1.2
+++ config.pod 9 Jan 2002 18:09:49 -0000 1.3
@@ -154,7 +154,7 @@
=item GlobalRequest
-Setup the global request_rec for use with Apache->request
+Setup the global request_rec for use with Apache-E<gt>request
=item ParseHeaders
1.2 +7 -7 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- design.pod 27 Dec 2001 12:02:47 -0000 1.1
+++ design.pod 9 Jan 2002 18:09:49 -0000 1.2
@@ -73,7 +73,7 @@
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->pool or request_rec->pool, which will be used for 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
is used. Several configuration directives control the interpreter
@@ -161,11 +161,11 @@
Perl*Handlers 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 MyModule->handler
+ # defaults to MyModule::handler or MyModule->handler
+ PerlResponseHandler MyModule
+ PerlResponseHandler $MyObject->handler
+ PerlResponseHandler 'sub { print "foo\n" }'
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
@@ -382,7 +382,7 @@
generated and compiled. The 2.0 version will provide the same
functionality, but will not require the generated xs module.
-=head1 <Perl> Configuration Sections
+=head1 E<lt>PerlE<gt> Configuration Sections
The ability to write configuration in Perl will carry over from 1.x,
but will likely be implemented much different internally. The mapping
1.2 +594 -591 modperl-docs/src/docs/2.0/user/overview/overview.pod
Index: overview.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/overview/overview.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- overview.pod 27 Dec 2001 12:02:47 -0000 1.1
+++ overview.pod 9 Jan 2002 18:09:49 -0000 1.2
@@ -11,28 +11,28 @@
more and more difficult to maintain, in large part to provide
compatibility between the many different flavors of Apache and Perl.
And, compatibility across these versions and flavors is a more
-diffcult goal for mod_perl to reach that a typical Apache or Perl
+difficult goal for mod_perl to reach that a typical Apache or Perl
module, since mod_perl reaches a bit deeper into the corners of Apache
and Perl internals than most. Discussions of the idea to rewrite
-mod_perl as version 2.0 started in 1998, but never made it much further
-than an idea. When Apache 2.0 development was underway it became
-clear that a rewrite of mod_perl would be required to adjust to the
-new Apache architechure and API.
+mod_perl as version 2.0 started in 1998, but never made it much
+further than an idea. When Apache 2.0 development was underway it
+became clear that a rewrite of mod_perl would be required to adjust to
+the new Apache architecture and API.
Of the many changes happening in Apache 2.0, the one which has the
-most impact on mod_perl is the introduction of threads to the overall
-design. Threads have been a part of Apache on the win32 side since
-the Apache port was introduced. The mod_perl port to win32 happened
-in verison 1.00b1, released in June of 1997. This port enabled
-mod_perl to compile and run in a threaded windows environment, with
-one major caveat: only one concurrent mod_perl request could be
-handled at any given time. This was due to the fact that Perl did not
+most significant impact on mod_perl is the introduction of threads to
+the overall design. Threads have been a part of Apache on the win32
+side since the Apache port was introduced. The mod_perl port to win32
+happened in version 1.00b1, released in June of 1997. This port
+enabled mod_perl to compile and run in a threaded windows environment,
+with one major caveat: only one concurrent mod_perl request could be
+handled at any given time. This was due to the fact that Perl did not
introduce thread safe interpreters until version 5.6.0, released in
-March of 2000. Contrary to popular belief, the "thread support"
+March of 2000. Contrary to popular belief, the "threads support"
implemented in Perl 5.005 (released July 1998), did not make Perl
-thread safe internally. Well before that version, Perl had the notion
-of "Multiplicity", which allowed multiple interpreter instances in the
-same process. However, these instances were not thread safe, that is,
+thread-safe internally. Well before that version, Perl had the notion
+of "Multiplicity", which allowed multiple interpreter instances in the
+same process. However, these instances were not thread safe, that is,
concurrent callbacks into multiple interpreters were not supported.
It just so happens that the release of Perl 5.6.0 was nearly at the
@@ -46,27 +46,29 @@
implementation based on lessons learned over the 4.5 years since
mod_perl was introduced.
-This paper and talk assume basic knowlege of mod_perl 1.xx features
-and will focus only the differences mod_perl-2.00 will bring.
+This document assumes basic knowlege of mod_perl-1.x features and will
+focus only the differences mod_perl-2.0 will bring.
-Note 1: The Apache and mod_perl APIs mentioned in this paper are both in
-an "alpha" state and subject to change.
+Note 1: The Apache and mod_perl APIs mentioned in this document are
+both in an "alpha" state and subject to change.
-Note 2: Some of the mod_perl APIs mentioned in this paper do not even
-exist and are subject to be implemented, in which case you would be
-redirected to "Note 1".
+Note 2: Some of the mod_perl APIs mentioned in this document do not
+even exist and are subject to be implemented, in which case you would
+be redirected to "Note 1".
=head1 Apache 2.0 Summary
Note: This section will give you a brief overview of the changes in
-Apache 2.0, just enough to understand where mod_perl will fit in. For
-more details on Apache 2.0 consult the papers by Ryan Bloom.
+Apache 2.0, just enough to understand where mod_perl-2.0 fits in. For
+more details on Apache 2.0 consult the documents by Ryan Bloom.
+
+META: URLs?
=head2 MPMs - Multi-Processing Model Modules
In Apache 1.3.x concurrent requests were handled by multiple
processes, and the logic to manage these processes lived in one place,
-I<http_main.c>, 7200 some odd lines of code. If Apache 1.3.x is
+I<http_main.c>, 7700 some odd lines of code. If Apache 1.3.x is
compiled on a Win32 system large parts of this source file are
redefined to handle requests using threads. Now suppose you want to
change the way Apache 1.3.x processes requests, say, into a DCE RPC
@@ -75,11 +77,11 @@
with a C<-DSTANDALONE_MAIN=your_function> compile time flag.
Neither of which is a clean, modular mechanism.
-Apache-2.0 solves this problem by intoducing I<Multi Processing Model
+Apache-2.0 solves this problem by introducing I<Multi Processing Model
modules>, better known as I<MPMs>. The task of managing incoming
requests is left to the MPMs, shrinking I<http_main.c> to less than
500 lines of code. Several MPMs are included with Apache 2.0 in the
-I<src/modules/mpm> directory:
+I<server/mpm> directory:
=over 4
@@ -88,22 +90,23 @@
The I<prefork> module emulates 1.3.x's preforking model, where each
request is handled by a different process.
-=item threaded
+=item worker
-This MPMs implements a hybrid multi-process multi-threaded
-approach based on the I<pthreads> standard.
+This MPMs implements a hybrid multi-process multi-threaded approach
+based on the I<pthreads> standard. It uses one acceptor thread,
+multiple worker threads.
-=item os2/winnt/beos
+=item spmt_os2, mpmt_os2, netware, win32 and beos
These MPMs also implement the hybrid multi-process/multi-threaded
model, with each based on native OS thread implementations.
=item perchild
-The I<perchild> MPM is similar to the I<threaded> MPM, but is extended
+The I<perchild> MPM is similar to the I<worker> MPM, but is extended
with a mechanism which allows mapping of requests to virtual hosts to
-a process running under the user id and group configured for that host.
-This provides a robust replacement for the I<suexec> mechanism.
+a process running under the user id and group configured for that
+host. This provides a robust replacement for the I<suexec> mechanism.
=back
@@ -112,33 +115,33 @@
Apache 1.3.x has been ported to a very large number of platforms
including various flavors of unix, win32, os/2, the list goes on.
However, in 1.3.x there was no clear-cut, pre-designed portability
-layer for third-party modules to take advantage of. APR provides this
-API layer in a very clean way. For mod_perl, APR will assist a great
-deal with portability. Combined with the portablity of Perl, mod_perl-2.0
-needs only to implement a portable build system, the rest comes "for free".
-A Perl interface will be provided for certain areas of APR, such as
-the shared memory abstraction, but the majority of APR will be used by
-mod_perl "under the covers".
+layer for third-party modules to take advantage of. APR provides this
+API layer in a very clean way. APR assists a great deal with mod_perl
+portability. Combined with the portablity of Perl, mod_perl-2.0 needs
+only to implement a portable build system, the rest comes "for free".
+A Perl interface is provided for certain areas of APR, such as the
+shared memory abstraction, but the majority of APR is used by mod_perl
+"under the covers".
=head2 New Hook Scheme
In Apache 1.3, modules were registered using the I<module> structure,
normally static to I<mod_foo.c>. This structure contains pointers to
-the command table, config create/merge functions, response handler
-table and function pointers for all of the other hooks, such as
-I<child_init> and I<check_user_id>. In 2.0, this structure has been
-pruned down to the first three items mention and a new function
-pointer added called I<register_hooks>. It is the job of
-I<register_hooks> to register functions for all other hooks (such as
-I<child_init> and I<check_user_id>). Not only is hook registration
-now dynamic, it is also possible for modules to register more than one
-function per hook, unlike 1.3. The new hook mechanism also makes it
-possible to sort registered functions, unlike 1.3 with function
-pointers hardwired into the module structure, and each module
+the command table, configuration creation and merging functions,
+response handler table and function pointers for all of the other
+hooks, such as I<child_init> and I<check_user_id>. In Apache 2.0,
+this structure has been pruned down to the first three items mentioned
+and a new function pointer added called I<register_hooks>. It is the
+job of I<register_hooks> to register functions for all other hooks
+(such as I<child_init> and I<check_user_id>). Not only is hook
+registration now dynamic, it is also possible for modules to register
+more than one function per hook, unlike 1.3. The new hook mechanism
+also makes it possible to sort registered functions, unlike 1.3 with
+function pointers hardwired into the module structure, and each module
structure into a linked list. Order in 1.3 depended on this list,
-which was possible to order using compile-time and configuration-time
+which was possible to order using compile-time and startup-time
configuration, but that was left to the user. Whereas in 2.0, the
-add_hook functions accept an order preference parameter, those
+I<add_hook> functions accept an order preference parameter, those
commonly used are:
=over 4
@@ -151,24 +154,25 @@
=back
-For mod_perl, dynamic registration provides a cleaner way to bypass the
-I<Perl*Handler> configuration. By simply adding this configuration:
+For mod_perl, dynamic registration provides a cleaner way to bypass
+the C<Perl*Handler> configuration directives. By simply adding this
+configuration:
- PerlModule Apache::Foo
+ PerlModule Apache::Foo
-I<Apache/Foo.pm> can register hooks itself at server startup:
+C<Apache::Foo> can register hooks itself at server startup:
- Apache::Hook->add(PerlAuthenHandler => \&authenticate,
Apache::Hook::MIDDLE);
- Apache::Hook->add(PerlLogHandler => \&logger, Apache::Hook::LAST);
+ Apache::Hook->add(PerlAuthenHandler => \&authenticate,
Apache::Hook::MIDDLE);
+ Apache::Hook->add(PerlLogHandler => \&logger, Apache::Hook::LAST);
However, this means that Perl subroutines registered via this
-mechanism will be called for *every* request. It will be left to that
-subroutine to decide if it was to handle or decline the given phase.
-As there is overhead in entering the Perl runtime, it will most likely
-be to your advantage to continue using I<Perl*Handler> configuration
-to reduce this overhead. If it is the case that your I<Perl*Handler>
-should be invoked for every request, the hook registration mechanism
-will save some configuration keystrokes.
+mechanism will be called for B<every> request. It will be left to
+that subroutine to decide if it was to handle or decline the given
+phase. As there is overhead in entering the Perl runtime, it will
+most likely be to your advantage to continue using C<Perl*Handler>
+configuration directives to reduce this overhead. If it is the case
+that your C<Perl*Handler> should be invoked for every request, the
+hook registration mechanism will save some configuration keystrokes.
=head2 Configuration Tree
@@ -178,33 +182,33 @@
first parsed into a tree structure, which is then walked to pass data
down to the modules. This tree is then left in memory with an API for
accessing it at request time. The tree can be quite useful for other
-modules. For example, in 1.3, mod_info has it's own configuration
+modules. For example, in 1.3, mod_info has its own configuration
parser and parses the configuration files each time you access it.
With 2.0 there is already a parse tree in memory, which mod_info can
-then walk to output it's information.
+then walk to output its information.
If a mod_perl 1.xx module wants access to configuration information,
-there are two approaches. A module can "subclass" directive handlers,
-saving a copy of the data for itself, then returning B<DECLINE_CMD> so
+there are two approaches. A module can "subclass" directive handlers,
+saving a copy of the data for itself, then returning B<DECLINE_CMD> so
the other modules are also handed the info. Or, the
-C<$Apache::Server::SaveConfig> variable can be set to save <Perl>
-configuration in the C<%Apache::ReadConfig::> namespace. Both methods
-are rather kludgy, version 2.0 will provide a Perl interface to the
-Apache configuration tree.
+C<$Apache::Server::SaveConfig> variable can be set to save
+E<lt>PerlE<gt> configuration in the C<%Apache::ReadConfig::>
+namespace. Both methods are rather kludgy, version 2.0 will provide a
+Perl interface to the Apache configuration tree.
=head2 Filtering
Filtering of Perl modules output has been possible for years since
-tied filehandle support was added to Perl. There are several modules,
-such as I<Apache::Filter> and I<Apache::OutputChain> which have been
-written to provide mechanisms for filtering the C<STDOUT> "stream".
-There are several of these modules because no one approach has quite
+tied filehandle support was added to Perl. There are several modules,
+such as C<Apache::Filter> and C<Apache::OutputChain> which have been
+written to provide mechanisms for filtering the C<STDOUT> stream.
+There are several of these modules because no one's approach has quite
been able to offer the ease of use one would expect, which is due
simply to limitations of the Perl tied filehandle design. Another
problem is that these filters can only filter the output of other Perl
modules. C modules in Apache 1.3 send data directly to the client and
there is no clean way to capture this stream. Apache 2.0 has solved
-this problem by introducing a filtering API. With the baseline i/o
+this problem by introducing a filtering API. With the baseline I/O
stream tied to this filter mechansim, any module can filter the output
of any other module, with any number of filters in between.
@@ -213,7 +217,7 @@
Apache 1.3 is hardwired to speak only one protocol, HTTP. Apache 2.0
has moved to more of a "server framework" architecture making it
possible to plugin handlers for protocols other than HTTP. The
-protocol module design also abstracts the transport layer so protocols
+protocol module design also abstracts the transport layer so protocols
such as SSL can be hooked into the server without requiring
modifications to the Apache source code. This allows Apache to be
extended much further than in the past, making it possible to add
@@ -227,32 +231,33 @@
=head2 Perl 5.6
Thread safe Perl interpreters, also known as "ithreads" (Intepreter
-Threads) provide the mechanism need for mod_perl to adapt to the
-Apache 2.0 thread architecture. This mechanism is a compile time
+Threads) provide the mechanism needed for mod_perl to adapt to the
+Apache 2.0 threads architecture. This mechanism is a compile time
option which encapsulates the Perl runtime inside of a single
-I<PerlInterpreter> structure. With each interpreter instance
+C<PerlInterpreter> structure. With each interpreter instance
containing its own symbol tables, stacks and other Perl runtime
mechanisms, it is possible for any number of threads in the same
process to concurrently callback into Perl. This of course requires
-each thread to have it's own I<PerlInterpreter> object, or at least
+each thread to have its own C<PerlInterpreter> object, or at least
that each instance is only access by one thread at any given time.
-mod_perl-1.xx has only a single I<PerlInterpreter>, which is
+mod_perl-1.xx has only a single C<PerlInterpreter>, which is
contructed by the parent process, then inherited across the forks to
child processes. mod_perl-2.0 has a configurable number of
-I<PerlInterpreters> and two classes of interpreters, I<parent> and
+C<PerlInterpreters> and two classes of interpreters, I<parent> and
I<clone>. A I<parent> is like that in 1.xx, the main interpreter
-created at startup time which compiles any pre-loaded Perl code.
-A I<clone> is created from the parent using the Perl API
-I<perl_clone()> function. At request time, I<parent> interpreters are
-only used for making more I<clones>, as they are the interpreters
-which actually handle requests. Care is taken by Perl to copy only
-mutable data, which means that no runtime locking is required and
-read-only data such as the syntax tree is shared from the I<parent>.
+created at startup time which compiles any pre-loaded Perl code. A
+I<clone> is created from the parent using the Perl API I<perl_clone()>
+function. At request time, I<parent> interpreters are only used for
+making more I<clones>, as the I<clones> are the interpreters which
+actually handle requests. Care is taken by Perl to copy only mutable
+data, which means that no runtime locking is required and read-only
+data such as the syntax tree is shared from the I<parent>, which
+should reduce the overall mod_perl memory footprint.
=head2 New mod_perl Directives for Threaded MPMs
-Rather than create a I<PerlInterperter> per-thread by default,
+Rather than create a C<PerlInterperter> per-thread by default,
mod_perl creates a pool of interpreters. The pool mechanism helps cut
down memory usage a great deal. As already mentioned, the syntax tree
is shared between all cloned interpreters. If your server is serving
@@ -317,17 +322,17 @@
By default, an interpreter will be held for the lifetime of the
request, equivalent to this configuration:
- PerlInterpScope request
+ PerlInterpScope request
For example, if a PerlAccessHandler is configured, an interpreter will
-selected before it is run and not released until after the logging
+be selected before it is run and not released until after the logging
phase.
Intepreters will be shared across subrequests by default, however, it
is possible configure the intepreter scope to be per-subrequest on
a per-directory basis:
- PerlInterpScope subrequest
+ PerlInterpScope subrequest
With this configuration, an autoindex generated page for example would
select an interpreter for each item in the listing that is configured
@@ -335,7 +340,7 @@
It is also possible to configure the scope to be per-handler:
- PerlInterpScope handler
+ PerlInterpScope handler
With this configuration, an interpreter will be selected before
PerlAccessHandlers are run, and putback immediately afterwards, before
@@ -351,7 +356,7 @@
maintain state for the lifetime of an ftp connection, it is possible
to do so on a per-virtualhost basis:
- PerlInterpScope connection
+ PerlInterpScope connection
=back
@@ -375,12 +380,12 @@
=head1 Thread Item Pool API
As we discussed, mod_perl implements a pool mechanism to manage
-I<PerlInterpreters> between threads. This mechanism has been
+C<PerlInterpreters> between threads. This mechanism has been
abstracted into an API known as "tipool", I<Thread Item Pool>. This
pool can be used to manage any data structure, in which you wish to
have a smaller number than the number of configured threads. A good
example of such a data structure is a database connection handle.
-The I<Apache::DBI> module implements persisent connections for 1.xx,
+The C<Apache::DBI> module implements persisent connections for 1.xx,
but may result in each child maintaining its own connection, when it
is most often the case that number of connections is never needed
concurrently. The TIPool API provides a mechanism to solve this
@@ -391,19 +396,19 @@
=item new
Create a new thread item pool. This constructor is passed an
-I<Apache::Pool> object, a hash reference to pool configuration parameters,
+C<Apache::Pool> object, a hash reference to pool configuration parameters,
a hash reference to pool callbacks and an optional userdata variable
which is passed to callbacks:
- my $tip = Apache::TIPool->new($p,
- {Start => 3, Max => 6},
- {grow => \&new_connection,
- shrink => \&close_connection},
- \%my_config);
-
-The configuration parameters, I<Start>, I<Max>, I<MinSpare>, I<MaxSpare>
-and I<MaxRequests> configure the pool for your items, just as the
-I<PerlInterp*> directives do for I<PerlInterpreters>.
+ my $tip = Apache::TIPool->new($p,
+ {Start => 3, Max => 6},
+ {grow => \&new_connection,
+ shrink => \&close_connection},
+ \%my_config);
+
+The configuration parameters, C<Start>, C<Max>, C<MinSpare>, C<MaxSpare>
+and C<MaxRequests> configure the pool for your items, just as the
+C<PerlInterp*> directives do for C<PerlInterpreters>.
The I<grow> callback is called to create new items to be added to the
pool, I<shrink> is called when an item is removed from the pool.
@@ -417,14 +422,14 @@
by calling the configured I<grow> callback. Otherwise, the I<pop>
method will block until an item is available.
- my $item = $tip->pop;
+ my $item = $tip->pop;
=item putback
This method gives an item (returned from I<pop>) back to the pool,
which is pushed into the head of the available list:
- $tip->putback($item);
+ $tip->putback($item);
=back
@@ -435,85 +440,86 @@
=head2 Apache::DBIPool
-Now we will take a look at how to make I<DBI> take advantage of
-I<TIPool> API with the I<Apache::DBIPool> module. The module
-configuration in httpd.conf will look something like so:
-
- PerlModule Apache::DBIPool
-
- <DBIPool dbi:mysql:db_name>
- DBIPoolStart 10
- DBIPoolMax 20
- DBIPoolMaxSpare 10
- DBIPoolMinSpare 5
- DBIUserName dougm
- DBIPassWord XxXx
- </DBIPool>
-
-The module is loaded using the I<PerlModule> directive just as with
-other modules. TIPools are then configured using I<DBIPool>
-configuration sections. The argument given to the container is the
-I<dsn> and within are the pool directives I<Start>, I<Max>,
-I<MaxSpare> and I<MinSpare>. The I<UserName> and I<PassWord>
-directives will be passed to the I<DBI> I<connect> method.
-There can be any number of I<DBIPool> containers, provided each I<dsn>
+Now we will take a look at how to make C<DBI> take advantage of
+C<TIPool> API with the C<Apache::DBIPool> module. The module
+configuration in I<httpd.conf> will look something like so:
+
+ PerlModule Apache::DBIPool
+
+ <DBIPool dbi:mysql:db_name>
+ DBIPoolStart 10
+ DBIPoolMax 20
+ DBIPoolMaxSpare 10
+ DBIPoolMinSpare 5
+ DBIUserName dougm
+ DBIPassWord XxXx
+ </DBIPool>
+
+The module is loaded using the C<PerlModule> directive just as with
+other modules. TIPools are then configured using C<DBIPool>
+ configuration sections. The argument given to the container is the
+C<dsn> and within are the pool directives C<Start>, C<Max>,
+C<MaxSpare> and C<MinSpare>. The C<UserName> and C<PassWord>
+directives will be passed to the C<DBI> C<connect> method.
+There can be any number of C<DBIPool> containers, provided each C<dsn>
is different, and/or each container is inside a different
-I<VirtualHost> container.
+C<VirtualHost> container.
Now let's examine the source code, keeping in mind this module
-contains the basics and the official release (tbd) will likely contain
-more details, such as how it hooks into I<DBI.pm> to provide
-transparency the way I<Apache::DBI> currently does.
+contains the basics and the official release (tbd) will likely contain
+more details, such as how it hooks into C<DBI> to provide transparency
+the way C<Apache::DBI> currently does.
-After pulling in the modules needed I<Apache::TIPool>,
-I<Apache::ModuleConfig> and I<DBI>, we setup a callback table. The
+After pulling in the needed modules C<Apache::TIPool>,
+C<Apache::ModuleConfig> and C<DBI>, we setup a callback table. The
I<new_connection> function will be called with the TIP needs to add a
new item and I<close_connection> when an item is being removed from
-the pool. The I<Apache::Hook> I<add> method registers a
-I<PerlPostConfigHandler> which will be called after Apache has read
+the pool. The C<Apache::Hook> I<add> method registers a
+C<PerlPostConfigHandler> which will be called after Apache has read
the configuration files.
-This handler (our I<init> function) is passed 3 I<Apache::Pool>
-objects and one I<Apache::Server> object. Each I<Apache::Pool> has a
+This handler (our I<init> function) is passed three C<Apache::Pool>
+objects and one C<Apache::Server> object. Each C<Apache::Pool> has a
different lifetime, the first will be alive until configuration is
read again, such as during restarts. The second will be alive until
logs are re-opened and the third is a temporary pool which is cleared
before Apache starts serving requests. Since the DBI connection pool
-is associated with configuration in httpd.conf, we will use that pool.
+is associated with configuration in I<httpd.conf>, we will use that
+pool.
-The I<Apache::ModuleConfig> I<get> method is called with the
-I<Apache::Server> object to give us the configuration associated with
+The C<Apache::ModuleConfig> I<get> method is called with the
+C<Apache::Server> object to give us the configuration associated with
the given server. Next is a while loop which iterates over the
-configuration parsed by the I<DBIPool> directive handler. The keys of
-this hash are the configured I<dsn>, of which there is one per
-I<DBIPool> configuration section. The values will be a hash reference
-to the pool configuration, I<Start>, I<Max>, I<MinSpare>, I<MaxSpare>
-and I<MaxRequests>.
-
-A I<new> I<Apache::TIPool> is then contructed, passing it the
-C<$pconf> I<Apache::Pool>, configuration C<$params>, the I<$callbacks>
-table and C<$conn> hash ref. The I<TIPool> is then saved into the
-C<$cfg> object, indexed by the I<dsn>.
+configuration parsed by the C<DBIPool> directive handler. The keys of
+this hash are the configured C<dsn>, of which there is one per
+C<DBIPool> configuration section. The values will be a hash reference
+to the pool configuration, C<Start>, C<Max>, C<MinSpare>, C<MaxSpare>
+and C<MaxRequests>.
+
+A I<new> C<Apache::TIPool> is then constructed, passing it the
+C<$pconf>, C<Apache::Pool>, configuration C<$params>, the C<$callbacks>
+table and C<$conn> hash ref. The C<TIPool> is then saved into the
+C<$cfg> object, indexed by the C<dsn>.
-At the time I<Apache::TIPool::new> is called, the I<new_connection>
-callback will be called the number of time to which I<Start> is
+At the time C<Apache::TIPool::new> is called, the I<new_connection>
+callback will be called the number of times to which C<Start> is
configured. This callback localizes I<Apache::DBIPool::connect> to a
code reference which makes the real database connection.
At request time I<Apache::DBIPool::connect> will fetch a database
-handle from the I<TIPool>. It does so by digging into the
+handle from the C<TIPool>. It does so by digging into the
configuration object associated with the current virtual host to
-obtain a reference to the I<TIPool> object. It then calls the I<pop>
+obtain a reference to the C<TIPool> object. It then calls the I<pop>
method, which will immediatly return a database handle if one is
-available. If all opened connection are in used and the current
-number of connections is less than the configured I<Max>, the call to
-I<pop> will result in a call to I<new_connection>. If I<Max> has
-already been reached, then I<pop> will block until a handle is
-I<putback> into the pool.
+available. If all opened connection are in use and the current number
+of connections is less than the configured C<Max>, the call to I<pop>
+will result in a call to I<new_connection>. If C<Max> has already
+been reached, then I<pop> will block until a handle is I<putback> into
+the pool.
-Finally, the handle is blessed into the I<Apache::DBIPool::db> class
+Finally, the handle is blessed into the C<Apache::DBIPool::db> class
which will override the dbd class I<disconnect> method. The
-overridden I<disconnect> method obtains a reference to the I<TIPool>
+overridden I<disconnect> method obtains a reference to the C<TIPool>
object and passes it to the I<putback> method, making it available for
use by other threads. Should the Perl code using this handle neglect to
call the I<disconnect> method, the overridden I<connect> method has
@@ -521,183 +527,184 @@
=head2 Apache::DBIPool Source
- package Apache::DBIPool;
-
- use strict;
- use Apache::TIPool ();
- use Apache::ModuleConfig ();
- use DBI ();
-
- my $callbacks = {
- grow => \&new_connection, #add new connection to the pool
- shrink => \&close_connection, #handle removed connection from pool
- };
-
- Apache::Hook->add(PerlPostConfigHandler => \&init); #called at startup
-
- sub init {
- my($pconf, $plog, $ptemp, $s) = @_;
-
- my $cfg = Apache::ModuleConfig->get($s, __PACKAGE__);
-
- #create a TIPool for each dsn
- while (my($conn, $params) = each %{ $cfg->{DBIPool} }) {
- my $tip = Apache::TIPool->new($pconf, $params, $callbacks, $conn);
- $cfg->{TIPool}->{ $conn->{dsn} } = $tip;
- }
- }
-
- sub new_connection {
- my($tip, $conn) = @_;
-
- #make actual connection to the database
- local *Apache::DBIPool::connect = sub {
- my($class, $drh) = (shift, shift);
- $drh->connect($dbname, @_);
- };
-
- return DBI->connect(@{$conn}{qw(dsn username password attr)});
- }
-
- sub close_connection {
- my($tip, $conn, $dbh) = @_;
- my $driver = (split $conn->{dsn}, ':')[1];
- my $method = join '::', 'DBD', $driver, 'db', 'disconnect';
- $dbh->$method(); #call the real disconnect method
- }
-
- my $EndToken = '</DBIPool>';
-
- #parse <DBIPool dbi:mysql:...>...
-
- sub DBIPool ($$$;*) {
- my($cfg, $parms, $dsn, $cfg_fh) = @_;
- $dsn =~ s/>$//;
-
- $cfg->{DBIPool}->{$dsn}->{dsn} = $dsn;
-
- while((my $line = <$cfg_fh>) !~ m:^$EndToken:o) {
- my($name, $value) = split $line, /\s+/, 2;
- $name =~ s/^DBIPool(\w+)/lc $1/ei;
- $cfg->{DBIPool}->{$dsn}->{$name} = $value;
- }
- }
-
- sub config {
- my $r = Apache->request;
- return Apache::ModuleConfig->get($r, __PACKAGE__);
- }
-
- #called from DBI::connect
- sub connect {
- my($class, $drh) = (shift, shift);
-
- $drh->{DSN} = join ':', 'dbi', $drh->{Name}, $_[0];
- my $cfg = config();
-
- my $tip = $cfg->{TIPool}->{ $drh->{DSN} };
-
- unless ($tip) {
- #XXX: do a real connect or fallback to Apache::DBI
- }
-
- my $item = $tip->pop; #select a connection from the pool
-
- $r->register_cleanup(sub { #incase disconnect() is not called
- $tip->putback($item);
- });
-
- return bless 'Apache::DBIPool::db', $item->data; #the dbh
- }
-
- package Apache::DBIPool::db;
-
- our @ISA = qw(DBI::db);
-
- #override disconnect, puts database handle back in the pool
- sub disconnect {
- my $dbh = shift;
- my $tip = config()->{TIPool}->{ $dbh->{DSN} };
- $tip->putback($dbh);
- 1;
- }
-
- 1;
- __END__
+ package Apache::DBIPool;
+
+ use strict;
+ use Apache::TIPool ();
+ use Apache::ModuleConfig ();
+ use DBI ();
+
+ my $callbacks = {
+ grow => \&new_connection, #add new connection to the pool
+ shrink => \&close_connection, #handle removed connection from pool
+ };
+
+ Apache::Hook->add(PerlPostConfigHandler => \&init); #called at startup
+
+ sub init {
+ my($pconf, $plog, $ptemp, $s) = @_;
+
+ my $cfg = Apache::ModuleConfig->get($s, __PACKAGE__);
+
+ #create a TIPool for each dsn
+ while (my($conn, $params) = each %{ $cfg->{DBIPool} }) {
+ my $tip = Apache::TIPool->new($pconf, $params, $callbacks, $conn);
+ $cfg->{TIPool}->{ $conn->{dsn} } = $tip;
+ }
+ }
+
+ sub new_connection {
+ my($tip, $conn) = @_;
+
+ #make actual connection to the database
+ local *Apache::DBIPool::connect = sub {
+ my($class, $drh) = (shift, shift);
+ $drh->connect($dbname, @_);
+ };
+
+ return DBI->connect(@{$conn}{qw(dsn username password attr)});
+ }
+
+ sub close_connection {
+ my($tip, $conn, $dbh) = @_;
+ my $driver = (split $conn->{dsn}, ':')[1];
+ my $method = join '::', 'DBD', $driver, 'db', 'disconnect';
+ $dbh->$method(); #call the real disconnect method
+ }
+
+ my $EndToken = '</DBIPool>';
+
+ #parse <DBIPool dbi:mysql:...>...
+
+ sub DBIPool ($$$;*) {
+ my($cfg, $parms, $dsn, $cfg_fh) = @_;
+ $dsn =~ s/>$//;
+
+ $cfg->{DBIPool}->{$dsn}->{dsn} = $dsn;
+
+ while((my $line = <$cfg_fh>) !~ m:^$EndToken:o) {
+ my($name, $value) = split $line, /\s+/, 2;
+ $name =~ s/^DBIPool(\w+)/lc $1/ei;
+ $cfg->{DBIPool}->{$dsn}->{$name} = $value;
+ }
+ }
+
+ sub config {
+ my $r = Apache->request;
+ return Apache::ModuleConfig->get($r, __PACKAGE__);
+ }
+
+ #called from DBI::connect
+ sub connect {
+ my($class, $drh) = (shift, shift);
+
+ $drh->{DSN} = join ':', 'dbi', $drh->{Name}, $_[0];
+ my $cfg = config();
+
+ my $tip = $cfg->{TIPool}->{ $drh->{DSN} };
+
+ unless ($tip) {
+ #XXX: do a real connect or fallback to Apache::DBI
+ }
+
+ my $item = $tip->pop; #select a connection from the pool
+
+ $r->register_cleanup(sub { #incase disconnect() is not called
+ $tip->putback($item);
+ });
+
+ return bless 'Apache::DBIPool::db', $item->data; #the dbh
+ }
+
+ package Apache::DBIPool::db;
+
+ our @ISA = qw(DBI::db);
+
+ #override disconnect, puts database handle back in the pool
+ sub disconnect {
+ my $dbh = shift;
+ my $tip = config()->{TIPool}->{ $dbh->{DSN} };
+ $tip->putback($dbh);
+ 1;
+ }
+
+ 1;
+ __END__
=head1 PerlOptions Directive
-A new configuration directive to mod_perl-2.0, I<PerlOptions>,
+A new configuration directive to mod_perl-2.0, C<PerlOptions>,
provides fine-grained configuration for what were compile-time only
options in mod_perl-1.xx. In addition, this directive provides
-control over what class of I<PerlInterpreter> is used for a
-I<VirtualHost> or location configured with I<Location>, I<Directory>, etc.
+control over what class of C<PerlInterpreter> is used for a
+C<E<lt>VirtualHostE<gt>> or location configured with
+C<E<lt>LocationE<gt>>, C<E<lt>DirectoryE<gt>>, etc.
These are all best explained with examples, first here's how to
disable mod_perl for a certain host:
- <VirtualHost ...>
- PerlOptions -Enable
- </VirtualHost>
+ <VirtualHost ...>
+ PerlOptions -Enable
+ </VirtualHost>
-Suppose a one of the hosts does not want to allow users to configure
-I<PerlAuthenHandler>, I<PerlAuthzHandler> or I<PerlAccessHandler> or
-<Perl> sections:
-
- <VirtualHost ...>
- PerlOptions -Authen -Authz -Access -Sections
- </VirtualHost>
+Suppose one of the hosts does not want to allow users to configure
+C<PerlAuthenHandler>, C<PerlAuthzHandler>, C<PerlAccessHandler> and
+E<lt>PerlE<gt> sections:
+
+ <VirtualHost ...>
+ PerlOptions -Authen -Authz -Access -Sections
+ </VirtualHost>
Or maybe everything but the response handler:
- <VirtualHost ...>
- PerlOptions None +Response
- </VirtualHost>
+ <VirtualHost ...>
+ PerlOptions None +Response
+ </VirtualHost>
A common problem with mod_perl-1.xx was the shared namespace between
all code within the process. Consider two developers using the same
server and each which to run a different version of a module with the
same name. This example will create two I<parent> Perls, one for each
-I<VirtualHost>, each with its own namespace and pointing to a
+C<E<lt>VirtualHostE<gt>>, each with its own namespace and pointing to a
different paths in C<@INC>:
- <VirtualHost ...>
- ServerName dev1
- PerlOptions +Parent
- PerlSwitches -Mblib=/home/dev1/lib/perl
- </VirtualHost>
-
- <VirtualHost ...>
- ServerName dev2
- PerlOptions +Parent
- PerlSwitches -Mblib=/home/dev2/lib/perl
- </VirtualHost>
+ <VirtualHost ...>
+ ServerName dev1
+ PerlOptions +Parent
+ PerlSwitches -Mblib=/home/dev1/lib/perl
+ </VirtualHost>
+
+ <VirtualHost ...>
+ ServerName dev2
+ PerlOptions +Parent
+ PerlSwitches -Mblib=/home/dev2/lib/perl
+ </VirtualHost>
Or even for a given location, for something like "dirty" cgi scripts:
- <Location /cgi-bin>
- PerlOptions +Parent
- PerlInterpMaxRequests 1
- PerlInterpStart 1
- PerlInterpMax 1
- PerlResponseHandler Apache::Registry
- </Location>
+ <Location /cgi-bin>
+ PerlOptions +Parent
+ PerlInterpMaxRequests 1
+ PerlInterpStart 1
+ PerlInterpMax 1
+ PerlResponseHandler Apache::Registry
+ </Location>
-Will use a fresh interpreter with its own namespace to handle each
+will use a fresh interpreter with its own namespace to handle each
request.
Should you wish to fine tune Interpreter pools for a given host:
- <VirtualHost ...>
- PerlOptions +Clone
- PerlInterpStart 2
- PerlInterpMax 2
- </VirtualHost>
+ <VirtualHost ...>
+ PerlOptions +Clone
+ PerlInterpStart 2
+ PerlInterpMax 2
+ </VirtualHost>
This might be worthwhile in the case where certain hosts have their
own sets of large-ish modules, used only in each host. By tuning each
-host to have it's own pool, that host will continue to reuse the Perl
+host to have its own pool, that host will continue to reuse the Perl
allocations in their specific modules.
In 1.x versions of mod_perl, configured Perl*Handlers which are not a
@@ -707,14 +714,14 @@
not auto-loaded during startup-time resolution. It is possible to
configure this feature with:
- PerlOptions +Autoload
+ PerlOptions +Autoload
Consider this configuration:
- PerlResponseHandler Apache::Magick
+ PerlResponseHandler Apache::Magick
-In this case, I<Apache::Magick> is the package name, and the
-subroutine name will default to I<handler>. If the I<Apache::Magick>
+In this case, C<Apache::Magick> is the package name, and the
+subroutine name will default to I<handler>. If the C<Apache::Magick>
module is not already loaded, B<PerlOptions +Autoload> will attempt to
pull it in at startup time.
@@ -722,28 +729,28 @@
The mod_perl-2.0 interface to the Apache filter API is much simpler
than the C API, hiding most of the details underneath. Perl filters
-are configured using the I<PerlFilterHandler> directive, for example:
+are configured using the C<PerlFilterHandler> directive, for example:
- PerlFilterHandler Apache::ReverseFilter
+ PerlFilterHandler Apache::ReverseFilter
This simply registers the filter, which can then be turned on using
-the core I<AddOutputFilter> directive:
+the core C<AddOutputFilter> directive:
- <Location /foo>
- AddOutputFilter Apache::ReverseFilter
- </Location>
+ <Location /foo>
+ AddOutputFilter Apache::ReverseFilter
+ </Location>
-The I<Apache::ReverseFilter> handler will now be called for anything
-accessed in the I</foo> url space. The I<AddOutputFilter> directive takes
+The C<Apache::ReverseFilter> handler will now be called for anything
+accessed in the I</foo> url space. The C<AddOutputFilter> directive takes
any number of filters, for example, this configuration will first send
the output to I<mod_include>, which will in turn pass its output down
-to I<Apache::ReverseFilter>:
+to C<Apache::ReverseFilter>:
- AddOutputFilter INCLUDE Apache::ReverseFilter
+ AddOutputFilter INCLUDE Apache::ReverseFilter
-For our example, I<Apache::ReverseFilter> simply reverses all of the
+For our example, C<Apache::ReverseFilter> simply reverses all of the
output characters and then sends them downstream. The first argument
-to a filter handler is an I<Apache::Filter> object, which at the
+to a filter handler is an C<Apache::Filter> object, which at the
moment provides two methods I<read> and I<write>. The I<read> method
pulls down a chunk of the output stream into the given buffer,
returning the length read into the buffer. An optional size argument
@@ -753,21 +760,21 @@
filter. In our case C<scalar reverse> takes advantage of Perl's
builtins to reverse the upstream buffer:
- 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;
+ 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 Perl interface to the APR and Apache API
@@ -779,20 +786,19 @@
The goal for 2.0 is to generate the majority of xs code and provide
thin wrappers were 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. The API behaves just
-as it did in 1.x, sosers of the API will not notice the difference,
-other than the addition of many new methods. And in the case of
-I<APR>, it is possible to use I<APR> modules outside of Apache, for
-example:
+public data structures are covered from the get-go. Certain functions
+and structures which are considered "private" to Apache or otherwise
+un-useful to Perl aren't glued. The API behaves just as it did in
+1.x, so users of the API will not notice the difference, other than the
+addition of many new methods. And in the case of C<APR>, it is
+possible to use C<APR> modules outside of Apache, for example:
- % perl -MAPR -MAPR::UUID -le 'print APR::UUID->new->format'
- b059a4b2-d11d-b211-bc23-d644b8ce0981
+ % perl -MAPR -MAPR::UUID -le 'print APR::UUID->new->format'
+ b059a4b2-d11d-b211-bc23-d644b8ce0981
The mod_perl generator is a custom suite of modules specifically tuned
for gluing Apache and allows for complete control over I<everything>,
-providing many possibilities none of I<xsubpp>, I<swig> nor
+providing many possibilities none of I<xsubpp>, I<SWIG> nor
I<Inline.pm> are designed to do. Advantages to generating the glue
code include:
@@ -840,142 +846,141 @@
=head2 Apache::Echo
-Apache 2.0 ships with an example protocol module, I<mod_echo>, which
+Apache 2.0 ships with an example protocol module, C<mod_echo>, which
simply reads data from the client and echos it right back. Here we'll
-take a look at a Perl version of that module, called I<Apache::Echo>.
+take a look at a Perl version of that module, called C<Apache::Echo>.
A protocol handler is configured using the
-I<PerlProcessConnectionHandler> directive and we'll use the I<Listen>
-and I<VirtualHost> directives to bind to a non-standard port B<8084>:
+C<PerlProcessConnectionHandler> directive and we'll use the C<Listen>
+and C<E<lt>VirtualHostE<gt>> directives to bind to a non-standard port
B<8084>:
- Listen 8084
- <VirtualHost _default_:8084>
- PerlProcessConnectionHandler Apache::Echo
- </VirtualHost>
+ Listen 8084
+ <VirtualHost _default_:8084>
+ PerlProcessConnectionHandler Apache::Echo
+ </VirtualHost>
-Apache::Echo is then enabled when starting Apache:
+C<Apache::Echo> is then enabled when starting Apache:
- % httpd
+ % httpd
And we give it a whirl:
- % telnet localhost 8084
- Trying 127.0.0.1...
- Connected to localhost (127.0.0.1).
- Escape character is '^]'.
- hello apachecon
- hello apachecon
- ^]
+ % telnet localhost 8084
+ Trying 127.0.0.1...
+ Connected to localhost (127.0.0.1).
+ Escape character is '^]'.
+ mod_perl rules
+ mod_perl rules
+ ^]
The code is just a few lines of code, with the standard I<package>
declaration and of course, C<use strict;>. As with all
-I<Perl*Handler>s, the subroutine name defaults to I<handler>. However,
-in the case of a protocol handler, the first argument is not a
-I<request_rec>, but a I<conn_rec> blessed into the
-I<Apache::Connection> class. We have direct access to the client
-socket via I<Apache::Connection>'s I<client_socket> method. This
-returns an object blessed into the I<APR::Socket> class.
+C<Perl*Handler>s, the subroutine name defaults to I<handler>.
+However, in the case of a protocol handler, the first argument is not
+a C<request_rec>, but a C<conn_rec> blessed into the
+C<Apache::Connection> class. We have direct access to the client
+socket via C<Apache::Connection>'s I<client_socket> method. This
+returns an object blessed into the C<APR::Socket> class.
Inside the echo loop, we attempt to read B<BUFF_LEN> bytes from the
client socket into the C<$buff> buffer. The C<$rlen> parameter will
-be set to the number of bytes actually read. The I<APR::Socket>
+be set to the number of bytes actually read. The C<APR::Socket>
I<recv> method will return an I<apr_status_t> value, be we need only
check the read length to break out of the loop if it is less than or
equal to B<0> bytes. If we received some data, it is immediately
-echoed back to the client with the I<APR::Socket> I<send> method.
-If we were unable to echo back the same number of bytes read from the
+echoed back to the client with the C<APR::Socket> I<send> method. If
+we were unable to echo back the same number of bytes read from the
client, assume the connection was dropped and break out of the loop.
Once the client has disconnected, the module returns B<Apache::OK>,
telling Apache we have handled the connection:
- package Apache::Echo;
-
- use strict;
- use Apache::Connection ();
- use APR::Socket ();
-
- use constant BUFF_LEN => 1024;
-
- sub handler {
- my Apache::Connection $c = shift;
- my APR::Socket $socket = $c->client_socket;
-
- my $buff;
-
- for (;;) {
- my($rlen, $wlen);
- my $rlen = BUFF_LEN;
- $socket->recv($buff, $rlen);
- last if $rlen <= 0;
- $wlen = $rlen;
- $socket->send($buff, $wlen);
- last if $wlen != $rlen;
- }
-
- return Apache::OK;
- }
-
- 1;
- __END__
+ package Apache::Echo;
+
+ use strict;
+ use Apache::Connection ();
+ use APR::Socket ();
+
+ use constant BUFF_LEN => 1024;
+
+ sub handler {
+ my Apache::Connection $c = shift;
+ my APR::Socket $socket = $c->client_socket;
+
+ my $buff;
+
+ for (;;) {
+ my($rlen, $wlen);
+ my $rlen = BUFF_LEN;
+ $socket->recv($buff, $rlen);
+ last if $rlen <= 0;
+ $wlen = $rlen;
+ $socket->send($buff, $wlen);
+ last if $wlen != $rlen;
+ }
+
+ return Apache::OK;
+ }
+
+ 1;
=head2 Apache::CommandServer
Our first protocol handler example took advange of Apache's server
framework, but did not tap into any other modules. The next example
is based on the example in the "TCP Servers with IO::Socket" section
-of I<perlipc>. Of course, we don't need I<IO::Socket> since Apache
-takes care of those details for us. The rest of that example can
-still be used to illustrate implementing a simple text protocol. In
-this case, one where a command is sent by the client to be executed on
-the server side, with results sent back to the client.
+of the I<perlipc> manpage. Of course, we don't need C<IO::Socket>
+since Apache takes care of those details for us. The rest of that
+example can still be used to illustrate implementing a simple text
+protocol. In this case, one where a command is sent by the client to
+be executed on the server side, with results sent back to the client.
-The I<Apache::CommandServer> handler will support four commands:
-I<motd>, I<date>, I<who> and I<quit>. These are probably not
+The C<Apache::CommandServer> handler will support four commands:
+C<motd>, C<date>, C<who> and C<quit>. These are probably not
commands which can be exploited, but should we add such commands,
we'll want to limit access based on ip address/hostname,
authentication and authorization. Protocol handlers need to take care
of these tasks themselves, since we bypass the HTTP protocol handler.
-As with all I<PerlProcessConnectionHandlers>, we are passed an
-I<Apache::Connection> object as the first argument. Again, we will be
+As with all C<PerlProcessConnectionHandlers>, we are passed an
+C<Apache::Connection> object as the first argument. Again, we will be
directly accessing the client socket via the I<client_socket> method.
The I<login> subroutine is called to check if access by this client
-should be allowed. This routine makes up for what we lost with the
+should be allowed. This routine makes up for what we lost with the
core HTTP protocol handler bypassed. First we call the
-I<Apache::RequestRec> I<new> method, which returns a I<request_rec>
-object, just like that which is passed into request time
-I<Perl*Handlers> and returned by the subrequest API methods,
+C<Apache::RequestRec> I<new> method, which returns a I<request_rec>
+object, just like that which is passed at request time to
+C<Perl*Handlers> and returned by the subrequest API methods,
I<lookup_uri> and I<lookup_file>. However, this "fake request" does
not run handlers for any of the phases, it simply returns an object
which we can use to do that ourselves. The C<location_merge> method
is passed the "location" for this request, it will look up the
-<Location> section that matches the given name and merge it with the
-default server configuration. For example, should we only wish to
-allow access to this server from certain locations:
-
- <Location Apache::CommandServer>
- deny from all
- allow from 10.*
- </Location>
+C<E<lt>LocationE<gt>> section that matches the given name and merge it
+with the default server configuration. For example, should we only
+wish to allow access to this server from certain locations:
+
+ <Location Apache::CommandServer>
+ deny from all
+ allow from 10.*
+ </Location>
The I<location_merge> method only looks up and merges the
-configuration, we still need to apply it.
-This is done in I<for> loop, iterating over three methods:
-I<run_access_checker>, I<run_check_user_id> and I<run_auth_checker>.
-These methods will call directly into the Apache functions that invoke
-module handlers for these phases and will return an integer status
-code, such as B<OK>, B<DECLINED> or B<FORBIDDEN>. If I<run_access_check>
-returns something other than B<OK> or B<DECLINED>, that status will be
-propagated up to the handler routine and then back up to Apache.
-Otherwise, the access check passed and the loop will break unless
-I<some_auth_required> returns true. This would be false given the
-previous configuration example, but would be true in the presense of a
-I<require> directive, such as:
-
- <Location Apache::CommandServer>
- deny from all
- allow from 10.*
- require user dougm
- </Location>
+configuration, we still need to apply it. This is done in I<for>
+loop, iterating over three methods: I<run_access_checker>,
+I<run_check_user_id> and I<run_auth_checker>. These methods will call
+directly into the Apache functions that invoke module handlers for
+these phases and will return an integer status code, such as C<OK>,
+C<DECLINED> or C<FORBIDDEN>. If I<run_access_check> returns something
+other than C<OK> or C<DECLINED>, that status will be propagated up to
+the handler routine and then back up to Apache. Otherwise, the access
+check passed and the loop will break unless I<some_auth_required>
+returns true. This would be false given the previous configuration
+example, but would be true in the presense of a I<require> directive,
+such as:
+
+ <Location Apache::CommandServer>
+ deny from all
+ allow from 10.*
+ require user dougm
+ </Location>
Given this configuration, I<some_auth_required> will return true.
The I<user> method is then called, which will return false if we have
@@ -1003,141 +1008,141 @@
return a true value, we break out of the loop. Let's give it a try
with this configuration:
- Listen 8085
- <VirtualHost _default_:8085>
- PerlProcessConnectionHandler Apache::CommandServer
-
- <Location Apache::CommandServer>
- allow from 127.0.0.1
- require user dougm
- satisfy any
- AuthUserFile /tmp/basic-auth
- </Location>
- </VirtualHost>
-
- % telnet localhost 8085
- Trying 127.0.0.1...
- Connected to localhost (127.0.0.1).
- Escape character is '^]'.
- Login: dougm
- Password: foo
- Welcome to Apache::CommandServer
- Available commands: motd date who quit
- motd
- Have a lot of fun...
- date
- Mon Mar 12 19:20:10 PST 2001
- who
- dougm tty1 Mar 12 00:49
- dougm pts/0 Mar 12 11:23
- dougm pts/1 Mar 12 14:08
- dougm pts/2 Mar 12 17:09
- quit
- Connection closed by foreign host.
+ Listen 8085
+ <VirtualHost _default_:8085>
+ PerlProcessConnectionHandler Apache::CommandServer
+
+ <Location Apache::CommandServer>
+ allow from 127.0.0.1
+ require user dougm
+ satisfy any
+ AuthUserFile /tmp/basic-auth
+ </Location>
+ </VirtualHost>
+
+ % telnet localhost 8085
+ Trying 127.0.0.1...
+ Connected to localhost (127.0.0.1).
+ Escape character is '^]'.
+ Login: dougm
+ Password: foo
+ Welcome to Apache::CommandServer
+ Available commands: motd date who quit
+ motd
+ Have a lot of fun...
+ date
+ Mon Mar 12 19:20:10 PST 2001
+ who
+ dougm tty1 Mar 12 00:49
+ dougm pts/0 Mar 12 11:23
+ dougm pts/1 Mar 12 14:08
+ dougm pts/2 Mar 12 17:09
+ quit
+ Connection closed by foreign host.
=head2 Apache::CommandServer Source
- package Apache::CommandServer;
-
- use strict;
- use Apache::Connection ();
- use APR::Socket ();
-
- my @cmds = qw(motd date who quit);
- my %commands = map { $_, \&{$_} } @cmds;
-
- sub handler {
- my Apache::Connection $c = shift;
- my APR::Socket $socket = $c->client_socket;
-
- if ((my $rc = login($c)) != Apache::OK) {
- $socket->send("Access Denied\n");
- return $rc;
- }
-
- $socket->send("Welcome to " . __PACKAGE__ .
- "\nAvailable commands: @cmds\n");
-
- for (;;) {
- my $cmd;
- next unless $cmd = getline($socket);
-
- if (my $sub = $commands{$cmd}) {
- last unless $sub->($socket) == APR::SUCCESS;
- }
- else {
- $socket->send("Commands: @cmds\n");
- }
- }
-
- return Apache::OK;
- }
-
- sub login {
- my $c = shift;
-
- my $r = Apache::RequestRec->new($c);
- $r->location_merge(__PACKAGE__);
-
- for my $method (qw(run_access_checker run_check_user_id
run_auth_checker)) {
- my $rc = $r->$method();
-
- if ($rc != Apache::OK and $rc != Apache::DECLINED) {
- return $rc;
- }
-
- last unless $r->some_auth_required;
-
- unless ($r->user) {
- my $socket = $c->client_socket;
- my $username = prompt($socket, "Login");
- my $password = prompt($socket, "Password");
-
- $r->set_basic_credentials($username, $password);
- }
- }
-
- return Apache::OK;
- }
-
- sub getline {
- my $socket = shift;
- my $line;
- $socket->recv($line, 1024);
- return unless $line;
- $line =~ s/[\r\n]*$//;
- return $line;
- }
-
- sub prompt {
- my($socket, $msg) = @_;
- $socket->send("$msg: ");
- getline($socket);
- }
-
- sub motd {
- my $socket = shift;
- open my $fh, '/etc/motd' or return;
- local $/;
- my $status = $socket->send(scalar <$fh>);
- close $fh;
- return $status;
- }
-
- sub date {
- my $socket = shift;
- $socket->send(scalar(localtime) . "\n");
- }
-
- sub who {
- my $socket = shift;
- $socket->send(scalar `who`);
- }
-
- sub quit {1}
-
- 1;
- __END__
+ package Apache::CommandServer;
+
+ use strict;
+ use Apache::Connection ();
+ use APR::Socket ();
+
+ my @cmds = qw(motd date who quit);
+ my %commands = map { $_, \&{$_} } @cmds;
+
+ sub handler {
+ my Apache::Connection $c = shift;
+ my APR::Socket $socket = $c->client_socket;
+
+ if ((my $rc = login($c)) != Apache::OK) {
+ $socket->send("Access Denied\n");
+ return $rc;
+ }
+
+ $socket->send("Welcome to " . __PACKAGE__ .
+ "\nAvailable commands: @cmds\n");
+
+ for (;;) {
+ my $cmd;
+ next unless $cmd = getline($socket);
+
+ if (my $sub = $commands{$cmd}) {
+ last unless $sub->($socket) == APR::SUCCESS;
+ }
+ else {
+ $socket->send("Commands: @cmds\n");
+ }
+ }
+
+ return Apache::OK;
+ }
+
+ sub login {
+ my $c = shift;
+
+ my $r = Apache::RequestRec->new($c);
+ $r->location_merge(__PACKAGE__);
+
+ for my $method (qw(run_access_checker run_check_user_id
run_auth_checker)) {
+ my $rc = $r->$method();
+
+ if ($rc != Apache::OK and $rc != Apache::DECLINED) {
+ return $rc;
+ }
+
+ last unless $r->some_auth_required;
+
+ unless ($r->user) {
+ my $socket = $c->client_socket;
+ my $username = prompt($socket, "Login");
+ my $password = prompt($socket, "Password");
+
+ $r->set_basic_credentials($username, $password);
+ }
+ }
+
+ return Apache::OK;
+ }
+
+ sub getline {
+ my $socket = shift;
+ my $line;
+ $socket->recv($line, 1024);
+ return unless $line;
+ $line =~ s/[\r\n]*$//;
+ return $line;
+ }
+
+ sub prompt {
+ my($socket, $msg) = @_;
+ $socket->send("$msg: ");
+ getline($socket);
+ }
+
+ sub motd {
+ my $socket = shift;
+ open my $fh, '/etc/motd' or return;
+ local $/;
+ my $status = $socket->send(scalar <$fh>);
+ close $fh;
+ return $status;
+ }
+
+ sub date {
+ my $socket = shift;
+ $socket->send(scalar(localtime) . "\n");
+ }
+
+ sub who {
+ my $socket = shift;
+ $socket->send(scalar `who`);
+ }
+
+ sub quit {1}
+
+ 1;
+ __END__
=head1 mod_perl-2.0 Optimizations
@@ -1149,17 +1154,15 @@
tree and some a combination of both. In this section we'll take a
brief look at some of the optimizations that are being considered.
-The details of these optimizations will from the most part be hidden
-from mod_perl users, the exeception being that some will only be turned
-on with configuration directives. The explanation of these
-optimization ideas are best left for the live talk, a few which will
-be overviewed include:
+The details of these optimizations from the most part are hidden from
+mod_perl users, the exception being that some will only be turned on
+with configuration directives. A few of which include:
=over 4
=item *
-"Compiled" Perl*Handlers
+"Compiled" C<Perl*Handlers>
=item *
@@ -1167,11 +1170,11 @@
=item *
-`print' enhancements
+I<print> enhancements
=item *
-Inlined Apache::*.xs calls
+Inlined C<Apache::*.xs> calls
=item *
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
