README for mod_perl.c, mod_perl_fast.c, and Apache.xs

These are Apache modules that embed a perl interpreter in the HTTP server.  
The benefit of this is that we are able to
run scripts without going through the expensive (fork/exec/parameter
passing/parsing, etc.) CGI interface.  
The scripts will run faster and they have direct access to the C API of the server.

The current approach of mod_perl is to allocate and construct a new perl interpreter for
each request.  The interpreter will then parse and run a perl script and we
finally destruct the perl interpreter in order to free memory consumed.  

The current approach of mod_perl_fast is to allocate and contruct one perl interpreter when
the server starts.  At the same time, load, parse and run one perl script, which may pull 
in other perl code such as your favorite modules.
This also allows you to initiate persistent connections such as to a database server.
Then, a subroutine in memory is called to handle each request.
The interpreter is destroyed upon restart or shutdown of the server.

You may choose to use the server API or setup a standard CGI environment.

INSTALLATION

**IMPORTANT**
Currently, you can only use mod_perl *or* mod_perl_fast.
Unless you have figured out a way to build perl with -DEMBED *and* -DMULTIPLICITY.
You may however, build Apache with both modules.
To "turn off" mod_perl, simply #comment out the AddType httpd/perl .pl
To "turn off" mod_perl_fast, simply #comment out the PerlScript scriptname.pl in srm.conf
*************

Build with apache1.1b2 or better.

Make sure you have perl version 5.002_01 or better, compiled with -DEMBED
(this is the default with 5.002_01) otherwise, Apache and Perl fight over namespace.
You can try with 5.002 and -DEMBED, but it looks like the 'usage' symbols will conflict

Fetch and install Devel::embed from CPAN 
<URL:http://www.perl.com/cgi-bin/cpan_mod?module=Devel::embed>.

You'll need to use
the Makefile.tmpl file in this directory, or make changes to your copy.

You'll also need to edit the Configuration file:

For mod_perl add:
Module perl_module mod_perl.o

For mod_perl_fast add:
Module perl_fast_module mod_perl_fast.o

Copy the files in this src/ to apache's src/

Copy Apache.pm to a place where perl can find it (sorry no Makefile.PL yet).

Follow the Apache install docs from there.

To tell Apache you want mod_perl to handle your scripts:
AddType httpd/perl .pl

To tell Apache you want mod_perl_fast to handle your scripts:
AddType httpd/fast-perl .fpl

In srm.conf:
PerlScript  script_to_load_at_startup.pl

This script will be loaded when the server starts.

In an access.conf <Directory /foo> or .htaccess:
PerlResponse sub_routine_name

This is the name of the subroutine to call (defined in PerlScript)
to handle each request.

See Apache.pm on how to use the Perl-Apache API
See mpf_eg.pl for an example script to use with mod_perl_fast.

Let me (dougm@osf.org) know how it goes...

KNOWN BUGS

mod_perl leaks memory,
this is a problem with perl itself, and is being investigated.

mod_perl_fast leaks memory when the server is restarted
this too is a problem with perl itself, and is being investigated.

Installation needs work.

TODO

o Resolve multiple perl interpreter issues.
o Complete Apache.xs interface
o Find a way to hookup perl's STDIN and STDOUT to the client
  with this new i/o scheme. tie(*STDIN, Tie::ApacheHandle, $r) anyone?
o Provide an optional and configurable Safe wrapper around embedded scripts
  (almost there)

ACKNOWLEGEMENTS

Many thanks to Gisle Aas <aas@oslonett.no>
for getting this started.

Thanks to John Detloff <detloff@arizona.edu> for
contributions to mod_perl_fast.