Table of Contents:
The Apache/Perl integration project brings together the full power of the Perl programming language and the Apache HTTP server. With mod_perl it is possible to write Apache modules entirely in Perl, letting you easily do things that are more difficult or impossible in regular CGI programs, such as running sub requests. In addition, the persistent Perl interpreter embedded in the server saves the overhead of starting an external interpreter, i.e. the penalty of Perl start-up time. And not the least important feature is code caching, where modules and scripts are loaded and compiled only once, then for the rest of the server's life they are served from the cache, thus the server spends its time only on running already loaded and compiled code, which is very fast.
The primary advantages of mod_perl are power and speed. You have full
access to the inner workings of the web server and can intervene at any
stage of request-processing. This allows for customized processing of (to
name just a few of the phases) URI->filename translation,
authentication, response generation, and logging. There is very little
run-time overhead. In particular, it is not necessary to start a separate
process, as is often done with web-server extensions. The most wide-spread
such extension, the Common Gateway Interface (CGI), can be replaced
entirely with Perl code that handles the response generation phase of
request processing. mod_perl includes 2 general purpose modules for this
purpose: Apache::Registry
, which can transparently run existing perl CGI scripts and
Apache::PerlRun
, which does a similar job but allows you to run ``dirtier'' (to some
extent) scripts.
You can configure your httpd server and handlers in Perl (using
PerlSetVar
, and <Perl> sections). You can even define your own configuration directives.
Many people wonder and ask ``How much of a performance improvement does mod_perl give?''. Well, it all depends on what you are doing with mod_perl and possibly who you ask. Developers report speed boosts from 200% to 2000%. The best way to measure is to try it and see for yourself! (See http://perl.apache.org/tidbits.html and http://perl.apache.org/stories/ for the facts.)
When you run your CGI scripts by using a configuration of:
ScriptAlias /cgi-bin/ /home/httpd/cgi-bin/
you run it under a mod_cgi handler, you never define it explicitly. Apache does all the configuration work behind the scenes, when you use a ScriptAlias.
BTW, don't confuse it with a ExecCGI
configuration option, it's being enabled so the script will be executed and
not returned as a plain file. For example for mod_perl and Apache::Registry
you would use a configuration like:
<Location /perl> SetHandler perl-script PerlHandler Apache::Registry Options ExecCGI PerlSendHeader On </Location>
META: complete
META: complete
From the point of Perl API, Apache::Registry
is just yet another handler that's not conceptually different from any
other handler. It reads in the file, compiles, executes it and stores into
the cache. Since the perl interpreter keeps running from child process'
creation to its death, any code compiled by the interpreter is not removed
from memory until the child dies.
To keep the script names from collisions, it prepends
Apache::ROOT::
and the mangled path of the URI to the key of the cached script. This key
is actually a package name, the script resides in. So if you have requested
a script /perl/project/test.pl
, the scripts would be wrapped in code which starts with package
declaration of:
package Apache::ROOT::perl::project::test_e2pl;
Apache::Registry
also stores the script's last modification time. Everytime the script
changes, the cached code would be discarded and recompiled using the
modified source. However, it doesn't check any of the perl libraries the
script might use.
Apache::Registry
overrides the CORE::exit()
with <Apache::exit()>, so the CGI scripts that used the
<exit()> will run correctly. We will talk about all these details
indepth later.
The last thing Apache::Registry
does, is emulating of the mod_cgi's environment variables. Like $ENV{SERVER_NAME}
, $ENV{REMOTE_USER}
and so on. PerlSetupEnv Off disables this feature and saves some memory bits and CPU clocks.
From the point of mod_cgi (when you take the script that was running as a plain CGI under mod_cgi to run under mod_perl), there is almost no difference, but great speed improve, though much heavier memory usage (there is no free lunch :).
Just rememeber that the code is being cached, so it wouldn't cleanup the memory, like you used to with mod_cgi when the script was existing (it doesn't exit in mod_perl).
Also rememeber that any libraries that your script might
require()
or use()
wouldn't be recompiled when
changed.
Of course the book will answer all this issues in depth.
Just to show you what happens with your script, when it's being executed
under Apache::Registry
. If we take the simplest code of (URI /perl/project/test.pl
)
print "Content-type: text/html\n\n"; print "It works\n";
Apache::Registry
will convert it into the following:
package Apache::ROOT::perl::project::test_e2pl; use Apache qw(exit); sub handler { print "Content-type: text/html\n\n"; print "It works\n"; }
META: Complete
This document was written in an effort to help you start using Apache's
mod_perl extension as quickly and easily as possible. It includes
information about installation and configuration of Perl and the Apache web
server and delves deeply into issues of writing and porting existing Perl
scripts to run under mod_perl. Note that it does not attempt to enter the
big world of using the Perl API or C API. You will find pointers covering
these topics in the Getting Helped and Further Learning section of this document. This guide tries to cover the most of the Apache::Registry
and Apache::PerlRun
modules. Along with mod_perl related topics, there are many more issues
related to administrating apache servers, debugging scripts, using
databases, Perl reference, code snippets and more. The Guide's Overview will help you to find your way through the guide.
It is assumed that you know at least the basics of building and installing Perl and Apache. (If you do not, just read the INSTALL docs coming with distribution of each package.) However, in this guide you will find specific Perl and Apache installation and configuration notes, which will help you successfully complete the mod_perl installation and get the server running in a short time.
If after reading this guide and other documents listed at Help section, you feel that your question is yet not answered, please ask the apache/mod_perl mailing list to help you. But first try to browse the mailing list archive (located at http://forum.swarthmore.edu/epigone/modperl ). Often you will find the answer to your question by searching the mailing list archive, since there is a good chance someone else has already encountered the problem and found a solution. If you ignore this advice, do not be surprised if your question goes unanswered - it bores people to answer the same question more than once (twice?). This does not mean that you should avoid asking questions, just do not abuse the available help and RTFM before you call for HELP. (You have certainly heard the infamous fable of the shepherd boy and the wolves...)
If you find incorrect details or my grammar mistakes, or you want to contribute to this document please feel free to send me an email at sbekman@iname.com .
I have used the following references while writing this guide:
mod_perl FAQ by Frank Cringle at http://perl.apache.org/faq/ .
mod_perl performance tuning guide by Vivek Khera at http://perl.apache.org/tuning/ .
mod_perl plugin reference guide by Doug MacEachern at http://perl.apache.org/src/mod_perl.html .
Quick guide for moving from CGI to mod_perl at http://perl.apache.org/dist/cgi_to_mod_perl.html .
mod_perl_traps, common traps and solutions for mod_perl users at http://perl.apache.org/dist/mod_perl_traps.html .
mod_perl mailing list emails. Answers to some of the questions posted to modperl@apache.org Apache/Perl mailing list.
My personal experience with mod_perl.
As I said, I have quoted many information snippets from FAQs and emails, and I did not credit people after each quote in the guide. I did not mean to take the credit for myself, it's just that I tried to keep track of names, and became lost, so I preferred not to put credit throughout the guide, but rather to centralize it here. If you want your name to show up under your original quote, please tell me and I'll add it for you.
Major contributors:
Doug MacEachern. A big part of this guide is built upon his email replies to users' questions.
Frank Cringle. Parts of his mod_perl FAQ has been used in the guide.
Vivek Khera. For his mod_perl performance tuning guide.
Steve Reppucci, who made a thorough review of the stuff I wrote. Fixed lots of spelling and grammar errors, and made the guide readable to English speakers :)
Eric Cholet, who wrote complete sections for the guide, and pointed out the errors the guide carried away.
Ken Williams, who reviewed a lot of stuff in the guide. Many snippets from his emails are included in the guide.
Credits of course go to ( alphabetically sorted ):
I want to thank all the people who donated their time and efforts to make this amazing idea of mod_perl a reality. This includes Doug MacEachern, the author of mod_perl, and all the developers who contributed bug patches, modules and help. And of course the numerous unseen users who helped to find bugs and advocate the mod_perl around the world.
|
||
Written by Stas Bekman.
Last Modified at 09/25/1999 |
![]() |
Use of the Camel for Perl is a trademark of O'Reilly & Associates, and is used by permission. |