[ TOC ]
The
Writing Apache Modules with Perl and C
book can be purchased online from O'Reilly
and
Amazon.com.
|
Your corrections of the technical and grammatical
errors are very welcome. You are encouraged to help me
improve this guide. If you have something to contribute
please send it
directly to me.
|
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, and for the rest of the server's life they are served from the cache. Thus the server spends its time only 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 two 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 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.)
[ TOC ]
When you run your CGI scripts by using a configuration like this:
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.
By the way, don't confuse ScriptAlias
with the ExecCGI
configuration option, which we enable so that the script will be executed
rather than returned as a plain text 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> |
[ TOC ]
META: complete
[ TOC ]
META: complete
[ TOC ]
From the viewpoint of the Perl API, Apache::Registry
is simply another handler that's not conceptually different from any other
handler. Apache::Registry
reads in the script 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 kept in memory until the
child dies.
To prevent script name collisions, Apache::Registry
creates a unique key for each cached script by prepending Apache::ROOT::
to the mangled path of the script's URI. This key is actually the package
name that 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 a 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 is discarded and recompiled using the modified
source. However, it doesn't check the modification times of any of the perl
libraries the script might use.
Apache::Registry
overrides CORE::exit()
with Apache::exit()
, so CGI scripts that use exit()
will run correctly. We will talk about all these details in depth later.
The last thing Apache::Registry
does, is emulation of mod_cgi's environment variables, like $ENV{SERVER_NAME}
, $ENV{REMOTE_USER}
and so on. PerlSetupEnv Off disables this feature which saves some memory and CPU cycles.
From the viewpoint of the programmer, there is almost no difference between running a script as a plain CGI script under mod_cgi and running it under mod_perl. There is however a great speed improvement, but at the expense of much heavier memory usage (there is no free lunch :).
When they run under mod_cgi, your CGI scripts are loaded each time they are called and then they exit. Under mod_perl they are loaded once and cached. This gives a big performance boost. But because the code is cached and doesn't exit, it won't cleanup memory as it would under mod_cgi. This can have unexpected effects.
Your scripts will be recompiled and reloaded by mod_perl when it detects
that you have changed them, but remember that any libraries that your
scripts might require()
or use()
will not be
recompiled when they are changed. You will have to take action yourself to
ensure that they are recompiled.
Of course the guide will answer all these issues in depth.
Let's see what happens to 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"; } |
The first line provides a unique namespace for the code to use, and a unique key by which the code can be referenced from the cache.
The second line imports Apache::exit
which over-rides perl's built-in exit
.
The sub handler
subroutine is wrapped around your code. By default (i.e. if you do not
specify an alternative), when you use mod_perl and your code's URI is
called, mod_perl will seek to execute the URI's associated handler
subroutine.
META: Complete
[ TOC ]
META: Complete
[ TOC ]
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 the installation and configuration of both Perl and the
Apache web server and delves deeply into the 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 to coverage of these topics in the
Getting Help 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 administering Apache servers, debugging scripts, using
databases, mod_perl related Perl, 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 documents which are part of the 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 the other documents listed in Getting Help and Further Learning you feel that your questions remain unanswered, you could try asking 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 most questions have already been asked and answered already! If you ignore this advice, do not be surprised if your question goes unanswered - it bores people when they're asked to answer the same question repeatedly - especially if the answer can be found in the archive or in the documentation. 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...) And if you do ask questions on the mailing list please make your subject line descriptive of the problem, not just ``Help'' - you're far more likely to get replies if people can see the issue you are talking about straight away.
If you find incorrect details or mistakes in my grammar, or you want to contribute to this document please feel free to send me an email at stas@stason.org .
[ TOC ]
A report prepared by Rex Staples at Thu, 14 Oct 1999:
Macromedia
4,273,000 unique visitors/month Aug-1999
Apache/1.3.4 (Unix) mod_perl/1.18 on Solaris
ValueClick: Results-based advertising network
80 million page views/day May 2000 using about 45 machines
Apache/1.3.9-dev (Unix) mod_perl/1.21_01 on FreeBSD
Deja.com
130 million pageviews/month Oct-1999
Apache/1.3b5 mod_perl/1.08 on Linux
MP3.com, Inc.
77 million page views/month Aug-1999
408,000 unique visitors/day Aug-1999
http://www.mp3.com http://www.mp3.com/pr/990914-keymetrics.html
Apache/1.3.4-9 (Unix) mod_perl/1.18-21 on Linux/FreeBSD
IMDB: Internet Movie Database
1.25 million page views/day Mar-1998
* They are now an Amazon.com company
Apache/1.3.7-dev (Unix) mod_perl/1.19_01-dev
Flash.net: Internet Service Provider
1,603,000 unique visitors/month Aug-1999
http://www.flash.net http://www.mediametrix.com/TopRankings/TopRankings.html
Apache/1.2.4 mod_perl/1.00 on Solaris
At Hand Network Yellow Pages
917,000 unique visitors/month Aug-1999
http://www.athand.com http://www.mediametrix.com/TopRankings/TopRankings.html
Stronghold/2.3 Apache/1.2.6 (Unix) mod_perl/1.15 on Solaris
Commissioner.com: Subscription Fantasy Football
12 million page views/day Oct-1999
Apache/1.35b mod_perl/1.10 on Linux
Slashdot: News For Nerds
400,000 page views/day Oct-1999
Apache/1.3.6 (Unix) mod_perl/1.21 on Linux
Hot Bot mail and member web pages:
Also widely used on HotWired, WiredNews, Webmonkey, and Suck.com
Apache/1.3.4 (Unix) mod_perl/1.21 on Solaris
Art Today: subscription clip-art service
250k hits/day
Oracle 7 + 1 Sun Ultra w/150GB storage Apache/1.3.4 (Unix) mod_perl/1.17 on Solaris
CMPnet: a technology information network
500k hits/day
Apache/1.3.9 (Unix) mod_perl/1.16
[ TOC ]
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 Apache/Perl mailing list. (To send email to modperl-subscribe@apache.org)
My personal experience with mod_perl.
I have quoted many snippets of information from FAQs and emails, but I have not credited each quote in the guide individually. 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 instead of scattering credits thoughout the Guide I have gathered them all together 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 large part of this guide is built upon his email replies to users questions.
Frank Cringle. Parts of his mod_perl FAQ have been used in this guide.
Vivek Khera. For his mod_perl performance tuning guide. And lots of useful comments on the list that made into the guide.
Steve Reppucci, who did a thorough review of the stuff I wrote. He 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 technical errors in it.
Ken Williams, who reviewed a lot of stuff in the guide. Many snippets from his emails are included in the guide.
Matt Sergeant, who contributed the section ``Exception Handling for mod_perl'' for the perl reference chapter and made many other contributions.
Wesley Darlington for contributing a big section for the scenario chapter.
Geoffrey S Young and David Harris for contributing big sections about mod_perl and RPM packages, and providing helpful comments and corrections.
Andreas J. Koenig for contributing his ``Correct HTTP headers'' document.
Ged W. Haywood for reviewing and fixing the whole guide, providing lots of constructive criticisms and helping to reorganize the guide to make it more user friendly.
Mark Summerfield for reviewing and fixing all the guide's chapters, improving guide's readability and suggesting useful extensions.
Jeffrey W. Baker for his ``guide to mod_perl database performance'' and many useful comments on the list that has been reused in the guide's material.
Richard A. Wells for reviewing and correcting a large part of the guide.
Randy Harmon for rewriting the mod_perl advocacy chapter
Dean Fitz for reviewing the ``Operating System and Hardware Demands'' chapter.
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 around the world who help to promote mod_perl and to make it a better tool. [ TOC ]
Your corrections of the technical and grammatical
errors are very welcome. You are encouraged to help me
improve this guide. If you have something to contribute
please send it
directly to me.
|
The
Writing Apache Modules with Perl and C
book can be purchased online from O'Reilly
and
Amazon.com.
|
Written by Stas Bekman. Last Modified at 03/20/2001 |
|
Use of the Camel for Perl is a trademark of O'Reilly & Associates, and is used by permission. |