You are viewing a plain text version of this content. The canonical link for it is here.
Posted to modperl-cvs@perl.apache.org by sb...@hyperreal.org on 1999/04/03 22:34:00 UTC
cvs commit: modperl-site/guide frequent.html guide-src.tar.gz perl.html CHANGES all.html config.html control.html debug.html guide.tar.gz help.html index.html intro.html obvious.html performance.html porting.html scenario.html snippets.html start.html status.html warnings.html
sbekman 99/04/03 12:33:59
Modified: guide CHANGES all.html config.html control.html
debug.html guide.tar.gz help.html index.html
intro.html obvious.html performance.html
porting.html scenario.html snippets.html start.html
status.html warnings.html
Added: guide frequent.html guide-src.tar.gz perl.html
Log:
* Rewritten the CREDITS section of the intro.html. I hope I didn't miss
anyone, if I did please tell. Lets feed the ego :)
* The guide now looks much better with StyleSheets (Nathan Vonnahme)
* added to porting.pod : Filehandlers and locks leakages (Ken Williams, Doug)
* added to obvious.pod: Handling the server timeout cases (Doug)
* created new pod: perl.pod to cover some too frequently asked pure
perl questions: opened up with "Using global variables and sharing
them between modules/packages"
* Now the pod sources available online along with the resulting htmls
and the scripts that generates them.
* Added a summary of various mod_perl deploying schemas (1/1, 2/2, DSO
and proxy). /scenario.html#More_mod_perl_deploying_schemas (Mark
Mills)
* created new frequent.pod for "Frequent mod_perl problems" as
suggested by Eric Cholet, who said that problems like 'my() scoped
variable in nested subroutines' come up so often on the list that
should be stressed in the guide as one of the most important things to
read/beware of. Since now it has only a few problems please suggest
what other ones should go here.
* obvious.pod rewritten : my() scoped variable in nested subroutines
(Eric Cholet)
* some typos fixes in intro.html, start.pod and scenario.pod (Garr
Updegraff)
* snippets.pod: Cookie handling code (Ed Park)
* obvious.pod updated: Handling the 'User pressed Stop button'
case. More hints (Eric Strovink) and apache 1.3.6 news (Henrique
Pantarotto)
* scenario.pod added : Is it possible to determine which options were
given to modperl's Makefile.PL
* More pods has been purified by Steve Reppucci (warning.pod,
obvious.pod and porting.pod). He did so much work to make them
readable, that I'm afraid to apply new changes to break all the
beauty he made :) Thanks, Steve!
Revision Changes Path
1.8 +65 -0 modperl-site/guide/CHANGES
Index: CHANGES
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/CHANGES,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- CHANGES 1999/03/16 08:20:09 1.7
+++ CHANGES 1999/04/03 20:33:49 1.8
@@ -1,6 +1,70 @@
This is a CHANGES file for mod_perl mini guide
+04.03.99
+
+
+* Rewritten the CREDITS section of the intro.html. I hope I didn't miss
+ anyone, if I did please tell. Lets feed the ego :)
+
+
+* The guide now looks much better with StyleSheets (Nathan Vonnahme)
+
+
+* added to porting.pod : Filehandlers and locks leakages (Ken Williams, Doug)
+
+
+* added to obvious.pod: Handling the server timeout cases (Doug)
+
+
+* created new pod: perl.pod to cover some too frequently asked pure
+ perl questions: opened up with "Using global variables and sharing
+them between modules/packages"
+
+
+* Now the pod sources available online along with the resulting htmls
+ and the scripts that generates them.
+
+
+* Added a summary of various mod_perl deploying schemas (1/1, 2/2, DSO
+ and proxy). /scenario.html#More_mod_perl_deploying_schemas (Mark
+ Mills)
+
+
+* created new frequent.pod for "Frequent mod_perl problems" as
+ suggested by Eric Cholet, who said that problems like 'my() scoped
+variable in nested subroutines' come up so often on the list that
+should be stressed in the guide as one of the most important things to
+read/beware of. Since now it has only a few problems please suggest
+what other ones should go here.
+
+
+* obvious.pod rewritten : my() scoped variable in nested subroutines
+ (Eric Cholet)
+
+
+* some typos fixes in intro.html, start.pod and scenario.pod (Garr
+ Updegraff)
+
+
+* snippets.pod: Cookie handling code (Ed Park)
+
+
+* obvious.pod updated: Handling the 'User pressed Stop button'
+ case. More hints (Eric Strovink) and apache 1.3.6 news (Henrique
+ Pantarotto)
+
+
+* scenario.pod added : Is it possible to determine which options were
+ given to modperl's Makefile.PL
+
+
+* More pods has been purified by Steve Reppucci (warning.pod,
+ obvious.pod and porting.pod). He did so much work to make them
+ readable, that I'm afraid to apply new changes to break all the
+ beauty he made :) Thanks, Steve!
+
+
03.15.99
@@ -250,3 +314,4 @@
* First Release
+
1.8 +1689 -838 modperl-site/guide/all.html
Index: all.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/all.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- all.html 1999/03/16 08:20:11 1.7
+++ all.html 1999/04/03 20:33:49 1.8
@@ -15,8 +15,8 @@
<CENTER><P><B>Deploying apache/mod_perl accelerator to give a rocket speed
to your perl cgi-bin scripts.</B></P></CENTER>
-<CENTER><P><B>Version 1.07 Mar, 16 1999</B></P></CENTER>
-
+<CENTER><P><B>Version 1.08 Apr, 3 1999</B></P></CENTER>
+
<P>
<HR WIDTH="100%"></P>
@@ -33,6 +33,8 @@
<LI><A HREF="control.html">Server Controlling and Monitoring</A></LI>
+<LI><A HREF="frequent.html">Frequent mod_perl problems</A></LI>
+
<LI><A HREF="porting.html">CGI to mod_perl Porting. mod_perl Coding guidelines.</A></LI>
<LI><A HREF="obvious.html">What is obvious for others but not for you</A>.</LI>
@@ -45,6 +47,8 @@
<LI><A HREF="debug.html">Code Debugging techniques</A></LI>
+<LI><A HREF="perl.html">Perl Reference</A></LI>
+
<LI><A HREF="snippets.html">Code Snippets</A></LI>
<LI><A HREF="help.html">Help. Further Learning.</A></LI>
@@ -55,7 +59,9 @@
<LI><A HREF="#search">Search perl.apache.org along with this guide</A></LI>
-<LI><A HREF="guide.tar.gz">Download as one file</A></LI>
+<LI>Download all files <A HREF="guide.tar.gz">guide.tar.gz</A>
+or sources and build scripts
+<A HREF="guide-src.tar.gz">guide-src.tar.gz</A></LI>
</UL>
@@ -93,7 +99,7 @@
<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A
HREF="help.html#author">Stas Bekman</A>.<BR> Last Modified at
-03/16/1999 </FONT></B></TD>
+04/03/1999 </FONT></B></TD>
<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" BORDER=0 ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
</TD>
@@ -256,46 +262,76 @@
all in the guide, but to centralize it here. If you think that
you want your name to show up under your original quote that I
have used, please tell me and I'll add it for you.<P>
+
+<P>Major contributors:
+
+<UL>
+ <LI><B>Doug MacEachern</B> - a big part of this guide is build upon his
+ email replies to the users' questions
+
+ <LI><B>Frank Cringle</B> - whose mod_perl FAQ lays in the basis of the guide.
-<P> Credits go to ( alphabetically sorted );
+ <LI><B>Vivek Khera</B> - for his mod_perl performance tuning guide.
+
+ <LI><B>Steve Reppucci</B> - 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 :)
+
+ <LI><B>Eric Cholet</B> - who wrote complete sections for the guide, and
+ pointed out the errors the guide carried away.
+
+ <LI><B>Ken Williams</B> - who reviewed a lot of stuff in the guide, and
+ many snippets from his emails are included in the guide.
+
+</UL>
+
+<P> Credits go of course to ( alphabetically sorted ):
<UL>
- <LI>Andreas J. Koenig
- <LI>Ask Bjoern Hansen
- <LI>Brian Moseley
- <LI>Chad K. Lewis
- <LI>David Landgren
- <LI>Doug Bagley
- <LI>Doug MacEachern
- <LI>Edmund Mergl
- <LI>Eric Cholet
- <LI>Evan A. Zacks
- <LI>Frank Cringle
- <LI>G.Richter
- <LI>Gunther Birznieks
- <LI>Howard Jones
- <LI>Jeff Baker
- <LI>Jeff Rowe
- <LI>Jon Orwant
- <LI>Ken Williams
- <LI>Leslie Mikesell
- <LI>Lincoln Stein
- <LI>Mike Fletcher
- <LI>Nancy Lin
- <LI>Nathan Torkington
- <LI>Ralf Engelschall
- <LI>Randal Schwartz
- <LI>Steve Reppucci
- <LI>Vivek Khera
+ <LI><B>Andreas J. Koenig</B>
+ <LI><B>Ask Bjoern Hansen</B>
+ <LI><B>Brian Moseley </B>
+ <LI><B>Chad K. Lewis</B>
+ <LI><B>David Landgren</B>
+ <LI><B>Doug Bagley</B>
+ <LI><B>Ed Park</B>
+ <LI><B>Edmund Mergl</B>
+ <LI><B>Evan A. Zacks</B>
+ <LI><B>G.Richter</B>
+ <LI><B>Garr Updegraff</B>
+ <LI><B>Gunther Birznieks</B>
+ <LI><B>Henrique Pantarotto</B>
+ <LI><B>Howard Jones</B>
+ <LI><B>Jeff Baker</B>
+ <LI><B>Jeff Rowe</B>
+ <LI><B>Jon Orwant</B>
+ <LI><B>Jonathan Peterson</B>
+ <LI><B>Leslie Mikesell</B>
+ <LI><B>Lincoln Stein</B>
+ <LI><B>Mark Mills</B>
+ <LI><B>Marshall Dudley</B>
+ <LI><B>Mike Fletcher</B>
+ <LI><B>Nancy Lin</B>
+ <LI><B>Nathan Torkington</B>
+ <LI><B>Nathan Vonnahme</B>
+ <LI><B>Perrin Harkins</B>
+ <LI><B>Peter Skov</B>
+ <LI><B>Radu Greab</B>
+ <LI><B>Ralf Engelschall</B>
+ <LI><B>Randal Schwartz</B>
+ <LI><B>Richard Dice</B>
+ <LI><B>Tzvetan Stoyanov</B>
+ <LI><B>Ulrich Pfeifer</B>
<LI>
<LI>Did I miss you? Tell me!
</UL>
</P>
-<P>I want to thank all the people who donated their time and efforts to
-made this amazing idea of mod_perl to become 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 the bugs and advocate mod_perl around the world.</P>
+<P>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 the bugs and advocate mod_perl around
+the world.</P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
<HR WIDTH="100%"></P>
@@ -312,8 +348,8 @@
SIZE=-1>Written by <A HREF="help.html#author">Stas Bekman</A>.<BR> Last
Modified at 03/16/1999 </FONT></B></TD>
-<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" BORDER=0 ALT="Mod Perl Icon" HEIGHT=59 WIDTH=150></A>
-</TD>
+<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg"
+BORDER=0 ALT="Mod Perl Icon" HEIGHT=59 WIDTH=150></A> </TD>
<TD><FONT SIZE=-2>Use of the Camel for Perl is <BR>
a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
@@ -335,6 +371,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -346,7 +390,7 @@
<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
- <LI><A HREF="#Coverage">Coverage </A>
+ <LI><A HREF="#Coverage">Coverage</A>
<LI><A HREF="#Downloading_the_needed_component">Downloading the needed components.</A>
<UL>
@@ -367,7 +411,7 @@
<UL>
<LI><A HREF="#Testing_by_checking_the_error_lo">Testing by checking the error_log file</A>
- <LI><A HREF="#Testing_by_viewing_perl_status">Testing by viewing /perl-status </A>
+ <LI><A HREF="#Testing_by_viewing_perl_status">Testing by viewing /perl-status</A>
<LI><A HREF="#Testing_via_telnet">Testing via telnet</A>
<LI><A HREF="#Testing_via_a_CGI_script">Testing via a CGI script</A>
<LI><A HREF="#Testing_via_lwp_request">Testing via lwp-request</A>
@@ -401,28 +445,28 @@
Perl is most likely already installed on your machine, but you should at
least check the version you using. It is highly recommended that you have
at least perl version 5.004 or higher. You can get the latest perl version
-from <A HREF="http://www.perl.com/.">http://www.perl.com/.</A> Try the
+from <A HREF="http://www.perl.com/">http://www.perl.com/</A> . Try the
direct download link <A
-HREF="http://www.perl.com/pace/pub/perldocs/latest.html.">http://www.perl.com/pace/pub/perldocs/latest.html.</A>
-
+HREF="http://www.perl.com/pace/pub/perldocs/latest.html">http://www.perl.com/pace/pub/perldocs/latest.html</A>
+.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Apache_Download">Apache Download</A></H2></CENTER>
<P>
Get the latest apache webserver from <A
-HREF="http://www.apache.org.">http://www.apache.org.</A> Try the direct
+HREF="http://www.apache.org">http://www.apache.org</A> . Try the direct
download link <A
-HREF="http://www.apache.org/dist/.">http://www.apache.org/dist/.</A>
+HREF="http://www.apache.org/dist/">http://www.apache.org/dist/</A> .
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Mod_Perl_Download">Mod_Perl Download</A></H2></CENTER>
<P>
Get the latest mod_perl from <A
-HREF="http://perl.apache.org.">http://perl.apache.org.</A> Try the direct
+HREF="http://perl.apache.org">http://perl.apache.org</A> . Try the direct
download link <A
-HREF="http://perl.apache.org/dist/.">http://perl.apache.org/dist/.</A>
+HREF="http://perl.apache.org/dist/">http://perl.apache.org/dist/</A> .
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -462,7 +506,7 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Mod_Perl">Mod_Perl</A></H2></CENTER>
<P>
-Now we come to the main point of this document.
+Now we come to the main point of this document.
<P>
Here I'll give only a short example of mod_perl installation. You should
@@ -600,8 +644,8 @@
</PRE>
<P>
Now fetch the URL <A
-HREF="http://www.you.com:8080/perl/test.pl.">http://www.you.com:8080/perl/test.pl.</A>
-You should see something like this (part of the output was snipped).
+HREF="http://www.you.com:8080/perl/test.pl">http://www.you.com:8080/perl/test.pl</A>
+. You should see something like this (part of the output was snipped).
<P>
<PRE> SERVER_SOFTWARE Apache/1.3.2 (Unix) mod_perl/1.16_01
@@ -618,6 +662,7 @@
(you'll need to add the perl line #!/bin/perl for the above script) and
fetch <A
HREF="http://www.you.com/cgi-bin/test.pl">http://www.you.com/cgi-bin/test.pl</A>
+.
<P>
<PRE> SERVER_SOFTWARE Apache/1.3.2 (Unix)
@@ -653,7 +698,7 @@
<CENTER><H2><A NAME="Testing_via_lwp_request">Testing via lwp-request</A></H2></CENTER>
<P>
Yet another one. Why do I show all these approaches? While here they are
-serving a very simple purpose, they can be helpful in other situations.
+serving a very simple purpose, they can be helpful in other situations.
<P>
Assuming you have the libwww-perl (LWP) package installed (you will need it
@@ -663,7 +708,7 @@
<PRE> % lwp-request -e -d www.site.com
</PRE>
<P>
-Will show you all the headers. (The <CODE>-d</CODE> option disables printing the response content.)
+Will show you all the headers. (The <CODE>-d</CODE> option disables printing the response content.)
<P>
<PRE> % lwp-request -e -d www.site.com | egrep '^Server:'
@@ -675,10 +720,10 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Starting_to_use_the_server">Starting to use the server</A></H1></CENTER>
<P>
-Now you are ready to start writing CGIs. Note here -- you had better start
+Now you are ready to start writing CGIs. Note here -- you better start
writing your scripts with an eye towards making them clean (i.e., <CODE>use strict;</CODE>), and with understanding of the new running environment. You have to learn
-how to write correctly for mod_perl. This is nothing new, the major item to
-remember is that your script won't die after it finishes serving the
+how to write correctly for mod_perl. There is nothing new, the major item
+to remember is that your script would not die after it finishes serving the
request, but will stay in memory and might affect all other scripts running
under the same server process (child). You will read more about it in the
following sections: <A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs</A>
@@ -697,7 +742,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/01/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
@@ -730,6 +775,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -750,7 +803,9 @@
<LI><A HREF="#httpd_perl_Server_mod_perl_">httpd_perl Server (mod_perl):</A>
</UL>
+ <LI><A HREF="#More_mod_perl_deploying_schemas">More mod_perl deploying schemas</A>
<LI><A HREF="#Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A>
+ <LI><A HREF="#Is_it_possible_to_determine_whic">Is it possible to determine which options were given to modperl's Makefile.PL</A>
</UL>
<!-- INDEX END -->
@@ -759,12 +814,12 @@
<CENTER><H1><A NAME="Making_a_Strategic_Decision">Making a Strategic Decision</A></H1></CENTER>
<P>
When running your scripts under mod_perl, you will notice that the httpd
-processes consume a huge amount of memory, from 5M to 25M and more. That's
+processes consume a huge amount of memory, from 5M to 25M and more. That is
the price you pay for the great speed improvements under mod_perl -- the
-function of Perl has has embedded in the Apache server binary.
+function of Perl embedded in the Apache server binary.
<P>
-It's overkill to serve the static objects like images and html docs with
+It is overkill to serve the static objects like images and html docs with
these larger processes. The best approach is to run two servers: a light
Apache server with no mod_perl compiled in serving the static pages, and a
heavy Apache/mod_perl server serving the CGIs in mod_perl mode only. This
@@ -776,9 +831,12 @@
Since we run two apache servers we will need two different configuration
files, log files and etc. We need a special directory layout. While some of
the directories can be shared between the two servers (assuming that both
-are built from the same source distribution) others should be separated.
-We'll refer to these two servers as <STRONG>httpd_docs</STRONG>
-(vanilla Apache) and <STRONG>httpd_perl</STRONG> (Apache/mod_perl).
+are built from the same source distribution) others should be separated. We
+will refer to these two servers as <STRONG>httpd_docs</STRONG> (vanilla Apache) and <STRONG>httpd_perl</STRONG>
+(Apache/mod_perl).
+
+<P>
+Of course there are more ways to use mod_perl. Please read <A HREF="././scenario.html#More_mod_perl_deploying_schemas">More mod_perl deploying schemas</A>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -827,15 +885,15 @@
drwxr-xr-x 8 stas stas 2048 Oct 29 17:38 modperl-1.16/
</PRE>
<P>
-Time to decide one the desired directory structure layout (where the apache
-files go):
+Time to decide on the desired directory structure layout (where the apache
+files go):
<P>
-<PRE> ROOT = /usr/apps
+<PRE> ROOT = /usr/apps
</PRE>
<P>
The two servers can share the following directories (so we will not
-duplicate data):
+duplicate data):
<P>
<PRE> /usr/apps/bin/
@@ -853,13 +911,11 @@
<P>
<PRE> /usr/apps/etc/httpd_docs/
httpd_perl/
-</PRE>
-<P>
-<PRE> /usr/apps/sbin/httpd_docs/
+
+ /usr/apps/sbin/httpd_docs/
httpd_perl/
-</PRE>
-<P>
-<PRE> /usr/apps/var/httpd_docs/logs/
+
+ /usr/apps/var/httpd_docs/logs/
proxy/
run/
httpd_perl/logs/
@@ -881,15 +937,12 @@
<P><DT><STRONG><A NAME="item_Configuration">Configuration</A></STRONG><DD>
<P>
<PRE> % cd /usr/apps/usr/src/httpd_docs/apache_1.3.2
-</PRE>
-<P>
-<PRE> % make clean
-</PRE>
-<P>
-<PRE> # gcc - compiles httpd by 100K+ smaller on AIX!
-</PRE>
-<P>
-<PRE> % env CC=gcc \
+
+ % make clean
+
+ # gcc - compiles httpd by 100K+ smaller on AIX!
+
+ % env CC=gcc \
./configure --prefix=/usr/apps \
--sbindir=/usr/apps/sbin/httpd_docs \
--sysconfdir=/usr/apps/etc/httpd_docs \
@@ -906,9 +959,8 @@
<P><DT><STRONG><A NAME="item_Compilation">Compilation:</A></STRONG><DD>
<P>
<PRE> % make
-</PRE>
-<P>
-<PRE> % make install
+
+ % make install
</PRE>
<P>
Rename 'httpd' to 'http_docs'
@@ -921,7 +973,8 @@
favorite text editor or by using perl)
<P>
-<PRE> % perl -p -i -e 's|httpd_docs/httpd|httpd_docs/httpd_docs|' /usr/apps/sbin/httpd_docs/apachectl
+<PRE> % perl -p -i -e 's|httpd_docs/httpd|httpd_docs/httpd_docs|' \
+ /usr/apps/sbin/httpd_docs/apachectl
</PRE>
</DL>
<P>
@@ -929,12 +982,13 @@
<CENTER><H2><A NAME="httpd_perl_Server_mod_perl_">httpd_perl Server (mod_perl):</A></H2></CENTER>
<P>
Before you start to configure the mod_perl sources, you should be aware
-that there a few Perl modules that have to be installed before building
-mod_perl. You will be alerted of any missing required when you run the
-<CODE>perl Makefile.PL</CODE> command line below. If you discover that you don't have these, go to your
+that there are a few Perl modules that have to be installed before building
+mod_perl. You will be alerted if any required modules are missing when you
+run the <CODE>perl Makefile.PL</CODE> command line below. If you discover that you do not have these, go to your
nearest CPAN repository (if you don't know what is it, go to <A
HREF="http://www.perl.com/CPAN">http://www.perl.com/CPAN</A> ) or run the
-CPAN interactive shell via the command line <CODE>perl -MCPAN -e shell</CODE> .
+CPAN interactive shell via the command line <CODE>perl -MCPAN -e
+shell</CODE> .
<P>
Now back to installation.
@@ -983,14 +1037,16 @@
/usr/apps/usr/src/httpd_perl/apache_1.3.2/src/httpd
<P>
-Note: You have noted that we didn't go to the apache's source dir and run <CODE>make install</CODE>. When <CODE>USE_APACI</CODE> is enabled, <CODE>APACHE_PREFIX</CODE> will specify the --prefix option for Apache's configure script, specifying
+Note: You may have noted that we did not go to the apache's source dir and
+run <CODE>make install</CODE>. When <CODE>USE_APACI</CODE> is enabled,
+<CODE>APACHE_PREFIX</CODE> will specify the --prefix option for Apache's configure script, specifying
the installation path for Apache. When this option is used, mod_perl's make
install will also make install on the Apache side, installing the httpd
binary, support tools, along with the configuration, log and document
trees.
<P>
-If make test fails, look into t/logs and see what's in there.
+If make test fails, look into t/logs and see what is in there.
<P>
Rename the 'httpd' to 'httpd_perl'
@@ -1003,13 +1059,82 @@
by using perl)
<P>
-<PRE> % perl -p -i -e 's|httpd_perl/httpd|httpd_perl/httpd_perl|' /usr/apps/sbin/httpd_perl/apachectl
+<PRE> % perl -p -i -e 's|httpd_perl/httpd|httpd_perl/httpd_perl|' \
+ /usr/apps/sbin/httpd_perl/apachectl
</PRE>
<P>
Now proceed to the <A HREF="././config.html#">Server Configuration</A> section.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="More_mod_perl_deploying_schemas">More mod_perl deploying schemas</A></H1></CENTER>
+<P>
+There are several different ways to build, configure and deploy your
+mod_perl enabled site. Some of the ways are:
+
+<OL>
+<P><LI>
+<P>
+1 binary and 1 config file (suffer a big binary for all kind of objects)
+
+<P><LI>
+<P>
+2 binaries and 2 config files (one big binary for mod_perl and one small
+for static object like images)
+
+<P><LI>
+<P>
+1 DSO style compile and 2 confs (Dynamic linking lets you compile once and
+have a big and a small binary in memory BUT you have to deal with a freshly
+made solution that has week documentation and is still subject to change
+and is rather more complex)
+
+<P><LI>
+<P>
+Any of the 3 approaches above plus proxy server in the http accelerator
+mode (squid was reported to be the best as of this writing).
+
+<P>
+<META> The proxy section should be added shortly. I am still trying
+to figure out how to ride the beast. If you have the experience with squid,
+your contributions are very important and welcome.</META>
+
+</OL>
+<P>
+If you are a newbie, I would recommend you to start with the first option
+and work on getting your feet wet with apache and mod_perl, then decide
+whether to move to a second one for production work or move up to the more
+state-of-the-art-yet-suspiciously-new DSO system (third) )or/and proven to
+be good forth option from above.
+
+<P>
+Option 1 will kill you in production if you load out a lot of static data
+with a 2-12 MB webserver process. On the other hand while testing you will
+have no other server interaction to mask or add to your errors.
+
+<P>
+Option 2 means keeping two compiles but lets you seriously tune the two
+binaries to their exact purpose. On the other hand you have to deal with
+proxying or fancy site design to keep the two servers in step. Choose
+serving on multiple ports, multiple IPs, etc...
+
+<P>
+Option 3 (DSO) -- as mentioned above -- means playing with the bleeding
+edge. Also the <CODE>mod_so</CODE> adds size and complexity to your binaries. The benefit being that modules
+can be added and removed with out recompiling and even shared amongst
+multiple servers. Again, it is bleeding edge and still sort of platform
+wonky so YMMV.
+
+<P>
+<META> Does anyone want to write a section for DSO? </META>
+
+<P>
+Option 4 (proxy in http accelerator mode) - should make you lots of good
+things, once correctly configured and tuned. Stay tuned for more
+information.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A></H1></CENTER>
<P>
Yes, no problem with that. Follow the instructions above and when you
@@ -1052,6 +1177,39 @@
<P>
<STRONG>c</STRONG>. Look for another ISP with lots of resources or one that supports mod_perl
(not likely)
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Is_it_possible_to_determine_whic">Is it possible to determine which options were given to modperl's Makefile.PL</A></H1></CENTER>
+<P>
+It is possible to determine which options were given to modperl's
+Makefile.PL during the configuration stage, so to be used later in
+recreating the same build tree when rebuilding the server. This is relevant
+only if did not use the default config parameters and altered some of them
+during the configuration stage.
+
+<P>
+I was into this problem many times. I'm going to build something pass some
+non default parameters to the config script and then later when I need to
+rebuild the tool either to upgrade it or to make an indentical copy at some
+other machine, I have found that I do not remember what parameters did I
+altered.
+
+<P>
+The best solution for this problem is to prepare the run file with all the
+parameters that are about to be used and then run it instead of typing it
+all by hand. So later I will have the script handy to be reused.
+
+<P>
+mod_perl suggests using the <CODE>makepl_args.mod_perl</CODE> file which comes with mod_perl distribution. This is the file you specify
+all the parameters you are going to use.
+
+<P>
+But if you have found yourself with a compiled tool and no traces of the
+specified parameters left, you can still find them out if the sources were
+not <CODE>make clean</CODE>'d. So you will find the apache specific parameters in <CODE>apache_x.x.x/config.status</CODE> and modperl's at in
+<CODE>mod_perl_x.xx/apaci/mod_perl.config</CODE>.
+
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P><A HREF="index.html">[Back to the main page]</A></P>
@@ -1066,7 +1224,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/14/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
@@ -1099,6 +1257,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -1179,9 +1345,8 @@
# Apache::Registry mode
Alias /perl/ /usr/apps/myproject/cgi/
-</PRE>
-<P>
-<PRE> # Apache::PerlRun mode
+
+ # Apache::PerlRun mode
Alias /cgi-perl/ /usr/apps/myproject/cgi/
</PRE>
<P>
@@ -1194,10 +1359,10 @@
<STRONG>http://www.you.com/perl/test.pl</STRONG> will be mapped to
<STRONG>/usr/apps/myproject/cgi/test.pl</STRONG>. This means you can have all your CGIs located at the same place at
filesystem, and call the script in any of three modes simply by changing
-the directory name component of the URL (cgi-bin|perl|cgi-perl) - isn't
-that cool? (That's the configuration you see above - all three Aliases
+the directory name component of the URL (cgi-bin|perl|cgi-perl) - is not
+that cool? (That is the configuration you see above - all three Aliases
point to the same directory within your filesystem, but of course they can
-be different). If your script doesn't seem to be working while running
+be different). If your script does not seem to be working while running
under mod_perl, you can easily call the script in straight mod_cgi mode
without making any script changes (in most cases), but rather by changing
the URL you invoke it by.
@@ -1213,10 +1378,10 @@
<P>
Of course you can choose any other alias (you will use it later in
-http.conf), you can choose to use all three modes or only one of these
-(It's undesirable to run plain cgi-bin scripts from a mod_perl-enabled
-server - the price is too high, it's better to run these on plain Apache
-server. See <A HREF="././scenario.html#Making_a_strategic_decision">Real World scenario</A> for details.)
+http.conf), you can choose to use all three modes or only one of these (It
+is undesirable to run plain cgi-bin scripts from a mod_perl-enabled server
+- the price is too high, it is better to run these on plain Apache server.
+See <A HREF="././scenario.html#Making_a_strategic_decision">Real World scenario</A> for details.)
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -1250,11 +1415,11 @@
<P>
Remember the <STRONG>Alias</STRONG> from the section above? We must use the same Alias here, if you use
-Location that doesn't have the same Alias defined in srm.conf, the server
+Location that does not have the same Alias defined in srm.conf, the server
will fail to locate the script in the filesystem. (We're talking about
-script execution here -- there are cases where Location is something that's
-being executed by the server itself, without having the corresponding file,
-like <A HREF="#perl_status">perl-status</A>.)
+script execution here -- there are cases where Location is something that
+is being executed by the server itself, without having the corresponding
+file, like <A HREF="#perl_status">perl-status</A>.)
<P>
Note that sometimes you will have to add : PerlModule Apache::Registry
@@ -1269,7 +1434,7 @@
with mod_perl
<P>
-Here's a similar location configuration for Apache::PerlRun. (More about
+Here is a similar location configuration for Apache::PerlRun. (More about
<A HREF="././porting.html#Apache_PerlRun_a_closer_look">Apache::PerlRun</A>)
<P>
@@ -1330,12 +1495,13 @@
# (but not to import) its autoloaded methods.
use CGI ();
CGI->compile(':all');
-
+</PRE>
+<P>
Note that starting with CGI::VERSION 2.46, the recommended method to
precompile the code in CGI.pm is:
-</PRE>
+
<P>
-<PRE> use CGI qw(-compile :all);
+<PRE> use CGI qw(-compile :all);
</PRE>
<P>
But the old method is still available for backword compatibility.
@@ -1351,7 +1517,7 @@
on server restart, add:
<P>
-<PRE> PerlFreshRestart On
+<PRE> PerlFreshRestart On
</PRE>
<P>
Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
@@ -1399,7 +1565,7 @@
can then walk and grind the names and values of Perl variables/structures
through the Apache core configuration gears. Most of the configurations
directives can be represented as scalars (<STRONG>$scalar</STRONG>) or lists (<STRONG>@list</STRONG>). An <CODE>@List</CODE> inside these sections is simply converted into a space delimited string for
-you inside. Here's an example:
+you inside. Here is an example:
<P>
<PRE> #httpd.conf
@@ -1438,12 +1604,10 @@
<P>
<PRE> push @Redirect, "/foo", "<A HREF="http://www.foo.com/"">http://www.foo.com/"</A>;;
-</PRE>
-<P>
-<PRE> push @Redirect, "/imdb", "<A HREF="http://www.imdb.com/"">http://www.imdb.com/"</A>;;
-</PRE>
-<P>
-<PRE> push @Redirect, [qw(temp "/here" "<A HREF="http://www.there.com"">http://www.there.com"</A>;)];
+
+ push @Redirect, "/imdb", "<A HREF="http://www.imdb.com/"">http://www.imdb.com/"</A>;;
+
+ push @Redirect, [qw(temp "/here" "<A HREF="http://www.there.com"">http://www.there.com"</A>;)];
</PRE>
<P>
Other section counterparts include <STRONG>%VirtualHost</STRONG>,
@@ -1484,8 +1648,8 @@
Now you may run <STRONG>perl -cx httpd.conf</STRONG>.
<P>
-To configure this feature build with
-<STRONG>perl Makefile.PL PERL_SECTIONS=1' </STRONG>
+To configure this feature build with <STRONG>perl Makefile.PL
+PERL_SECTIONS=1' </STRONG>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -1549,7 +1713,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/15/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
@@ -1582,6 +1746,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -1810,35 +1982,33 @@
Crontab entry:
<P>
-0,30 * * * * /path/to/the/apache.watchdog >/dev/null 2>&1
-
+<PRE> 0,30 * * * * /path/to/the/apache.watchdog >/dev/null 2>&1
+</PRE>
<P>
The script:
<P>
<PRE> #!/bin/sh
-
+
# this script is a watchdog to see whether the server is online
# It tries to restart the server if it's
# down and sends an email alert to admin
-</PRE>
-<P>
-<PRE> # admin's email
+
+ # admin's email
EMAIL=webmaster@somewhere.far
#EMAIL=root@localhost
-
+
# the path to your PID file
PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid
-
+
# the path to your httpd binary, including options if necessary
HTTPD=/usr/apps/sbin/httpd_perl/httpd_perl
-
+
# check for pidfile
if [ -f $PIDFILE ] ; then
PID=`cat $PIDFILE`
-</PRE>
-<P>
-<PRE> if kill -0 $PID; then
+
+ if kill -0 $PID; then
STATUS="httpd (pid $PID) running"
RUNNING=1
else
@@ -1849,7 +2019,7 @@
STATUS="httpd (no pid file) not running"
RUNNING=0
fi
-
+
if [ $RUNNING -eq 0 ]; then
echo "$0 $ARG: httpd not running, trying to start"
if $HTTPD ; then
@@ -1911,20 +2081,17 @@
my $message = ($status == 0)
? "Server was down and successfully restarted!"
: "Server is down. Can't restart.";
-</PRE>
-<P>
-<PRE> my $subject = ($status == 0)
+
+ my $subject = ($status == 0)
? "Attention! Webserver restarted"
: "Attention! Webserver is down. can't restart";
-</PRE>
-<P>
-<PRE> # email the monitoring person
+
+ # email the monitoring person
my $to = $monitor_email;
my $from = $monitor_email;
send_mail($from,$to,$subject,$message);
-</PRE>
-<P>
-<PRE> # input: URL to check
+
+ # input: URL to check
# output: 1 if success, o for fail
#######################
sub checkurl{
@@ -1944,9 +2111,8 @@
#######################
sub send_mail{
my($from,$to,$subject,$messagebody) = @_;
-</PRE>
-<P>
-<PRE> open MAIL, "|$mail_program"
+
+ open MAIL, "|$mail_program"
or die "Can't open a pipe to a $mail_program :$!\n";
print MAIL <<__END_OF_MAIL__;
@@ -2028,16 +2194,25 @@
<PRE> % http_perl -Dsbekman
</PRE>
<P>
-At the end of the httpd.conf I wrote: # Personal development Server for
-sbekman # sbekman use the server running on port 8000 <IfDefine
-sbekman> Port 8000 PidFile
-/usr/apps/var/httpd_perl/run/httpd.pid.sbekman ErrorLog
-/usr/apps/var/httpd_perl/logs/error_log.sbekman Timeout 300 KeepAlive On
-MinSpareServers 2 MaxSpareServers 2 StartServers 1 MaxClients 3
-MaxRequestsPerChild 15 </IfDefine>
+At the end of the httpd.conf I wrote:
<P>
-<PRE> # Personal development Server for userfoo
+<PRE> # Personal development Server for sbekman
+ # sbekman use the server running on port 8000
+ <IfDefine sbekman>
+ Port 8000
+ PidFile /usr/apps/var/httpd_perl/run/httpd.pid.sbekman
+ ErrorLog /usr/apps/var/httpd_perl/logs/error_log.sbekman
+ Timeout 300
+ KeepAlive On
+ MinSpareServers 2
+ MaxSpareServers 2
+ StartServers 1
+ MaxClients 3
+ MaxRequestsPerChild 15
+ </IfDefine>
+
+ # Personal development Server for userfoo
# userfoo use the server running on port 8001
<IfDefine userfoo>
Port 8001
@@ -2191,9 +2366,8 @@
# we want to make a complete emulation, so we must remove the
# user's environment
@INC = ();
-</PRE>
-<P>
-<PRE> # local perl libs
+
+ # local perl libs
push @INC, ("$basedir/lib/perl5/5.00502/aix",
"$basedir/lib/perl5/5.00502",
"$basedir/lib/perl5/site_perl/5.005/aix",
@@ -2301,24 +2475,19 @@
<PRE> #!/usr/bin/perl -Tw
use strict;
use File::Basename;
-</PRE>
-<P>
-<PRE> $ENV{PATH} = "/usr/ucb:/bin:/usr/bin";
-</PRE>
-<P>
-<PRE> my $ROOT = "/WWW/apache"; # names are relative to this
+
+ $ENV{PATH} = "/usr/ucb:/bin:/usr/bin";
+
+ my $ROOT = "/WWW/apache"; # names are relative to this
my $CONF = "$ROOT/conf/httpd.conf"; # master conf
my $MIDNIGHT = "MIDNIGHT"; # name of program in each logdir
-</PRE>
-<P>
-<PRE> my ($user_id, $group_id, $pidfile); # will be set during parse of conf
+
+ my ($user_id, $group_id, $pidfile); # will be set during parse of conf
die "not running as root" if $>;
-</PRE>
-<P>
-<PRE> chdir $ROOT or die "Cannot chdir $ROOT: $!";
-</PRE>
-<P>
-<PRE> my %midnights;
+
+ chdir $ROOT or die "Cannot chdir $ROOT: $!";
+
+ my %midnights;
open CONF, "<$CONF" or die "Cannot open $CONF: $!";
while (<CONF>) {
if (/^User (\w+)/i) {
@@ -2339,22 +2508,20 @@
$midnights{$midnight}++;
}
close CONF;
-</PRE>
-<P>
-<PRE> die "missing User definition" unless defined $user_id;
+
+ die "missing User definition" unless defined $user_id;
die "missing Group definition" unless defined $group_id;
die "missing PidFile definition" unless defined $pidfile;
-</PRE>
-<P>
-<PRE> open PID, $pidfile or die "Cannot open $pidfile: $!";
+
+ open PID, $pidfile or die "Cannot open $pidfile: $!";
<PID> =~ /(\d+)/;
my $httpd_pid = $1;
close PID;
die "missing pid definition" unless defined $httpd_pid and $httpd_pid;
kill 0, $httpd_pid or die "cannot find pid $httpd_pid: $!";
-</PRE>
-<P>
-<PRE> for (sort keys %midnights) {
+
+
+ for (sort keys %midnights) {
defined(my $pid = fork) or die "cannot fork: $!";
if ($pid) {
## parent:
@@ -2368,9 +2535,8 @@
die "cannot exec $MIDNIGHT: $!";
}
}
-</PRE>
-<P>
-<PRE> kill 1, $httpd_pid or die "Cannot sighup $httpd_pid: $!";
+
+ kill 1, $httpd_pid or die "Cannot sighup $httpd_pid: $!";
</PRE>
<P>
And then individual MIDNIGHT scripts can look like this:
@@ -2378,9 +2544,8 @@
<P>
<PRE> #!/usr/bin/perl -Tw
use strict;
-</PRE>
-<P>
-<PRE> die "bad guy" unless getpwuid($<) =~ /^(root|nobody)$/;
+
+ die "bad guy" unless getpwuid($<) =~ /^(root|nobody)$/;
my @LOGFILES = qw(access_log error_log);
umask 0;
$^I = ".".time;
@@ -2451,7 +2616,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/16/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
@@ -2484,6 +2649,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -2504,7 +2677,7 @@
<UL>
<LI><A HREF="#Script_s_namespace">Script's namespace</A>
- <LI><A HREF="#Names_collisions_with_Modules_an">Names collisions with Modules and libs</A>
+ <LI><A HREF="#Name_collisions_with_Modules_and">Name collisions with Modules and libs</A>
<LI><A HREF="#_END_or_DATA_tokens">__END__ or __DATA__ tokens</A>
<LI><A HREF="#Output_from_system_calls">Output from system calls</A>
<LI><A HREF="#Using_format_">Using format()</A>
@@ -2516,16 +2689,20 @@
<LI><A HREF="#BEGIN_blocks">BEGIN blocks </A>
<LI><A HREF="#END_blocks">END blocks </A>
<LI><A HREF="#Switches_w_T">Switches -w, -T</A>
- <LI><A HREF="#Switches_w_T">Switches -w, -T</A>
</UL>
<LI><A HREF="#strict_pragma">strict pragma</A>
<LI><A HREF="#Turning_warnings_ON">Turning warnings ON</A>
<LI><A HREF="#diagnostics_pragma">diagnostics pragma</A>
<LI><A HREF="#Global_Variables">Global Variables</A>
- <LI><A HREF="#Code_has_been_changed_but_seems">Code has been changed, but seems that script uses the old code</A>
- <LI><A HREF="#Memory_leakages">Memory leakages</A>
- <LI><A HREF="#Sometimes_it_works_Sometimes_Not">Sometimes it works Sometimes Not (Very important!)</A>
+ <LI><A HREF="#Code_has_been_changed_but_it_se">Code has been changed, but it seems the script is running the old code</A>
+ <LI><A HREF="#Memory_leakage">Memory leakage</A>
+ </UL>
+
+ <LI><A HREF="#Filehandlers_and_locks_leakages">Filehandlers and locks leakages</A>
+ <UL>
+
+ <LI><A HREF="#Sometimes_it_Works_Sometimes_Not">Sometimes it Works Sometimes Not (Very important!)</A>
<LI><A HREF="#The_Script_is_too_dirty_It_does">The Script is too dirty, It does the job and I can't afford rewriting it.</A>
<LI><A HREF="#Apache_PerlRun_a_closer_look">Apache::PerlRun - a closer look</A>
</UL>
@@ -2538,32 +2715,34 @@
<P>
<CENTER><H1><A NAME="Document_Coverage">Document Coverage</A></H1></CENTER>
<P>
-This document is relevant for both - writing a new cgi from scratch and
-migrating from the plain cgi to mod_perl.
+This document is relevant to both writing a new CGI from scratch and
+migrating an application from plain CGI to mod_perl.
<P>
-If you are in the porting stage use it as a reference for possible problems
-you might encounter when running the existent CGI in the new mode.
+If you are in the porting stage, use it as a reference for possible
+problems you might encounter when running the existent CGI in the new mode.
<P>
-If you are about to write a new cgi from scratch, it would be a good idea
+If you are about to write a new CGI from scratch, it would be a good idea
to learn most of the possible pitfalls and to avoid them in first place.
<P>
-It covers also the case when the script is too dirty, but does the job and
-I can't afford rewriting it. (Apache::PerlRun)
+It covers also the case where the CGI script being ported does the job, but
+is too dirty to be easily altered to run as a mod_perl program.
+(Apache::PerlRun)
<P>
-If your project in hurry, I would think of the following steps: First run
-all the scripts in the Apache::PerlRun mode - then as time allows you, move
-them into Apache::Registry mode.
+If your project schedule is tight, I would suggest converting to mod_perl
+in the following steps: Initially, run all the scripts in the
+Apache::PerlRun mode. Then as time allows, move them into Apache::Registry
+mode.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Before_you_start_to_code">Before you start to code</A></H1></CENTER>
<P>
-It can be a good idea to strengthen some of the programming skills, since
-Apache::Registry doesn't allow sloppiness programming.
+It can be a good idea to tighten up some of your Perl programming
+practices, since Apache::Registry doesn't allow sloppy programming.
<P>
You might want to read:
@@ -2571,55 +2750,57 @@
<UL>
<P><LI><STRONG><A NAME="item_Perl">Perl Module Mechanics</A></STRONG>
<P>
-This page describes the mechanics of creating, compiling, releasing and
+This page describes the mechanics of creating, compiling, releasing, and
maintaining Perl modules. <A
HREF="http://world.std.com/~swmcd/steven/perl/module_mechanics.html">http://world.std.com/~swmcd/steven/perl/module_mechanics.html</A>
<P><LI><STRONG><A NAME="item_Mod">Mod Perl Book</A></STRONG>
<P>
-(when it will be released) - you can find parts of the book online at <A
-HREF="http://www.modperl.com.">http://www.modperl.com.</A>
+A must have book! See the details at <A
+HREF="http://www.modperl.com">http://www.modperl.com</A> .
</UL>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Coding_with_mod_perl">Coding with mod_perl</A></H1></CENTER>
<P>
-First, before you start coding for Apache::Registry you have to change the
-state of your mind. Scripts running under mod_perl are like subroutines are
-being called from the daemon who runs all the time. Imagine the daemon
-process that when requested to process some of the scripts - reads it in,
-compiles it as a subroutine and finally executes it. On any subsequent
-request it'll just recall the already compiled subroutine. Hope that you
+Before you start coding for Apache::Registry, you have to change your
+programming state of mind. Scripts running under mod_perl are like
+subroutines are being called from a continually running daemon. Imagine a
+daemon process that when requested to process some script, reads it in,
+compiles it as a subroutine, and finally executes it. On any subsequent
+request, it'll just recall the already compiled subroutine. Hope that you
get the idea.
<P>
The best thing you do when coding from scratch is to make it clean and use
-packages, as you go thru the notes you will understand why.
+packages. By ``make it clean'' we mean make certain that you <STRONG>use strict;</STRONG>
+and that your script produces no warnings when tested via
+<STRONG>perl -cw myscript.pl</STRONG>. As you go thru the notes you will understand why.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="What_s_different_about_modperl">What's different about modperl</A></H2></CENTER>
<P>
-There are a few things that behaves differently under mod_perl. It's good
-to know what they are.
+There are a few things that behave differently under mod_perl. It's good to
+know what they are.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H3><A NAME="Script_s_namespace">Script's namespace</A></H3></CENTER>
<P>
-Scripts under Apache::Registry do not run in package <STRONG>main</STRONG>, they run in a unique namespace based on the requested uri. e.g if your
-uri is /perl/test.pl the package will be called
-Apache::ROOT::perl::test_2epl;
+Scripts under Apache::Registry do not run in package <STRONG>main</STRONG>, they run in a unique namespace based on the requested uri. For example,
+if your uri is <STRONG>/perl/test.pl</STRONG> the package will be called
+<STRONG>Apache::ROOT::perl::test_2epl;</STRONG>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="Names_collisions_with_Modules_an">Names collisions with Modules and libs</A></H3></CENTER>
+<CENTER><H3><A NAME="Name_collisions_with_Modules_and">Name collisions with Modules and libs</A></H3></CENTER>
<P>
-Just to make things clear before we go into details: each server process
-has its own <CODE>%INC</CODE> array which is used to store the information
-about compiled modules. Where the keys are the names of the modules or
-parameters passed to <CODE>require().</CODE> And values are the real paths
+Just to make things clear before we go into detail: each server process has
+its own <CODE>%INC</CODE> hash which is used to store information about its
+compiled modules. The keys of the hash are the names of the modules or
+parameters passed to <CODE>require().</CODE> The values are the real paths
to these modules. So if you do (assume it's in the <CODE>@INC</CODE> path)
<P>
@@ -2636,7 +2817,7 @@
<P>
You can't have 2 identical module names running under the same server! Only
-the first one <CODE>use()d</CODE> or <CODE>require()d</CODE> will be
+the first one <CODE>use()'d</CODE> or <CODE>require()'d</CODE> will be
compiled into the package, the request to the other identical module will
be skipped since server will think that it's already compiled. It'll be
already in child's %INC. (See <A HREF="././status.html#Watching_the_server">Watching the server</A>
@@ -2654,7 +2835,7 @@
<P>
And both scripts do: <CODE>use Foo;</CODE> only the first one called will know about Foo, when you will call the
second script it will not know about Foo at all - it's like you've
-forgotten to write <CODE>use Foo;</CODE>. Run the server in the <A HREF="././control.html#Single_Mode_Running">single server mode</A> to solve that kind of bug immediately.
+forgotten to write <CODE>use Foo;</CODE>. Run the server in <A HREF="././control.html#Single_Mode_Running">single server mode</A> to solve that kind of bug immediately.
<P>
You will see the following in the error_log file:
@@ -2691,7 +2872,8 @@
<OL>
<P><LI>
<P>
-Add some special path so the fs layout will be something like
+Place your library modules in a subdirectory structure so that they have
+different path prefixes. The file system layout will be something like
<P>
<PRE> cgi/tool1/Tool1/Foo.pm
@@ -2700,14 +2882,14 @@
cgi/tool2/tool2.pl
</PRE>
<P>
-And you change the scripts:
+And change the scripts:
<P>
<PRE> use Tool1::Foo;
use Tool2::Foo;
</PRE>
<P>
-and respectively the package declaration in the modules:
+and respectively, the package declaration in the modules:
<P>
<PRE> package Tool1::Foo;
@@ -2732,11 +2914,12 @@
<P>
<PRE> use lib qw(.);
require "tool2-lib/config.pl";
+
</PRE>
<P><LI>
<P>
-Or use a full path to the script, so it'll be compiled into the name of the
-key in the %INC;
+Another option is to use a full path to the script, so it'll be compiled
+into the name of the key in the %INC;
<P>
<PRE> require "/full/path/to/the/config.pl";
@@ -2752,8 +2935,8 @@
package name for the key!
<P>
-But then you will have to use Package::function() method unless you will
-export the symbols from the <CODE>use()d</CODE> package like
+But then you will have to use <STRONG>Package::function()</STRONG> method unless you will export the symbols from the <CODE>use()'d</CODE>
+package like:
<P>
<PRE> use Package qw(:all_subs);
@@ -2763,7 +2946,7 @@
process.
<P>
-<STRONG>Important:</STRONG> Only this solution will work, if you have 2 scripts that
+<STRONG>Important:</STRONG> This solution will only work if you have two scripts that
<CODE>require()</CODE> the same file!
<P>
@@ -2801,39 +2984,38 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H3><A NAME="Output_from_system_calls">Output from system calls</A></H3></CENTER>
<P>
-Output of system, exec and open PIPE, ``|program'' calls will not be sent
-to the browser unless you Perl was configured with sfio.
+Output of <STRONG>system</STRONG>, <STRONG>exec</STRONG>, and <STRONG>open PIPE "|program"</STRONG> calls will not be sent to the browser unless your Perl was configured with
+sfio.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H3><A NAME="Using_format_">Using format()</A></H3></CENTER>
<P>
-Currently Possible Only if you have perl compiled with sfio
+Currently possible only if you have perl compiled with sfio
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H3><A NAME="Using_exit_">Using exit()</A></H3></CENTER>
<P>
-Perl's <CODE>exit()</CODE> built-in function cannot be used in mod_perl
-scripts. Unless you want the server child to exit (which makes the whole
-idea of using mod_perl irrelevant). The Apache::exit() function should be
-used instead.
+Perl's <STRONG>exit()</STRONG> built-in function cannot be used in mod_perl scripts. Calling it causes the
+server child to exit (which makes the whole idea of using mod_perl
+irrelevant.) The <STRONG>Apache::exit()</STRONG> function should be used instead.
<P>
-You might start you scripts with overriding the exit sub (if you use
-directly the Apache::exit() you will have the problem to test the script
-from the shell, unless you stuff <CODE>use Apache ();</CODE> into your code. I use the following code:
+You might start your scripts by overriding the exit sub (if you use
+<STRONG>Apache::exit()</STRONG> directly, you will have a problem testing the script from the shell, unless
+you stuff <CODE>use Apache ();</CODE> into your code.) I use the following code:
<P>
<PRE> BEGIN {
# Auto-detect if we are running under mod_perl or CGI.
- $USE_MOD_PERL = ( (exists $ENV{'GATEWAY_INTERFACE'} and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
+ $USE_MOD_PERL = ( (exists $ENV{'GATEWAY_INTERFACE'}
+ and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
or exists $ENV{'MOD_PERL'} ) ? 1 : 0;
}
use subs (exit);
-</PRE>
-<P>
-<PRE> # Select the correct exit way
+
+ # Select the correct exit way
########
sub exit{
# Apache::exit(-2) will cause the server to exit gracefully,
@@ -2842,27 +3024,27 @@
}
</PRE>
<P>
-Now every time the select code will be called and the correct exit will be
-picked, no matter if you run the script as cgi or from shell.
+Now each time the select code is called, the correct <STRONG>exit</STRONG>
+will be chosen, whether you run the script as a CGI or from the shell.
<P>
<STRONG>Note</STRONG> that if you run the script under <CODE>Apache::Registry</CODE>, <STRONG>The
Apache function `exit' overrides the Perl core built-in
function</STRONG>. While you see the <CODE>exit()</CODE> listed in <CODE>@EXPORT_OK</CODE>
of Apache package, Apache::Registry makes something you don't see and
-imports this function for you. (which means that if your script is running
-under Apache::Registry handler, you don't have to worry about
-<CODE>exit(),</CODE> Apache::PerlRun as well)
+imports this function for you. This means that if your script is running
+under Apache::Registry handler (Apache::PerlRun as well), you don't have to
+worry about <CODE>exit().</CODE>
<P>
<STRONG>Note</STRONG> that if you still use CORE::exit() in your scripts running under modperl,
the child will exit, but neither proper exit nor logging will happen on the
-way. CORE::exit() cuts off server's legs... If you need to properly
-shutdown the child , use $r->child_terminate (which sets the internal
-MaxRequestsPerChild so the child will exit).
+way. CORE::exit() cuts off the server's legs... If you need to properly
+shutdown the child , use $r->child_terminate (which sets the internal MaxRequestsPerChild so the child
+will exit).
<P>
-You can accomplish that in 2 ways - in the Apache::Registry script:
+You can accomplish this in 2 ways - in the Apache::Registry script:
<P>
<PRE> Apache->request->child_terminate;
@@ -2879,17 +3061,16 @@
<P>
Your scripts <CODE>*will</CODE> not* run from the command line (yet) unless
you use CGI::Switch or CGI.pm and 5.004+ and do not make any direct calls
-to Apache->methods. Since it's different environment and See also above.
+to Apache->methods.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H3><A NAME="I_O_is_different">I/O is different</A></H3></CENTER>
<P>
-If you are using Perl 5.004 most CGI scripts can run under mod_perl
-untouched. If you're using 5.003, Perl's built-in <CODE>read()</CODE> and
-<CODE>print()</CODE> functions do not work as they do under CGI. If you're
-using CGI.pm, use $query->print instead of plain 'ol
-<CODE>print().</CODE>
+If you are using Perl 5.004 or better, most CGI scripts can run under
+mod_perl untouched. If you're using 5.003, Perl's built-in
+<CODE>read()</CODE> and <CODE>print()</CODE> functions do not work as they
+do under CGI. If you're using CGI.pm, use $query->print instead of plain 'ol <CODE>print().</CODE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -2907,11 +3088,10 @@
terminating newline, your script must send that itself, e.g.:
<P>
-<PRE> print "Content-type: text/html\n\n";
+<PRE> print "Content-type: text/html\r\n\r\n";
</PRE>
<P>
-If you're using CGI.pm or CGI::Switch and 'print $q->header' you do
-_not_ need PerlSendHeader On.
+If you're using CGI.pm or CGI::Switch and <STRONG>print $q->header</STRONG> you do _not_ need PerlSendHeader On.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -2924,11 +3104,11 @@
<PRE> local $| = 1;
</PRE>
<P>
-And If you normally set PerlSendHeader On, add this to your httpd.conf:
+And if you normally set PerlSendHeader On, add this to your httpd.conf:
<P>
<PRE> <Files */nph-*>
- PerlSendHeader Off
+ PerlSendHeader Off
</Files>
</PRE>
<P>
@@ -2937,31 +3117,61 @@
<P>
Perl executes BEGIN blocks during the compile time of code as soon as
possible. The same is true under mod_perl. However, since mod_perl normally
-only compiles scripts and modules once, in the parent server or once
-per-child, BEGIN blocks in that code will only be run once. As perlmod
-explains, once a BEGIN has run, it is immediately undefined. In the
+only compiles scripts and modules once -- either in the parent server or
+once per-child -- BEGIN blocks in that code will only be run once. As
+perlmod explains, once a BEGIN has run, it is immediately undefined. In the
mod_perl environment, this means BEGIN blocks will not be run during each
incoming request unless that request happens to be one that is compiling
the code.
<P>
Modules and files pulled in via require/use which contain BEGIN blocks will
-be executed: - only once, if pulled in by the parent process - once
-per-child process if not pulled in by the parent process - an additional
-time, once per-child process if the module is pulled in off of disk again
-via Apache::StatINC - an additional time, in the parent process on each
-restart if PerlFreshRestart is On - unpredictable if you fiddle with
-<CODE>%INC</CODE> yourself.
+be executed:
+
+<DL>
+<P><DT><STRONG><A NAME="item__">-</A></STRONG><DD>
+<P>
+only once, if pulled in by the parent process.
+
+<P><DT><STRONG>-</STRONG><DD>
+<P>
+once per-child process if not pulled in by the parent process.
+
+<P><DT><STRONG>-</STRONG><DD>
+<P>
+an additional time, once per-child process if the module is pulled in off
+of disk again via Apache::StatINC.
+
+<P><DT><STRONG>-</STRONG><DD>
+<P>
+an additional time, in the parent process on each restart if
+PerlFreshRestart is On.
+
+<P><DT><STRONG>-</STRONG><DD>
+<P>
+unpredictable if you fiddle with <CODE>%INC</CODE> yourself.
+
+</DL>
+<P>
+Apache::Registry scripts which contain BEGIN blocks will be executed:
+<DL>
+<P><DT><STRONG>-</STRONG><DD>
<P>
-Apache::Registry scripts which contain BEGIN blocks will be executed: -
only once, if pulled in by the parent process via Apache::RegistryLoader -
-once per-child process if not pulled in by the parent process - an
-additional time, once per-child process if the script file has changed on
-disk - an additional time, in the parent process on each restart if pulled
-in by the parent process via Apache::RegistryLoader and PerlFreshRestart is
-On.
+once per-child process if not pulled in by the parent process.
+
+<P><DT><STRONG>-</STRONG><DD>
+<P>
+an additional time, once per-child process if the script file has changed
+on disk.
+
+<P><DT><STRONG>-</STRONG><DD>
+<P>
+an additional time, in the parent process on each restart if pulled in by
+the parent process via Apache::RegistryLoader and PerlFreshRestart is On.
+</DL>
<P>
Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
@@ -2975,23 +3185,23 @@
mod_perl does make a special case for Apache::Registry scripts.
<P>
-Normally, END blocks are executed by Perl during it's
-<CODE>perl_run()</CODE> function, which is called once each time the Perl
-program is executed, e.g. once per (mod_cgi) CGI scripts. However, mod_perl
-only calls <CODE>perl_run()</CODE> once, during server startup. Any END
-blocks encountered during main server startup, i.e. those pulled in by the
-PerlRequire or by any PerlModule are suspended and run at server shutdown,
-aka child_exit (requires apache 1.3b3+).
+Normally, END blocks are executed by Perl during its <STRONG>perl_run()</STRONG>
+function, which is called once each time the Perl program is executed, e.g.
+once per (mod_cgi) CGI scripts. However, mod_perl only calls
+<STRONG>perl_run()</STRONG> once, during server startup. Any END blocks encountered during main server
+startup, i.e. those pulled in by the PerlRequire or by any PerlModule, are
+suspended and run at server shutdown, aka child_exit (requires apache
+1.3b3+).
<P>
Any END blocks that are encountered during compilation of Apache::Registry
-scripts <STRONG>are called after the script done its
-running</STRONG> (not during the cleanup phase though) including subsequent invocations when
+scripts <STRONG>are called after the script has completed</STRONG>
+(not during the cleanup phase though) including subsequent invocations when
the script is cached in memory. All other END blocks encountered during
other Perl*Handler callbacks, e.g. PerlChildInitHandler, will be suspended
while the process is running and called during child_exit when the process
-is shutting down. Module authors may be wish to use $r->register_cleanup
-as an alternative to END blocks if this behavior is not desirable.
+is shutting down. Module authors may be wish to use $r->register_cleanup as an alternative to END blocks if this behavior is not
+desirable.
<P>
The last paragraph is very important for the <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>
@@ -3001,17 +3211,16 @@
<CENTER><H3><A NAME="Switches_w_T">Switches -w, -T</A></H3></CENTER>
<P>
Normally when you run perl from the command line or have the shell invoke
-it with `#!', you may choose to pass perl switch arguments such as -w or
--T. Most command line arguments have a equivalent special variable. For
-example, the $^W variable corresponds to the -w switch. Consult perlvar for
-more details. With mod_perl it is also possible to turn on warnings
-globally via the PerlWarn directive:
+it with `#!', you may choose to pass perl switch arguments such as <STRONG>-w</STRONG> or <STRONG>-T</STRONG>. Most command line arguments have a equivalent special variable. For
+example, the <STRONG>$^W</STRONG> variable corresponds to the <STRONG>-w</STRONG>
+switch. Consult perlvar for more details. With mod_perl it is also possible
+to turn on warnings globally via the PerlWarn directive:
<P>
<PRE> PerlWarn On
</PRE>
<P>
-You can turn it off with <CODE>local $^W = 0;</CODE> in your scripts on the local basis (or inside the block). If you write <CODE>$^W = 0;</CODE> you disable the warn mode everywhere, the same with <CODE>$^W = 1;</CODE>.
+You can turn it off with <CODE>local $^W = 0;</CODE> in your scripts on the local basis (or inside the block). If you write <CODE>$^W = 0;</CODE> you disable the warning mode everywhere, the same with <CODE>$^W = 1;</CODE>.
<P>
The switch which enables taint checks does not have a special variable, so
@@ -3022,23 +3231,20 @@
<PRE> PerlTaintCheck On
</PRE>
<P>
-Now, any and all code compiled inside httpd will be checked.
+Now, any and all code compiled inside httpd will be taint checked.
<P>
The environment variable PERL5OPT can be used to set additional perl
startup flags such as -d and -D. See perlrun.
<P>
-If you have the shebang line (#!/bin/perl -wT) in your script, <STRONG>-w</STRONG>
+If you have the shebang line (#!/bin/perl -Tw) in your script, <STRONG>-w</STRONG>
will be honored (which means that you have turned the warn mode on for the
scope of this script, <STRONG>-T</STRONG> will produce a warning if
<CODE>PerlTaintCheck</CODE> isn't <CODE>On</CODE>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="Switches_w_T">Switches -w, -T</A></H3></CENTER>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="strict_pragma">strict pragma</A></H2></CENTER>
<P>
It's absolutely mandatory to start all your scripts with:
@@ -3047,8 +3253,8 @@
<PRE> use strict; (at least for development)
</PRE>
<P>
-If you need you can always to turn off the 'strict' pragma inside the
-block, e.g:
+If needed, you can always turn off the 'strict' pragma inside the block,
+e.g:
<P>
<PRE> {
@@ -3057,10 +3263,9 @@
}
</PRE>
<P>
-It's more important to have use strict enabled under mod_perl Perl than
-anywhere else, while it's not required, it strongly recommended, it will
-save you more time in the long run. And, of course, clean scripts will
-still run under mod_cgi (plain CGI)!
+It's more important to have <STRONG>use strict;</STRONG> enabled under mod_perl than anywhere else. While it's not required, it is
+strongly recommended, it will save you more time in the long run. And, of
+course, clean scripts will still run under mod_cgi (plain CGI)!
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -3068,46 +3273,49 @@
<P>
Have a <CODE>$^W=1</CODE> in the script or PerlWarn ON at the server config file. Turning the warning
on will save you a lot of troubles with debugging your code. Note that
-first magic line <CODE>#!/perl -swithces</CODE>
-#is ignored by mod_perl so do the switches you used to write there.
+first magic line <CODE>#!/perl -switches</CODE>
+is ignored by mod_perl, so too are the switches you used to write there.
<P>
-If you need you can always turn off the warning with <CODE>$^W = 0</CODE> in your code, if you have some section you don't want the perl compiler to
+If you need you can always turn off the warning with <CODE>$^W = 0</CODE> in your code if you have some section you don't want the perl compiler to
warn in.
<P>
-In a production code it can be a good idea to have the Warnings Off.
-Otherwise if your code isn't very clean and spits a few lines of warns here
-and there, you will end up with a huge error_log file in a short time on
-the loaded server.
+In production code, it can be a good idea to turn warnings off. Otherwise
+if your code isn't very clean and spits a few lines of warnings here and
+there, you will end up with a huge error_log file in a short time on the
+loaded server. Also, enabling runtime warning checking has a small
+performance impact -- in any script, not just under mod_perl -- so your
+approach should be to enable warnings during development, and then disable
+them when your code is production-ready.
<P>
-<CODE>use diagnostics;</CODE> can put more light on the errors and warns you see, But you better don't
-use <CODE>use diagnostics;</CODE>
-in the production, since you end up in a huge overhead of the diagnostics
-pragma. (run the script with -dDprof to check the overhead. See
+<CODE>use diagnostics;</CODE> can shed more light on the errors and warnings you see, but again, it's
+better to not use <CODE>use diagnostics;</CODE>
+in production, since otherwise you incur the overhead of the diagnostics
+pragma. (You can run your script with -dDprof to check the overhead. See
Devel::Dprof for more info)
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="diagnostics_pragma">diagnostics pragma</A></H2></CENTER>
<P>
-Perl compiler pragma to force verbose warning diagnostics. Put at the start
-of your scripts:
+This is a Perl compiler pragma which forces verbose warning diagnostics.
+Put at the start of your scripts:
<P>
<PRE> use diagnostics;
</PRE>
<P>
-This pragma turns on the -w mode, but gives you a much better diagnostics
-of the errors and warnings. Generally it explains the reason for
-warnings/errors you get, shows you an example of code, where the same kind
-of warning is being triggered and tells you the remedy.
+This pragma turns on the -w mode, but gives you much better diagnostics of
+the errors and warnings encountered. Generally it explains the reason for
+warnings/errors you get, shows you an example of code where the same kind
+of warning is being triggered, and tells you the remedy.
<P>
-It's a bad idea to keep it in your production code! Since it'll spit
-zillions of diagnostics lines into your error_log file. And it'll add
-significant overhead to the cgi's runtime. (I discovered this by using
+Again, it's a bad idea to keep this in your production code, as it will
+spit zillions of diagnostics lines into your error_log file. Also, it will
+add significant overhead to the CGI's runtime. (I discovered this by using
Devel::DProf!)
<P>
@@ -3115,12 +3323,9 @@
<CENTER><H2><A NAME="Global_Variables">Global Variables</A></H2></CENTER>
<P>
It's always a good idea to stay away from global variables when possible.
-Some variables must be global so Perl can see them, such as a module's
-<CODE>@ISA</CODE> or <CODE>$VERSION</CODE> variables. In common practice, a
-combination of use strict and use vars keeps modules clean and reduces a
-bit of noise. However, use vars also creates aliases as the Exporter does,
-which eat up more space. When possible, try to use fully qualified names
-instead of use vars. Example:
+Some variables must be global so Perl can see them, such as a module's <STRONG>@ISA</STRONG> or
+<STRONG>$VERSION</STRONG> variables. In common practice, a combination of <STRONG>use strict</STRONG> and <STRONG>use vars</STRONG> keeps modules clean and reduces a bit of noise. However, <STRONG>use vars</STRONG> also creates aliases as the Exporter does, which eat up more space. When
+possible, try to use fully qualified names instead of use vars. Example:
<P>
<PRE> package MyPackage;
@@ -3129,8 +3334,8 @@
$MyPackage::VERSION = "1.00";
</PRE>
<P>
-<PRE> vs.
-</PRE>
+vs.
+
<P>
<PRE> package MyPackage;
use strict;
@@ -3139,27 +3344,28 @@
$VERSION = "1.00";
</PRE>
<P>
+Also see <A HREF="././perl.html#Using_global_variables_and_shari">Using global variables and sharing them</A>
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Code_has_been_changed_but_seems">Code has been changed, but seems that script uses the old code</A></H2></CENTER>
+<CENTER><H2><A NAME="Code_has_been_changed_but_it_se">Code has been changed, but it seems the script is running the old code</A></H2></CENTER>
<P>
-Files pulled in via use or require statements are not automatically
-reloaded when changed on disk. See <A HREF="././obvious.html#Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A> for more info.
+Files pulled in via <STRONG>use</STRONG> or <STRONG>require</STRONG> statements are not automatically reloaded when changed on disk. See <A HREF="././obvious.html#Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A> for more info.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Memory_leakages">Memory leakages</A></H2></CENTER>
+<CENTER><H2><A NAME="Memory_leakage">Memory leakage</A></H2></CENTER>
<P>
Scripts under mod_perl can very easily leak memory! Global variables stay
-around indefinitely, lexical variables (declared with <Cmy()> are
-destroyed when they go out of scope, provided there are no references to
-them from outside of that scope.
+around indefinitely, lexical variables (declared with <CODE>my()</CODE> are destroyed when they go out of scope, provided there are no references
+to them from outside of that scope.
<P>
-Perl doesn't return back the memory it acquired from the kernel. It does
-reuse it so!
+Perl doesn't return the memory it acquired from the kernel. It does reuse
+it though!
<P>
-<STRONG>First example</STRONG> is file reading:
+<STRONG>First example</STRONG> demonstrates reading a file:
<P>
<PRE> open IN, $file or die $!;
@@ -3168,54 +3374,59 @@
close IN;
</PRE>
<P>
-If you file is of a 5Mb - The child who served that script will grow
-exactly by that size. Now if you have 20 children and all of them will
-serve this cgi, all of them will consume additional 20*5M = 100M of RAM! If
-that's the case try to use other approaches of processing the file, if
-possible of course. Try to process line at a time and print it back to the
-file (if you need to modify the file itself, use temporary file for that,
-when finished overwrite the src file, make sure to provide locking
-mechanism!).
+If your file is 5Mb, the child who served that script will grow exactly by
+that size. Now if you have 20 children and all of them will serve this CGI,
+all of them will consume additional 20*5M = 100M of RAM! If that's the
+case, try to use other approaches of processing the file, if possible of
+course. Try to process a line at a time and print it back to the file. (If
+you need to modify the file itself, use a temporary file. When finished,
+overwrite the source file, making sure to provide a locking mechanism!)
<P>
-<STRONG>Second example</STRONG> is copying variables between functions (passing variables by value). Let's
-use the example above. Assuming we have no choice and the whole file had to
-be read before any data processing. Now you have a very nice sub
+<STRONG>Second example</STRONG> demonstrates copying variables between functions (passing variables by
+value). Let's use the example above, assuming we have no choice but to read
+the whole file before any data processing. Now you have a very nice sub
<CODE>process()</CODE> that processes the data and returns it back. What
happens if you pass the <CODE>$content</CODE> by value? You have just
-copied another 5M and the child has grew up up by another 5M in size (watch
-your swap space!) now multiply it again by factor of 10 you have 200M of
-wasted RAM, which will be apparently reused but it's a waste! Whenever you
-think the variable can grow bigger than few Kb pass it by reference! Once I
-wrote the script that passed a content of the little DB to the function and
-it was OK, but then the DB become huge - I had to make a decision, whether
-to buy more memory or to rewrite the code. So it's better to plan ahead and
-pass the variables by reference. There are few approaches for that:
+copied another 5M and the child has grown by another 5M in size (watch your
+swap space!) now multiply it again by factor of 20 you have 200M of wasted
+RAM, which will be apparently reused but it's a waste! Whenever you think
+the variable can grow bigger than few Kb, pass it by reference!
+
+<P>
+Once I wrote the script that passed a content of the little DB to the
+function and it was OK, but then the DB become huge - I had to make a
+decision, whether to buy more memory or to rewrite the code. So it's better
+to plan ahead and pass the variables by reference. There are few approaches
+for that:
<P>
<PRE> sub process{
my $content_r = shift;
- ... some processing on $$content here ($$var_r - dereference the scalar)
- [nothing returned - the variable $content outside is already changed
+ ... some processing on $$content here
+ ($$var_r - dereference the scalar)
+ [nothing returned - the variable $content
+ outside is already changed]
}
process(\$content);
-</PRE>
-<P>
-<PRE> @{$var_lr} - dereference an array
+
+ @{$var_lr} - dereference an array
%{$var_hr} = dereference a hash
</PRE>
<P>
For more see <CODE>perldoc perlref</CODE>
<P>
-Other approach would be to use directly the <CODE>@_</CODE> variable. Using
-directly the <CODE>@_</CODE> array serves the job of passing by reference!
+Another approach would be to directly use the <CODE>@_</CODE> variable.
+Using directly the <CODE>@_</CODE> array serves the job of passing by
+reference!
<P>
<PRE> sub process{
$_[0] =~ s/A/a/gs;
- ... some processing on $_[0] here
- [nothing returned - the variable $content outside is already changed
+ ... some processing on $_[0] here
+ [nothing returned - the variable $content
+ outside is already changed]
}
process($content);
</PRE>
@@ -3223,18 +3434,18 @@
From <CODE>perldoc perlsub</CODE>: The array <CODE>@_</CODE> is a local array, but its elements are aliases
for the actual scalar parameters. In particular, if an element $_[0] is
updated, the corresponding argument is updated (or an error occurs if it is
-not possible to update)....
+not possible to update)...
<P>
-<STRONG>Third example</STRONG> is work with DataBases. If you do some DB processing, many times you have
-lots of records that you read into you program, and then print them to the
-browser after they were formatted. (I even don't mention the horrible case
-where programmers read in the whole DB and then let the perl to process
-it!!! Use relational DB and let the SQL do the job, so you get only the
-records you need!!!).
+<STRONG>Third example</STRONG> demonstrates work with DataBases. If you do some DB processing, many times
+you encounter the need to read lots of records into your program, and then
+print them to the browser after they are formatted. (I don't even mention
+the horrible case where programmers read in the whole DB and then use perl
+to process it!!! Use a relational DB and let the SQL do the job, so you get
+only the records you need!!!).
<P>
-We will use DBI for that (assume we are already connected to the DB) (read
+We will use DBI for this (assume we are already connected to the DB) (read
perldoc DBI for complete info):
<P>
@@ -3247,14 +3458,15 @@
<P>
In the example above the httpd_process will grow up by the size of the
variables that have been allocated for the records that matched the query.
-(Again remember to multiply it by the number of the children server runs!).
+(Again remember to multiply it by the number of the children your server
+runs!).
<P>
-What you want to do is to not accumulate the records but print them as they
-are fetched from the DB. More over we use a bind_col and
-$sth->fetchrow_arrayref (aliased to $sth->fetch) methods, to get the
-the fastest way to fetch data. The example below prints the TABLE with
-matched data, the only memory that is being used is a @cols.
+A better approach is to not accumulate the records, but rather print them
+as they are fetched from the DB. Moreover, we use the <STRONG>bind_col</STRONG>
+and <STRONG>$sth->fetchrow_arrayref</STRONG> (aliased to <STRONG>$sth->fetch</STRONG>) methods, to fetch the data in the fastest possible way. The example below
+prints the TABLE with matched data, the only memory that is being used is a
+@cols.
<P>
<PRE> my @select_fields = qw(a b c);
@@ -3267,21 +3479,20 @@
$sth->bind_columns(undef,\(@cols));
print "<TABLE>";
while($sth->fetch) {
- print "<TR>";
- print map { "<TD>$_</TD>" } @cols;
- print "</TR>";
+ print "<TR>",
+ map("<TD>$_</TD>", @cols),
+ "</TR>";
}
print "</TABLE>";
</PRE>
<P>
-Note: the above method doesn't allow you to know how many records has been
+Note: the above method doesn't allow you to know how many records have been
matched. The workaround is to run an identical query before the code above
-where you use 'SELECT <CODE>count(*)</CODE> ...' instead of 'SELECT * ...',
-so you get the number of matched records.
+where you use <STRONG>SELECT count(*) ...</STRONG> instead of <STRONG>'SELECT *
+...</STRONG> to get the number of matched records.
<P>
-For those who think that $sth->rows will do the job, here is the quote
-from the DBI manpage:
+For those who think that <STRONG>$sth->rows</STRONG> will do the job, here is the quote from the DBI manpage:
<BLOCKQUOTE>
@@ -3304,9 +3515,9 @@
</BLOCKQUOTE>
<P>
-Just as a bonus, I wanted to write a single sub that process any query but
-very flexible, since it accepts: conditions, callback closure sub, select
-fields and restrictions.
+As a bonus, I wanted to write a single sub that flexibly processes any
+query, accepting: conditions, callback closure sub, select fields and
+restrictions.
<P>
<PRE> # $o->dump(\%conditions,\&callback_closure,\@select_fields,@restrictions)
@@ -3316,36 +3527,29 @@
my $rsub = shift;
my @select_fields = @{+shift}; # dereference list
my @restrict = shift || '';
-</PRE>
-<P>
-<PRE> # create a list of cols values
+
+ # create a list of cols values
my @cols = ();
@cols[0..$#select_fields] = ();
-</PRE>
-<P>
-<PRE> my $do_sql = '';
+
+ my $do_sql = '';
my @where = ();
-</PRE>
-<P>
-<PRE> # make a @where list
+
+ # make a @where list
map { push @where, "$_=\'$param{$_}\'" if $param{$_};} keys %param;
-</PRE>
-<P>
-<PRE> # prepare the sql statement
+
+ # prepare the sql statement
$do_sql = "SELECT ";
$do_sql .= join(" ", @restrict) if @restrict;# append the restriction list
$do_sql .= " " .join(",", @select_fields) ; # append the select list
$do_sql .= " FROM $DBConfig{TABLE} "; # from table
-</PRE>
-<P>
-<PRE> # we will not add the WHERE clause if @where is empty
+
+ # we will not add the WHERE clause if @where is empty
$do_sql .= " WHERE " . join " AND ", @where if @where;
-</PRE>
-<P>
-<PRE> print "SQL: $do_sql \n" if $debug;
-</PRE>
-<P>
-<PRE> $dbh->{RaiseError} = 1; # do this, or check every call for errors
+
+ print "SQL: $do_sql \n" if $debug;
+
+ $dbh->{RaiseError} = 1; # do this, or check every call for errors
$sth = $dbh->prepare($do_sql);
$sth->execute;
# Bind perl variables to columns.
@@ -3353,36 +3557,38 @@
while($sth->fetch) {
&$rsub(@cols);
}
- # print the tail or "no records found" message according to the previous calls
+ # print the tail or "no records found" message
+ # according to the previous calls
&$rsub();
-</PRE>
-<P>
-<PRE> } # end of sub dump
+
+ } # end of sub dump
</PRE>
<P>
Now a callback closure sub can do lots of things. We need a closure to know
-what stage are we in: header, body or tail. For example a callback closure
-for formatting the rows we want to print:
+what stage are we in: header, body or tail. For example, we want a callback
+closure for formatting the rows to print:
<P>
<PRE> my $rsub = eval {
- # make a copy of @fields list, since it might go out of scope when this closure will be called
+ # make a copy of @fields list, since it might go
+ # out of scope when this closure will be called
my @fields = @fields;
my @query_fields = qw(user dir tool act); # no date field!!!
my $header = 0;
my $tail = 0;
my $counter = 0;
my %cols = (); # columns name=> value hash
-</PRE>
-<P>
-<PRE> # Closure with the following behavior:
- # 1. Header's code will be executed on the first call only and if @_ was set
+
+ # Closure with the following behavior:
+ # 1. Header's code will be executed on the first call only and
+ # if @_ was set
# 2. Row's printing code will be executed on every call with @_ set
- # 3. Tail's code will be executed only if Header's code was printed and @_ isn't set
- # 4. "No record found" code will be executed if Header's code wasn't executed
-</PRE>
-<P>
-<PRE> sub {
+ # 3. Tail's code will be executed only if Header's code was
+ # printed and @_ isn't set
+ # 4. "No record found" code will be executed if Header's code
+ # wasn't executed
+
+ sub {
# Header
if (@_ and !$header){
print "<TABLE>\n";
@@ -3408,47 +3614,88 @@
unless ($header){
print $q->p($q->center($q->b("No record was found!\n")));
}
-</PRE>
-<P>
-<PRE> } # end of sub {}
+
+ } # end of sub {}
}; # end of my $rsub = eval {
</PRE>
<P>
-You might want to check also <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>
- and <A HREF="././performance.html#Limiting_the_resources_used_by_h">Limiting the resources used by httpd children</A>.
+You might also want to check <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>
+and <A HREF="././performance.html#Limiting_the_resources_used_by_h">Limiting the resources used by httpd children</A>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Sometimes_it_works_Sometimes_Not">Sometimes it works Sometimes Not (Very important!)</A></H2></CENTER>
+<CENTER><H1><A NAME="Filehandlers_and_locks_leakages">Filehandlers and locks leakages</A></H1></CENTER>
<P>
-When you start running the scripts under mod_perl you might find yourself
-in situation that scripts seems to work, but sometimes it screws up. And
-the more it runs without restart the more it screws up. Many times you can
-resolve this problem very easily. You have to test your script under with
-Server running as a
-<A HREF="././control.html#Single_Mode_Running">single process</A>.
+At the beginning there was:
<P>
-Generally the problem you have is using global variables. Since global
-variables don't change from one script invocation to another unless you
-change it, you can find your scripts do ``fancy'' things.
+<PRE> open IN, "in.txt" or die "Cannot open in.txt for reading : $!\n";
+</PRE>
+<P>
+But it was not perfect for mod_perl, since you have had to make sure you
+do:
<P>
-The first example is amazing. Web Services. Imagine that you enter some
-site you have your account on (Free Email Account?). Now you want to see
-what other users read.
+<PRE> close IN;
+</PRE>
+<P>
+somewhere before the end of the script, since if you do not, you will get a
+file descriptor leakage and unlock problem. Even if you do have it, but for
+some reason the interpreter did not make it to it, because of various
+reasons, such as user aborted script (<A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>) the leakage is still there.
<P>
-You type in your name and passwd, and you are expecting to enter to your
-account, but instead to enter the account of someone else. This is cool
-isn't it? Is it a bug or feature. (For some of us it's a feature, while for
-others it's a bug :( You say, why in the world this happens? The answer is
+What do we do? We use <CODE>IO::File</CODE> (and other <CODE>IO::*</CODE>), which allows us to assign the filehandler to variable, which can be <CODE>my()</CODE>
+scoped. And when this variable goes out of scope the file or other
+filesystem entity will be preperly closed and unlocked (if was locked).
+
+<P>
+<PRE> {
+ my $fh = new IO::File("filename") or die $!;
+ # read from $fh
+ } # ...$fh is closed automatically at end of block, without leaks.
+</PRE>
+<P>
+But even faster and lighter technique is to use <CODE>Symbol.pm</CODE>:
+
+<P>
+<PRE> {
+ my $fh = Symbol::gensym();
+ open $fh, "filename" or die $!
+ }
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Sometimes_it_Works_Sometimes_Not">Sometimes it Works Sometimes Not (Very important!)</A></H2></CENTER>
+<P>
+When you start running your scripts under mod_perl, you might find yourself
+in situation where a script seems to work, but sometimes it screws up. And
+the more it runs without a restart, the more it screws up. Many times you
+can resolve this problem very easily. You have to test your script under
+with Server running as a
+<A HREF="././control.html#Single_Mode_Running">single process</A>.
+
+<P>
+Generally the problem you have is using global variables. Since global
+variables don't change from one script invocation to another unless you
+change it, you can find your scripts do ``fancy'' things.
+
+<P>
+The first example is amazing -- Web Services. Imagine that you enter some
+site you have your account on (Free Email Account?). Now you want to see
+what other users read.
+
+<P>
+You type in your name and passwd, and you expect to enter to your account,
+but instead you enter the account of someone else. This is cool isn't it?
+Is it a bug or feature. (For some of us it's a feature, while for others
+it's a bug.) You say, why in the world does this happen? The answer is
simple: Global Variables. You have entered the account of someone who
-happened to be served by the same server child as you, because of the
-sloppiness programming, the global variable was not reset at the beginning
-of the program and voila you can easily peek into other people emails! You
-would ask it can't happen, since you have entered the login and passwd. I
-tell you, it happens! See for yourself:
+happened to be served by the same server child as you. Because of sloppy
+programming, a global variable was not reset at the beginning of the
+program and voila, you can easily peek into other people's emails! You
+would think that it can't happen, since you have entered the login and
+passwd. I tell you, it happens! See for yourself:
<P>
<PRE> use vars ($authenticated);
@@ -3460,27 +3707,24 @@
die "Wrong passwd" unless $authenticated == 1;
# user is OK, fetch user's data
show_user($username);
-</PRE>
-<P>
-<PRE> sub authenticate{
+
+ sub authenticate{
my ($username,$passwd) = @_;
# some checking
$authenticated = 1 if (SOMETHING);
}
</PRE>
<P>
-Do you see the catch? I can type in any valid username and any dummy passwd
-and enter that's user account, with the code above if someone has
+Do you see the catch? With the code above, I can type in any valid username
+and any dummy passwd and enter that user's account, if someone has
successfully entered his account before me using the same child process!
-Since <CODE>$authenticated</CODE> is global - if it becomes 1 once it'll be
-1 for the whole child's life!!! The solution is trivial - reset the
-<CODE>$authenticated</CODE> to 0 at the beginning of the program. (Or many
-other different solutions). Of course the example is too trivial - but
-believe me it happens!
+Since <STRONG>$authenticated</STRONG> is global - if it becomes 1 once it'll be 1 for the remainder of the
+child's life!!! The solution is trivial -- reset <STRONG>$authenticated</STRONG> to 0 at the beginning of the program. (Or many other different solutions).
+Of course this example is trivial -- but believe me it happens!
<P>
-Just another little one liner that can make your day spoiled, assuming you
-forgot to reset the $allowed. It's perfectly OK in plain mod_cgi:
+Just another little one liner that can spoil your day, assuming you forgot
+to reset the <STRONG>$allowed</STRONG> variable. It works perfectly OK in plain mod_cgi:
<P>
<PRE> $allowed = 1 if $username eq 'admin';
@@ -3490,17 +3734,18 @@
assuming you have used the same child prior to some user request).
<P>
-Another good example is usage of /o in regexp. After you restart the server
-most likely you will not detect the problem, if on every request you will
-use a different pattern that will be used in regexp and it'll happen that
-each time a different child will serve the new request. Only arriving to
-the child who has already cached the regexp will reveal the problem, but
-generally you miss that and when you press reload - You see that it works
-(new fresh child) and then it doesn't (child that already cached the regexp
-and wouldn't recompile because of /o).
+Another good example is usage of the <STRONG>/o</STRONG> regular expression qualifier, which compiles a regular expression once, on
+its first execution. This problem can be difficult to detect, as after
+restarting the server each request you make will be served by a different
+child process, and thus the regex pattern for that child will be compiled
+fresh. Only when you make a request that happens to be served by a child
+which has already cached the regexp will you see the problem. Generally you
+miss that and when you press reload, you see that it works (with a new,
+fresh child) and then it doesn't (with a child that already cached the
+regexp and wouldn't recompile because of <STRONG>/o</STRONG>.)
<P>
-So to make sure you don't miss these bugs always test your CGI in
+To make sure you don't miss these bugs always test your CGI in
<A HREF="././control.html#Single_Mode_Running">single process</A>. To solve this particular <STRONG>/o</STRONG> problem refer to <A HREF="././obvious.html#Compiled_Regular_Expressions">Compiled Regular Expressions</A>.
<P>
@@ -3510,16 +3755,15 @@
You still can win from using mod_perl.
<P>
-One approach it to replace the Apache::Registry handler with
-Apache::PerlRun and defined a new location (the script can reside in the
+One approach is to replace the Apache::Registry handler with
+Apache::PerlRun and define a new location (the script can reside in the
same directory on the disk.
<P>
<PRE> # srm.conf
Alias /cgi-perl/ /home/httpd/cgi/
-</PRE>
-<P>
-<PRE> # httpd.conf
+
+ # httpd.conf
<Location /cgi-perl>
#AllowOverride None
SetHandler perl-script
@@ -3551,24 +3795,23 @@
write scripts that run under CGI or mod_perl without any change. Unlike
Apache::Registry, the Apache::PerlRun handler does not cache the script
inside of a subroutine. Scripts will be ``compiled'' on each request. After
-the script has run, it's namespace is flushed of all variables and
+the script has run, its namespace is flushed of all variables and
subroutines. Still, you don't have the overhead of loading the perl and
compilation time of the standard modules (If your script is very light, but
uses lots of standard modules - you will see no difference between
Apache::PerlRun and Apache::Registry !).
<P>
-Be aware though, that if you use some packages that use internals variables
-that has circular references, they will be not flushed!!!
+Be aware though, that if you use packages that use internal variables that
+have circular references, they will be not flushed!!!
<P>
Apache::PerlRun only flushes your script's namespace, which does not
-include any other required package's namespace. If there's a reference to
-<CODE>my()</CODE> scoped variable that's keeping it from being DESTROYed
-after leaving the eval scope (of Apache::PerlRun), that cleanup might not
-be taken care of until the server is shutdown and
-<CODE>perl_destruct()</CODE> is run, which always happens after running
-command line scripts. Consider this example:
+include any other required packages' namespaces. If there's a reference to
+a <STRONG>my()</STRONG> scoped variable that's keeping it from being DESTROYed after leaving the
+eval scope (of Apache::PerlRun), that cleanup might not be taken care of
+until the server is shutdown and <CODE>perl_destruct()</CODE> is run, which
+always happens after running command line scripts. Consider this example:
<P>
<PRE> package Foo;
@@ -3576,16 +3819,14 @@
sub DESTROY {
warn "Foo->DESTROY\n";
}
-</PRE>
-<P>
-<PRE> eval <<'EOF';
+
+ eval <<'EOF';
package my_script;
my $self = Foo->new;
#$self->{circle} = $self;
EOF
-</PRE>
-<P>
-<PRE> print $@ if $@;
+
+ print $@ if $@;
print "Done with script\n";
</PRE>
<P>
@@ -3625,7 +3866,7 @@
to see the error message, but I want it to be emailed to me if it's severe
enough. The handler traps various errors and performs accordingly to the
defined logic. My handler was written for the modperl environment, but
-works correctly when is being called from the shell. A stipped version of
+works correctly when is being called from the shell. A stripped version of
the code is shown here:
<P>
@@ -3735,9 +3976,10 @@
</PRE>
<P>
-You have noticed that I trap the CGI.pm's <CODE>die()</CODE> calls here, I
-don't see any reason why my users should see an ugly error messages, but
-that's the way CGI.pm written. The workaround was to trap them myself.
+You may have noticed that I trap the CGI.pm's <CODE>die()</CODE> calls
+here, I don't see any reason why my users should see an ugly error
+messages, but that's the way CGI.pm written. The workaround is to trap them
+myself.
<P>
Please note that as of ver 2.49, CGI.pm provides a <CODE>cgi_error()</CODE>
@@ -3757,8 +3999,103 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
+ Written by <A HREF="help.html#author">Stas Bekman</A>.
+ <BR>Last Modified at 04/03/99
+ </FONT>
+ </B>
+ </TD>
+
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
+
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
+</TR>
+</TABLE></CENTER>
+
+</BODY>
+</HTML>
+
+
+<HR SIZE=6>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+ <TITLE>mod_perl guide: Frequent mod_perl problems</TITLE>
+ <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
+ <META NAME="Author" CONTENT="Bekman Stas">
+ <META NAME="Description" CONTENT="mod_perl,perl,apache">
+ <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
+<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+Frequent mod_perl problems</H1>
+<HR WIDTH="100%">
+ <!-- INDEX BEGIN -->
+<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+<UL>
+
+ <LI><A HREF="#Coverage">Coverage</A>
+ <LI><A HREF="#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>
+ <LI><A HREF="#Segfaults_caused_by_PerlFreshRes">Segfaults caused by PerlFreshRestart</A>
+</UL>
+<!-- INDEX END -->
+
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<P>
+<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
+<P>
+This new document was born because some problems come up so often on the
+mailing list that should be stressed in the guide as one of the most
+important things to read/beware of. So I have tried to enlist them in this
+document. If you think some important problem that is being reported
+frequently on the list and covered in the guide but not included below,
+please tell.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A></H1></CENTER>
+<P>
+<A HREF="././obvious.html#my_scoped_variable_in_nested_s">More info</A>
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Segfaults_caused_by_PerlFreshRes">Segfaults caused by PerlFreshRestart</A></H1></CENTER>
+<P>
+<A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>
+
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<P><A HREF="index.html">[Back to the main page]</A></P>
+
+<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
+</TR>
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/16/99
+ <BR>Last Modified at 04/02/99
</FONT>
</B>
</TD>
@@ -3785,25 +4122,40 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: What is obvious for others but not for you</TITLE>
+ <TITLE>mod_perl guide: Things obvious to others, but not to you</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-What is obvious for others but not for you</H1>
+Things obvious to others, but not to you</H1>
<HR WIDTH="100%">
<!-- INDEX BEGIN -->
<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Coverage">Coverage</A>
- <LI><A HREF="#my_scoped_variable_in_the_nest">my() scoped variable in the nested subroutine</A>
+ <LI><A HREF="#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>
+ <UL>
+
+ <LI><A HREF="#The_poison">The poison</A>
+ <LI><A HREF="#The_diagnosis">The diagnosis</A>
+ <LI><A HREF="#The_remedy">The remedy</A>
+ </UL>
+
<LI><A HREF="#Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A>
<UL>
@@ -3816,6 +4168,7 @@
<LI><A HREF="#Debugging_your_code_in_Single_Se">Debugging your code in Single Server Mode</A>
<LI><A HREF="#_M_and_other_time_file_tests_u">-M and other time() file tests under mod_perl</A>
<LI><A HREF="#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>
+ <LI><A HREF="#Handling_the_server_timeout_case">Handling the server timeout cases</A>
<LI><A HREF="#Where_do_the_warnings_errors_go_">Where do the warnings/errors go?</A>
</UL>
<!-- INDEX END -->
@@ -3824,111 +4177,135 @@
<P>
<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
<P>
-This document describes ``special'' traps of running your plain cgis under
-Apache::Registry and Apache::PerlRun.
+This document describes ``special'' traps you may encounter when running
+your plain CGIs under Apache::Registry and Apache::PerlRun.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="my_scoped_variable_in_the_nest">my() scoped variable in the nested subroutine</A></H1></CENTER>
+<CENTER><H1><A NAME="my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A></H1></CENTER>
<P>
-When you write a code like:
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="The_poison">The poison</A></H2></CENTER>
+<P>
+In a non modperl script (standalone or CGI), there is no problem writing
+code like this:
<P>
-<PRE> #!perl -w
- my $x;
- sub y {
- $x
+<PRE> use CGI qw/param/;
+ my $x = param('x');
+ sub printit {
+ print "$x\n";
}
</PRE>
<P>
-there is no problem. But when you write:
+However, the script is run under Apache::Registry, it will in fact be
+repackaged into something like this:
<P>
-<PRE> #!perl -w
- sub x {
- my $x;
- sub y {
- $x
- }
+<PRE> package $mangled_package_name;
+ sub handler {
+ #line1 $original_filename
+ use CGI qw/param/;
+ my $x = param('x');
+ sub printit {
+ print "$x\n";
}
+ }
</PRE>
<P>
-it produces this warning:
+Now printit is an inner named subroutine. Because it is referencing a
+lexical variable from an enclosing scope, a closure is created.
-<P>
-<PRE> Value of $x will not stay shared at - line 5.
-</PRE>
<P>
-The tone of this message is definite because the code *will* fail if
-<CODE>&x</CODE> is called more than once. NOTE: Subroutines defined
-inside BEGIN{} and END{} cannot trigger this message, since each BEGIN{}
-and END{} is known to be called exactly once. (To understand why, read
-about the closures at perlref or perlfaq 13.12)
+The first time the script is run, the correct value of <CODE>$x</CODE> will
+be printed. However on subsequent runs, printit will retain the initial
+value of <CODE>$x</CODE> -- not what you want.
<P>
-Also, this slightly different code:
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="The_diagnosis">The diagnosis</A></H2></CENTER>
+<P>
+Always use -w (or/and PerlWarn ON)! Perl will then emit a warning like:
<P>
-<PRE> #!perl -w
- sub x {
- my $x;
- sub y {
- sub { $x }
- }
- }
+<PRE> Value of $x will not stay shared at - line 5.
</PRE>
<P>
-produces this warning:
+NOTE: Subroutines defined inside <STRONG>BEGIN{}</STRONG> and <STRONG>END{}</STRONG> cannot trigger this message, since each <STRONG>BEGIN{}</STRONG> and <STRONG>END{}</STRONG> is defined to be called exactly once. (To understand why, read about the
+closures at perlref or perlfaq 13.12)
<P>
-<PRE> Value of $x may be unavailable at - line 5.
+PERLDIAG manpage says:
+
+<P>
+<PRE> An inner (nested) named subroutine is referencing a lexical variable
+ defined in an outer subroutine.
</PRE>
<P>
-This message is less definite because the code can work correctly, if
-<CODE>&y</CODE> is called only from inside &x.
+When the inner subroutine is called, it will probably see the value of the
+outer subroutine's variable as it was before and during the *first* call to
+the outer subroutine; in this case, after the first call to the outer
+subroutine is complete, the inner and outer subroutines will no longer
+share a common value for the variable. In other words, the variable will no
+longer be shared.
<P>
-(this was partially extracted from perl5-porters post)
+Check your code by running Apache in single-child mode (httpd -X). Since
+the value of a my variable retain its initial value <CODE>per
+child process</CODE>, the closure problem can be difficult to track down in multi-user mode. It
+will appear to work fine until you have cycled through all the httpd
+children.
<P>
-Now hold on, you ask what it has to do with your cgi script?
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="The_remedy">The remedy</A></H2></CENTER>
<P>
-That's exactly the point that is not obvious. Apache::Registry wraps your
-code into a sub! You heard it right. So all your code's subs are nested.
-And while you don't see it, your code actually is the same as the simple
-snippet above. And all the behavior described above applies to your code!
+If a variable needs file scope, use a global variable:
+<P>
+<PRE> use vars qw/$x/;
+ use CGI qw/param/;
+ $x = param('x');
+ sub printit {
+ print "$x\n";
+ }
+</PRE>
<P>
-A solution?
+You can safely use a <CODE>my()</CODE> scoped variable if its value is constant:
<P>
-<PRE> use vars qw($x $a); at the top of your code
+<PRE> use vars qw/$x/;
+ use CGI qw/param/;
+ $x = param('x');
+ my $y = 5;
+ sub printit {
+ print "$x, $y\n";
+ }
</PRE>
<P>
Also see the clarification of <CODE>my()</CODE> vs. <CODE>use vars</CODE> - Ken Williams writes:
<P>
-<PRE> Yes, there's quite a bit of difference! With use vars(), you're
- making an entry in the symbol table, and you're telling the compiler
- that you're going to be referencing that entry without an explicit
- package name.
+<PRE> Yes, there is quite a bit of difference! With use vars(), you are
+ making an entry in the symbol table, and you are telling the
+ compiler that you are going to be referencing that entry without an
+ explicit package name.
</PRE>
<P>
-<PRE> With my(), NO ENTRY IS PUT IN THE SYMBOL TABLE. The compiler figures
- out _at_ _compile_time_ which my() variables (i.e. lexical variables)
- are the same as each other, and once you hit execute time you can't go
- looking those variables up in the symbol table.
+<PRE> With my(), NO ENTRY IS PUT IN THE SYMBOL TABLE. The compiler
+ figures out _at_ _compile_time_ which my() variables (i.e. lexical
+ variables) are the same as each other, and once you hit execute time
+ you can not go looking those variables up in the symbol table.
</PRE>
<P>
And <CODE>my()</CODE> vs. <CODE>local()</CODE> - Randal Schwartz writes:
<P>
-<PRE> local() creates a temporal-limited package-based scalar, array, hash,
- or glob -- when the scope of definition is exited at runtime, the
- previous value (if any) is restored. References to such a variable
- are *also* global... only the value changes. (Aside: that's what
- causes variable suicide. :)
+<PRE> local() creates a temporal-limited package-based scalar, array,
+ hash, or glob -- when the scope of definition is exited at runtime,
+ the previous value (if any) is restored. References to such a
+ variable are *also* global... only the value changes. (Aside: that
+ is what causes variable suicide. :)
</PRE>
<P>
<PRE> my() creates a lexically-limited non-package-based scalar, array, or
@@ -3940,24 +4317,28 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A></H1></CENTER>
<P>
-When you develop your plain cgi scripts you just change the code, and rerun
-the cgi in your browser. Since the script wasn't staying in the memory, the
-next time you call it - server recompile it from scratch so all the changes
-you apply are immediately taking the expected effect.
-
-<P>
-The situation is different with Apache::Registry. Since the whole idea was
-to get the maximum performance from the server. By default server wouldn't
-spend the time to go and check whether the code has been changed. It
-assumes that it wasn't, thus saving a few millisecs to stat the file (And
-if you have many of them it takes more time). The only check that is being
-done is whether your main script has been changed. So if you have only one
-script that doesn't require or use other Perl Modules (packages) there is
-nothing new about it. The files you <CODE>use()</CODE> or
-<CODE>require()</CODE> aren't being checked at all. So what are the
-workarounds?
+When you develop plain CGI scripts, you can just change the code, and rerun
+the CGI from your browser. Since the script isn't cached in memory, the
+next time you call it the server starts up a new perl process, which
+recompiles it from scratch. The effects of any modifications you've applied
+are immediately present.
+
+<P>
+The situation is different with Apache::Registry, since the whole idea is
+to get maximum performance from the server. By default, the server won't
+spend the time to check whether any included library modules have been
+changed. It assumes that they weren't, thus saving a few millisecs to stat
+the source file (multiplied by however many modules/libraries you are
+<STRONG>use</STRONG>/<STRONG>require</STRONG>-ing in your script.) The only check that is being done is whether your
+main script has been changed. So if you have only one script that doesn't <STRONG>use</STRONG> (or <STRONG>require</STRONG>) other perl modules (or packages), there is nothing new about it. If
+however, you are developing a script that includes other modules, the files
+you <STRONG>use()</STRONG> or <STRONG>require()</STRONG> aren't being checked to see if they have been modified.
<P>
+Acknowledging this, how do we get our modperl-enabled server to recognize
+changes in any library modules? Well, there are a couple of techniques:
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Restarting_the_server">Restarting the server</A></H2></CENTER>
<P>
@@ -3967,33 +4348,32 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Using_Apache_StatINC">Using Apache::StatINC</A></H2></CENTER>
<P>
-After restarting the server for about 100 times you will be tired and will
-look for another solutions. Here comes for a help the Apache::StatINC
-module.
+After restarting the server about 100 times, you will be tired and will
+look for another solutions. Help comes from the Apache::StatINC module.
<P>
Read its pod pages, but beware of the following note: Only the modules
-located in <CODE>@INC</CODE> are being reloaded on change, and you can
-change the <CODE>@INC</CODE> only before the server has been started.
-Whatever you do in you scripts/modules which are being
-<CODE>required()</CODE> after the server startup will not take an effect on
-@INC. When you do use lib <CODE>qw(foo/bar);</CODE> the <CODE>@INC</CODE>
-is being changed only for the time the code is being parsed. When it's over
-the <CODE>@INC</CODE> is being reset to its original value. To make sure
-that you have set a correct <CODE>@INC</CODE> fetch <A
+located in <STRONG>@INC</STRONG> are being reloaded on change, and you can change the <STRONG>@INC</STRONG> only before the server has been started. Whatever you do in your
+scripts/modules which are being <CODE>required()</CODE> after the server
+startup will not have any effect on <STRONG>@INC</STRONG>.
+
+<P>
+When you do <STRONG>use lib qw(foo/bar);</STRONG>, the <STRONG>@INC</STRONG> is being changed only for the time the code is being parsed. When it's over
+the <STRONG>@INC</STRONG> is being reset to its original value. To make sure that you have set a
+correct <STRONG>@INC</STRONG> fetch <A
HREF="http://your.perl.server/perl-status?inc">http://your.perl.server/perl-status?inc</A>
and watch the bottom of the page. (I assume you have configured the
-<Location /perl-status> section in httpd.conf as modperl docs shows.
+<Location /perl-status> section in httpd.conf as the mod_perl docs
+show.)
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Reloading_only_specific_files">Reloading only specific files</A></H2></CENTER>
<P>
-However checking all the Modules in <CODE>%INC</CODE> can add a some (big?)
-overhead to server response times, and you certainly wouldn't want
-Apache::StatINC module to be enabled in your production site's
-configuration. But sometimes you want to have some Configuration file
-(module) to be reloaded without restarting the whole server. For this you
+Checking all the Modules in <STRONG>%INC</STRONG> can add some (large?) overhead to server response times, and you certainly
+wouldn't want Apache::StatINC module to be enabled in your production
+site's configuration. But sometimes you want to have some Configuration
+file (module) be reloaded without restarting the whole server. For this you
will have to add something like this in your code:
<P>
@@ -4043,10 +4423,11 @@
}
</PRE>
<P>
-You will want to add debug printings to test this code in your application.
+You may want to add debug print statements to test this code in your
+application.
<P>
-Read also use versus require article for more info.
+Read the ``use versus require'' article for more info.
(http://www.perl.com/CPAN-local/doc/FMTEYEWTK/use_vs_require)
<P>
@@ -4056,9 +4437,9 @@
When using a regular expression that contains an interpolated Perl
variable, if it is known that the variable (or variables) will not vary
during the execution of the program, a standard optimization technique
-consists of adding the o modifier to the regexp pattern, to direct the
-compiler to build the internal table once, for the entire lifetime of the
-script, rather than every time the pattern is executed. Consider:
+consists of adding the <STRONG>/o</STRONG> modifier to the regexp pattern. This directs the compiler to build the
+internal table once, for the entire lifetime of the script, rather than
+every time the pattern is executed. Consider:
<P>
<PRE> my $pat = '^foo$'; # likely to be input from an HTML form field
@@ -4067,13 +4448,14 @@
}
</PRE>
<P>
-This is usually a big win in loops over lists, or when using grep or map.
+This is usually a big win in loops over lists, or when using
+<STRONG>grep</STRONG> or <STRONG>map</STRONG>.
<P>
In long-lived mod_perl scripts, however, this can pose a problem if the
variable changes according to the invocation. The first invocation of a
-fresh httpd child will compile the table and perform the search correctly,
-however, all subsequent uses by the httpd child will continue to match the
+fresh httpd child will compile the regex and perform the search correctly.
+However, all subsequent uses by the httpd child will continue to match the
original pattern, regardless of the current contents of the Perl variables
the pattern is dependent on. Your script will appear broken.
@@ -4081,9 +4463,9 @@
There are two solutions to this problem.
<P>
-The first is to use eval q//, to force the code to be evaluated each time.
-Just make sure that the eval block covers the entire loop of processing,
-and not just the pattern match itself.
+The first is to use <STRONG>eval q//</STRONG>, to force the code to be evaluated each time. Just make sure that the eval
+block covers the entire loop of processing, and not just the pattern match
+itself.
<P>
The above code fragment would be rewritten as:
@@ -4097,7 +4479,7 @@
}
</PRE>
<P>
-Just saying
+Just saying:
<P>
<PRE> eval q{ print if /$pat/o; };
@@ -4106,11 +4488,11 @@
is going to be a horribly expensive proposition.
<P>
-You use this approach if you require more than one pattern match operator
-in a given section of code. If the section contains only one operator (be
-it an m// or s///), you can rely on the property of the null pattern, that
-reuses the last pattern seen. This leads to the second solution, which also
-eliminates the use of eval.
+You can use this approach if you require more than one pattern match
+operator in a given section of code. If the section contains only one
+operator (be it an <STRONG>m//</STRONG> or <STRONG>s///</STRONG>), you can rely on the property of the null pattern, that reuses the last
+pattern seen. This leads to the second solution, which also eliminates the
+use of eval.
<P>
The above code fragment becomes:
@@ -4125,8 +4507,8 @@
<P>
The only gotcha is that the dummy match that boots the regular expression
engine must absolutely, positively succeed, otherwise the pattern will not
-be cached, and the // will match everything. If you can't count on fixed
-text to ensure the match succeeds, you have two possibilities.
+be cached, and the <STRONG>//</STRONG> will match everything. If you can't count on fixed text to ensure the match
+succeeds, you have two possibilities.
<P>
If you can guarantee that the pattern variable contains no meta-characters
@@ -4196,12 +4578,12 @@
Running in httpd -X mode. (good only for testing during development phase).
<P>
-You want to test your application that it handles correctly the global
-variables (if you have such - The less you have them the better, but
-sometimes you just can't without them). It's hard to test with multiply
-servers serving your cgi since each child has a different value for its
-global variables. Imagine that you have a <CODE>random()</CODE> sub that
-returns a random number and you have the following script.
+You want to test that your application correctly handles global variables
+(if you have any - the less you have of them the better, but sometimes you
+just can't without them). It's hard to test with multiple servers serving
+your cgi since each child has a different value for its global variables.
+Imagine that you have a <CODE>random()</CODE> sub that returns a random
+number and you have the following script.
<P>
<PRE> use vars qw($num);
@@ -4209,46 +4591,52 @@
print ++$num;
</PRE>
<P>
-This script initializes the <CODE>$num</CODE> with random value, then it
-increments on each request and print it out. Running this script in
-multiply server environment will result in something like 1,9,4,19 (number
-per reload), since ``each'' time your script will be served by a different
-child. (On some OSes parent process assign all the requests to the same
-child process if all of the children are idle... AIX...). But if you run in
-httpd -X single server mode you will get 2,3,4,5... (taken that the
-<CODE>random()</CODE> returned 1 at the first call)
+This script initializes the variable <STRONG>$num</STRONG> with a random value, then increments it on each request and prints it out.
+Running this script in multiple server environments will result in
+something like 1,9,4,19 (number per reload), since each time your script
+will be served by a different child. (On some OSes, the parent httpd
+process will assign all of the requests to the same child process if all of
+the children are idle... AIX...). But if you run in httpd -X single server
+mode you will get 2,3,4,5... (taken that the <CODE>random()</CODE> returned
+1 at the first call)
<P>
-But don't get too obsessive with this mode, since working only in single
+But do not get too obsessive with this mode, since working only in single
server mode sometimes hides problems that show up when you switch to multi
-server mode. Assume the following code:
+server mode. Consider an application that allows you to change the
+configuration at run time.
<P>
-Application that allows you to change the configuration at the run time.
Let's say the script produces a form to change the background color of the
-page. (It's not a good idea but for the sake of potential problem
-presentation we will assume that we don't write down the change on the
-disk). So you have typed in a new color , and as a respond you print back
+page. It's not a good design, but for the sake of demonstrating the
+potential problem, we will assume that our script doesn't write the changed
+background color to the disk, but simply changes it in memory.
+
+<P>
+So you have typed in a new color, and in response, your script prints back
the html with a new color - you think that's it! It was so simple. And if
you keep running in single server mode you will never notice that you have
-a problem... If you run the same code in the multi server environment ,
-after you submit the color change you will get the result as expected, but
-when you will call the same URL again (not reload!) chances are that you
-will get back the old color, since except the child who processed the color
-change request no one knows about their global variable change. Just
-remember that children can't share information, but the stuff they
-inherited from parent on their load.
+a problem...
+
+<P>
+If you run the same code in the multi server environment, after you submit
+the color change you will get the result as expected, but when you will
+call the same URL again (not reload!) chances are that you will get back
+the old color, since except the child who processed the color change
+request no one knows about their global variable change. Just remember that
+children can't share information, other than that which they inherited from
+their parent on their load.
<P>
-Also note that since the server is running in single mode - If the output
-returns HTML with IMG tags, the load of these will take a lot of time (read
-apache docs of httpd -X to learn why).
+Also note that since the server is running in single mode, if the output
+returns HTML with IMG tags, then the load of these will take a lot of time
+(read apache docs of httpd -X to learn why).
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="_M_and_other_time_file_tests_u">-M and other time() file tests under mod_perl</A></H1></CENTER>
<P>
-Under mod_perl files that have been created after the server's (child?)
+Under mod_perl, files that have been created after the server's (child?)
startup are being reported with negative age with -M (-C -A) test. This is
obvious if you remember that you will get the negative result if the server
was started before the file was created and it's a normal behavior with any
@@ -4263,17 +4651,36 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A></H1></CENTER>
<P>
-Ok, When user decided to press the stop button, apache will detect that
-thru the SIG{'PIPE'} and will cease the script execution. When we are
-talking about mod_cgi, there are generally no problem, since all opened
-files will be closed and all the resources will be freed (almost if you
-happened to use external lock files, most chances that the resources that
-are being locked by these will be left blocked and non-usable by any other,
-who will use this advisory locking scheme).
+When a user presses the stop button, Apache will detect that via
+SIG{'PIPE'} and will cease the script execution. When we are talking about
+mod_cgi, there is generally no problem, since all opened files will be
+closed and all the resources will be freed (almost all -- if you happened
+to use external lock files, most likely the resources that are being locked
+by these will be left blocked and non-usable by any others who use this
+advisory locking scheme.)
+<P>
+Important to notice that when the user hits ``stop'' on the browser, the
+mod_perl script is blissfully unaware until it tries to send some data to
+the browser. At that point, Apache realizes that the browser is gone, and
+all the good cleanup stuff happens.
+
+<P>
+Starting from apache 1.3.6 apache will not catch SIGPIPE anymore and
+modperl will do it much better. Here is something from CHANGES from Apache
+1.3.6.
+
+<P>
+<PRE> *) SIGPIPE is now ignored by the server core. The request write
+ routines (ap_rputc, ap_rputs, ap_rvputs, ap_rwrite, ap_rprintf,
+ ap_rflush) now correctly check for output errors and mark the
+ connection as aborted.
+ Replaced many direct (unchecked) calls to ap_b* routines with the
+ analogous ap_r* calls. [Roy Fielding]
+</PRE>
<P>
-What's happening if your mod_perl script has some global variables, that
-are being used for resource locking?
+What happens if your mod_perl script has some global variables, that are
+being used for resource locking?
<P>
It's possible not to notice the pitfall if the critical code section
@@ -4289,14 +4696,14 @@
3. unlock resource
</PRE>
<P>
-If user presses 'Stop' and Apache sends SIGPIPE before stage 3, since we
-are in the mod_perl mode and we want the lock variable to be cached, it
-will be not unlocked. A kind of ``deadlock''.
+If user presses 'Stop' and Apache sends SIGPIPE before step 3, since we are
+in the mod_perl mode and we want the lock variable to be cached, it will be
+not unlocked. A kind of ``deadlock'' exists.
<P>
Here is the working example. Run the server with -X, Press 'Stop' before
the countup to 10 has been finished. Then rerun the script, it'll hang in
-<CODE>while(1)!</CODE> Resource is not available anymore.
+<CODE>while(1)!</CODE> The resource is not available anymore.
<P>
<PRE> -------------------------------------------------------------
@@ -4305,12 +4712,10 @@
$|=1;
my $q = new CGI;
print $q->header,$q->start_html;
-</PRE>
-<P>
-<PRE> print $q->p("$$ Going to lock!\n");
-</PRE>
-<P>
-<PRE> # actually the while loop below is not needed
+
+ print $q->p("$$ Going to lock!\n");
+
+ # actually the while loop below is not needed
# (since it's an internal lock and accessible only
# by the same process and it if it's locked... it's locked for the
# whole child's life
@@ -4327,15 +4732,14 @@
sleep 1;
print $c++,"\n<BR>";
}
-</PRE>
-<P>
-<PRE> print $q->p("Going to unlock!");
+
+ print $q->p("Going to unlock!");
$CACHE{LOCK} = 0;
print $q->p("Unlock!\n");
-------------------------------------------------------------
</PRE>
<P>
-You will ask, what is the solution for this problem? As noted in the
+You may ask, what is the solution for this problem? As noted in the
<A HREF="././porting.html#END_blocks">END blocks</A> any END blocks that are encountered during compilation of Apache::Registry
scripts are called after the script done is running, including subsequent
invocations when the script is cached in memory. So if you are running in
@@ -4357,32 +4761,56 @@
<PRE> $r->register_cleanup(sub {$CACHE{LOCK} = 0;});
</PRE>
<P>
+If you are into Apache API <CODE>Apache-</CODE>request->connection->aborted()> construct can be used to test for
+the aborted connection.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Handling_the_server_timeout_case">Handling the server timeout cases</A></H1></CENTER>
+<P>
+A similar situation to <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Pressed Stop button disease</A> happens when client (browser) timeouts the connection (is it about 2
+minutes?) . There are cases when your script is about to perform a very
+long operation and there is a chance that its duration will be longer than
+the client's timeout. One case I can think about is the DataBase
+interaction, where the DB engine hangs or needs a lot of time to return
+results. If this is the case, use <CODE>$SIG{ALRM}</CODE> to prevent the timeouts:
+
+<P>
+<PRE> eval {
+ local $SIG{ALRM} = sub { die "timeout\n" };
+ alarm $timeout;
+ ... db stuff ...
+ alarm 0;
+ };
+
+ die $@ if $@;
+</PRE>
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Where_do_the_warnings_errors_go_">Where do the warnings/errors go?</A></H1></CENTER>
<P>
-Your cgi doesn't work and you want to see what is the problem. The best
-idea is to checkout what the server error report. Where I can find this
-report?
+Your CGI doesn't work and you want to see what the problem is. The best
+idea is to check out any errors that the server may be reporting. Where I
+can find these errors?
<P>
-Generally all the errors are being logged into an error_log file. The exact
-file location and name are defined in the http.conf file. Watch the
-<CODE>ErrorLog</CODE> parameter. My httpd.conf says:
+Generally all errors are logged into an error_log file. The exact file
+location and name are defined in the http.conf file. Look for the <CODE>ErrorLog</CODE> parameter. My httpd.conf says:
<P>
<PRE> ErrorLog var/logs/error_log
</PRE>
<P>
-Hey, where is the beginning of the path? There is another apache's
-parameter called <CODE>ServerRoot</CODE>. Everytime apache sees a value of the parameter with no absolute path (e.g <CODE>/tmp/my.txt</CODE>) but with relative path (e.g <CODE>my.txt</CODE>) it prepends the value of the <CODE>ServerRoot</CODE> to this value. I have:
+Hey, where is the beginning of the path? There is another Apache parameter
+called <CODE>ServerRoot</CODE>. Everytime apache sees a value of the parameter with no absolute path (e.g <CODE>/tmp/my.txt</CODE>) but with relative path (e.g <CODE>my.txt</CODE>) it prepends the value of the <CODE>ServerRoot</CODE> to this value. I have:
<P>
<PRE> ServerRoot /usr/local/apache
</PRE>
<P>
So I will look for error_log file at
-<CODE>/usr/local/apache/var/logs/error_log</CODE>. Ofcourse you can use a absolute path to define the file's location at the
-filesystem.
+<CODE>/usr/local/apache/var/logs/error_log</CODE>. Of course you can also use an absolute path to define the file's location
+at the filesystem.
<P>
<META>: is this 100% correct?
@@ -4391,16 +4819,20 @@
But there are cases when errors don't go to the error_log file. For example
some errors are being printed to the console (tty) you have executed the
httpd from (unless you redirected the httpd's stderr flow). This happens
-when the server didn't open the error_log file for writing yet. So if the
-error happens when server executes PerlRequire or PerlModule directive you
-might see the errors goes to the tty.
+when the server didn't open the error_log file for writing yet.
+
+<P>
+For example, if you have mistakenly entered a non-existent directory path
+in your <STRONG>ErrorLog</STRONG> directive, the error message will be printed on the controlling tty. Or, if
+the error happens when server executes PerlRequire or PerlModule directive
+you might see the errors here also.
<P>
-You are probably wander where all the errors go when you are running the
-server in the single mode (httpd -X). They go to the console. That's
-because when running in the single mode there is no parent httpd process
-who performs all the logging. It includes all the status messages that
-generally show up in the error_log file.
+You are probably wonder where all the errors go when you are running the
+server in single mode (httpd -X). They go to the console. That is because
+when running in the single mode there is no parent httpd process to perform
+all the logging. It includes all the status messages that generally show up
+in the error_log file.
<P>
</META>
@@ -4419,7 +4851,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 01/23/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
@@ -4452,6 +4884,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -4463,7 +4903,7 @@
<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
- <LI><A HREF="#A_general_advice">A general advice </A>
+ <LI><A HREF="#General_Advice">General Advice </A>
<LI><A HREF="#Value_of_x_will_not_stay_shared">Value of $x will not stay shared at - line 5</A>
<LI><A HREF="#Value_of_x_may_be_unavailable_a">Value of $x may be unavailable at - line 5.</A>
<LI><A HREF="#mod_perl_rwrite_returned_1">mod_perl: rwrite returned -1</A>
@@ -4485,9 +4925,9 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<CENTER><H1><A NAME="A_general_advice">A general advice</A></H1></CENTER>
+<CENTER><H1><A NAME="General_Advice">General Advice</A></H1></CENTER>
<P>
-Using the <CODE>use diagnostics;</CODE> generally helps you to determine the source of the problem and how to solve
+Enabling <CODE>use diagnostics;</CODE> generally helps you to determine the source of the problem and how to solve
it. See <A HREF="././porting.html#diagnostics_pragma">diagnostics pragma</A> for more info.
<P>
@@ -4518,10 +4958,9 @@
[modperl] process 1234 going to Apache::exit with status...
</PRE>
<P>
-That's the $SIG{PIPE} handler installed by mod_perl/Apache::SIG, called if
-a connection timesout or Client presses the 'Stop' button. It gives you an
-opportunity to make cleanups if the script was aborted in the middle of its
-execution. See <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A> for more info.
+That's the <STRONG>$SIG{PIPE}</STRONG> handler installed by mod_perl/Apache::SIG, called if a connection timesout
+or Client presses the 'Stop' button. It gives you an opportunity to do
+cleanups if the script was aborted in the middle of its execution. See <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A> for more info.
<P>
If your mod_perl version < 1.17 you might get the message in the
@@ -4544,8 +4983,7 @@
That's a mandatory warning inside Perl. It happens only if you modify your
script and Apache::Registry reloads it. Perl is warning you that the
<CODE>subroutine(s)</CODE> were redefined. It is mostly harmless. If you
-don't like seeing those, just kill -USR2 (graceful restart) apache when you
-modify your scripts.
+don't like seeing those, just <CODE>kill -USR2</CODE> (graceful restart) apache when you modify your scripts.
<P>
<PRE> <META>
@@ -4563,8 +5001,8 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Global_symbol_foo_requires_ex">Global symbol "$foo" requires explicit package name</A></H1></CENTER>
<P>
-A script below will print a warning like above, moreover it will print the
-whole script as a part of the warning message:
+The script below will print a warning like above, moreover it will print
+the whole script as a part of the warning message:
<P>
<PRE> #!/usr/bin/perl -w
@@ -4599,13 +5037,12 @@
/lib/perl5/site_perl/5.005/aix/Apache/Constants.pm line 23.
</PRE>
<P>
-The error is simple to fix. When you use <CODE>use strict;</CODE> pragma (and you better do that), all variables should be defined before
-being used.
+The error is simple to fix. When you use the <CODE>use strict;</CODE> pragma (and you should...), all variables should be defined before being
+used.
<P>
-The bad thing is that sometimes the whole script that can be of thousands
-lines is being printed to error_log file as a code that the server has
-tried to <CODE>eval()uate.</CODE>
+The bad thing is that sometimes the whole script (possibly, thousands of
+lines) is printed to error_log file as a code that the server has tried to <STRONG>eval()</STRONG>uate.
<P>
As Doug answered to this question:
@@ -4636,47 +5073,52 @@
<P>
This problem is caused when, a client drops the connection while httpd is
in the middle of a write, httpd timeout happens, sending a SIGPIPE, and
-Perl in that child is stuck in the middle of it's eval context. This is
+Perl in that child is stuck in the middle of its eval context. This is
fixed by the Apache::SIG module which is called by default. This should not
-happen unless you have code that is messing with $SIG{PIPE}. It's also
-triggered only when you've changed your script on disk and mod_perl is
-trying to reload it.
+happen unless you have code that is messing with <STRONG>$SIG{PIPE}</STRONG>. It's also triggered only when you've changed your script on disk and
+mod_perl is trying to reload it.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Use_of_uninitialized_value_at_e">Use of uninitialized value at (eval 80) line 12.</A></H1></CENTER>
<P>
-If you compile with the experimental PERL_MARK_WHERE=1, it shows you
-``exactly'' where this is happening. many times compiler makes a shift for
-``unknown'' reasons in it's line counter. You can always stuff you code
-with special compiler directives, to reset it's counter to the value you
-will tell. At the beginning of the line you should write (# sticked to the
-leftmost side):
+If you compile with the experimental <STRONG>PERL_MARK_WHERE=1</STRONG>, it shows you ``exactly'' where this is happening. many times compiler
+makes a shift for ``unknown'' reasons in its line counter. You can always
+stuff your code with special compiler directives, to reset its counter to
+the value you will tell. At the beginning of the line you should write (the
+'#' in column 1):
<P>
<PRE> #line 298 myscript.pl
</PRE>
<P>
-(myscript.pl is optional). It specifies the line number of the _following_
-line, not the line the directive is on. You can use a little script to
-stuff every N lines of your code with this directives, but then you will
-have to rerun this script every time you add remove code lines. The script:
+(myscript.pl is optional.) This specifies the line number of the
+<STRONG>following</STRONG> line, not the line the directive is on. You can use a little script to
+stuff every N lines of your code with these directives, but then you will
+have to rerun this script every time you add or remove code lines. The
+script:
<P>
+<PRE> <META>
+ This example was double incrementing $counter.
+ I took the second increment out -- sgr.
+ </META>
+</PRE>
+<P>
<PRE> #!/usr/bin/perl
# Puts Perl line markers in a Perl program for debugging purposes.
# Also takes out old line markers.
die "No filename to process.\n" unless @ARGV;
- my $filename = $ARGV[0];
+ my $filename = $ARGV[0];
my $lines = 100;
open IN, $filename or die "Cannot open file: $filename: $!\n";
- open OUT, ">$filename.marked" or die "Cannot open file: $filename.marked: $!\n";
+ open OUT, ">$filename.marked"
+ or die "Cannot open file: $filename.marked: $!\n";
my $counter = 1;
while (<IN>) {
print OUT "# line $counter\n" unless $counter++ % $gap;
next if $_ =~ /^# line /;
print OUT $_;
- $counter++;
}
close OUT;
close IN;
@@ -4699,9 +5141,9 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Can_t_load_auto_DBI_DBI_so_">Can't load '.../auto/DBI/DBI.so' for module DBI</A></H1></CENTER>
<P>
-Checkout that all your modules are compiled with the same perl that is
-being compiled into mod_perl. perl5.005 and 5.004 are binary incompatible
-by default.
+Check that all your modules are compiled with the same perl that is being
+compiled into mod_perl. perl 5.005 and 5.004 are not binary compatible by
+default.
<P>
Other known causes of this problem: OS distributions that ship with a
@@ -4709,8 +5151,8 @@
library are somehow built with different binary compatibility flags.
<P>
-The solution to these problems is to rebuild Perl and extension modules
-from a fresh source tree. Tip for running Perl's Configure script, use the
+The solution to these problems is to rebuild Perl and any extension modules
+from a fresh source tree. Tip for running Perl's Configure script: use the
`-des' flags to accepts defaults and `-D' flag to override certain
attributes:
@@ -4742,8 +5184,8 @@
See <A HREF="#Out_of_memory_">Out_of_memory!</A>
<P>
-I've just discovered that the server is not responding and error log filled
-up the remaining space on the file system (about a gig's worth). The
+I've just discovered that my server is not responding and its error log has
+filled up the remaining space on the file system (about a gig's worth). The
error_log includes millions of lines:
<P>
@@ -4759,7 +5201,7 @@
error, so Perl is stuck in a loop writing that same message to stderr.
<P>
-Perl 5.005+ plus is recommended for it's improved malloc.c and features
+Perl 5.005+ plus is recommended for its improved malloc.c and features
mentioned in mod_perl_traps.pod on by default.
<P>
@@ -4767,10 +5209,10 @@
<CENTER><H1><A NAME="Out_of_memory_">Out of memory!</A></H1></CENTER>
<P>
If something goes really wrong with your code, Perl may die with an ``Out
-of memory!'' message and or ``Callback called exit''. A common cause of
-this are never-ending loops, deep recursion or calling an undefined
-subroutine. Here's one way to catch the problem: See Perl's INSTALL
-document for this item:
+of memory!'' message and/or ``Callback called exit''. Common causes of this
+are never-ending loops, deep recursion, or calling an undefined subroutine.
+Here's one way to catch the problem: See Perl's INSTALL document for this
+item:
<P>
<PRE> =item -DPERL_EMERGENCY_SBRK
@@ -4781,8 +5223,8 @@
variable $^M. See perlvar(1) for more details.
</PRE>
<P>
-If you compile with that option and add 'use Apache::Debug level => 4;'
-to your PerlScript, it will allocate the $^M emergency pool and the
+If you compile with that option and add '<CODE>use Apache::Debug level =&gt;
+4;</CODE>' to your PerlScript, it will allocate the $^M emergency pool and the
$SIG{__DIE__} handler will call Carp::confess, giving you a stack trace
which should reveal where the problem is. See the Apache::Resource module
for prevention of spinning httpds.
@@ -4813,20 +5255,23 @@
the corresponding filesystem path. Most of failures happen when one passes
a file path instead of URI. (A reminder: /home/httpd/perl/test.pl is a file
path, while /perl/test.pl is an URI). In most cases all you have to do is
-to path something that RegistryLoader expects to get - the URI, but there
-are more complex cases, RegistryLoader's man page shows how to handle these
+to pass something that RegistryLoader expects to get - the URI, but there
+are more complex cases. RegistryLoader's man page shows how to handle these
cases as well (watch for the <CODE>trans()</CODE> sub).
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A></H1></CENTER>
<P>
-Not all Perl modules can survive a reload. PerlFreshRestart does nothing
+Not all Perl modules can survive a reload. PerlFreshRestart does not much
more than:
<P>
-while (my($k,$v) = each %INC) { delete $INC{$k}; require $k; }
-
+<PRE> while (my($k,$v) = each %INC) {
+ delete $INC{$k};
+ require $k;
+ }
+</PRE>
<P>
Besides that, it flushes the Apache::Registry cache, and empties any
dynamic stacked handlers (e.g. PerlChildInitHandler).
@@ -4849,7 +5294,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/15/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
@@ -4882,6 +5327,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -4972,16 +5425,24 @@
compile method of CGI.pm. The third test checks benefit the the Library
Perl Module preload but a few of them (too see more memory saved) and also
the effect of precompiling the Registry modules with
-Apache::RegistryLoader.
+Apache::RegistryLoader.
<P>
-Summary: 1. Library Perl Modules Preloading gave a good results everywhere.
+Summary:
+
+<P>
+1. Library Perl Modules Preloading gave a good results everywhere.
+
+<P>
2. compile method of CGI seems to make things worse (may be the speed is
-better?) 3. Apache::RegistryLoader might made the script load faster on the
-first request after the child has just started but the memory usage was
-worse!!! See the numbers by yourself.
+better?)
<P>
+3. Apache::RegistryLoader might made the script load faster on the first
+request after the child has just started but the memory usage was worse!!!
+See the numbers by yourself.
+
+<P>
HW/SW: The server is apache 1.3.2, mod_perl 1.16 running on AIX 4.1.5
<P>
@@ -5201,7 +5662,7 @@
httpd 26844 0.0 1.0 6748 5092 - A 17:23:12 0:00 httpd
</PRE>
<P>
-Observation: child httpd has grown even more 3316K ! Doesn't seem to be
+Observation: child httpd has grown even more 3316K ! Does not seem to be
good!
<P>
@@ -5212,15 +5673,16 @@
each child with Apache::DBI.
<P>
-<PRE> use Apache::DBI ();
- Apache::DBI->connect_on_init("DBI:mysql:test", '','', {
- RaiseError => 1,
- PrintError => 1,
- AutoCommit => 1,
- };
+<PRE> use Apache::DBI ();
+ Apache::DBI->connect_on_init("DBI:mysql:test", 'login','passwd',
+ {
+ RaiseError => 1,
+ PrintError => 1,
+ AutoCommit => 1,
+ };
</PRE>
<P>
-See also <A HREF="#Persistent_DB_Connections">Persistant DB Connections</A>
+See also <A HREF="#Persistent_DB_Connections">Persistent DB Connections</A>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -5249,7 +5711,7 @@
warn "pre-load of `$url' failed, status=$status\n";
}
}, $perl_dir);
- }
+ }
</PRE>
<P>
Note that we don't use here the second argument to the
@@ -5273,7 +5735,7 @@
<P>
When possible, avoid importing of a module functions into your namespace.
The aliases which are created can take up quite a bit of space. Try to use
-method interfaces and fully qualified Package::function names instead.
+method interfaces and fully qualified Package::function names instead.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -5293,7 +5755,7 @@
<P>
Joel Wagner reports that calling an undefined subroutine in a module can
cause a tight loop that consumes all memory. Here is a way to catch such
-errors. Define an autoload subroutine
+errors. Define an autoload subroutine:
<P>
<PRE> sub UNIVERSAL::AUTOLOAD {
@@ -5500,21 +5962,18 @@
<P>
<PRE> Benchmark: timing 100 iterations of cgi, perl... [rate 1:28]
-</PRE>
-<P>
-<PRE> cgi: 56 secs ( 0.33 usr 0.28 sys = 0.61 cpu)
+
+ cgi: 56 secs ( 0.33 usr 0.28 sys = 0.61 cpu)
perl: 2 secs ( 0.31 usr 0.27 sys = 0.58 cpu)
Benchmark: timing 1000 iterations of cgi,perl... [rate 1:21]
-</PRE>
-<P>
-<PRE> cgi: 567 secs ( 3.27 usr 2.83 sys = 6.10 cpu)
+
+ cgi: 567 secs ( 3.27 usr 2.83 sys = 6.10 cpu)
perl: 26 secs ( 3.11 usr 2.53 sys = 5.64 cpu)
Benchmark: timing 10000 iterations of cgi, perl [rate 1:21]
-</PRE>
-<P>
-<PRE> cgi: 6494 secs (34.87 usr 26.68 sys = 61.55 cpu)
+
+ cgi: 6494 secs (34.87 usr 26.68 sys = 61.55 cpu)
perl: 299 secs (32.51 usr 23.98 sys = 56.49 cpu)
</PRE>
<P>
@@ -5600,9 +6059,8 @@
<P>
<PRE> % ./ab -n 100 -c 10 www.you.com:81/test/test.pl
-</PRE>
-<P>
-<PRE> Concurrency Level: 10
+
+ Concurrency Level: 10
Time taken for tests: 0.715 seconds
Complete requests: 100
Failed requests: 0
@@ -5611,9 +6069,8 @@
HTML transferred: 31900 bytes
Requests per second: 139.86
Transfer rate: 84.90 kb/s received
-</PRE>
-<P>
-<PRE> Connection Times (ms)
+
+ Connection Times (ms)
min avg max
Connect: 0 0 3
Processing: 13 67 71
@@ -5655,10 +6112,16 @@
500</CODE> derived 94.82 req/sec. It went down with the high load.
<P>
-This test was performed with the following configuration: MinSpareServers 8
-MaxSpareServers 6 StartServers 10 MaxClients 50 MaxRequestsPerChild 1500
+This test was performed with the following configuration:
<P>
+<PRE> MinSpareServers 8
+ MaxSpareServers 6
+ StartServers 10
+ MaxClients 50
+ MaxRequestsPerChild 1500
+</PRE>
+<P>
Now let's try this:
<P>
@@ -5691,7 +6154,7 @@
MaxRequestsPerChild 1500
</PRE>
<P>
-I've got 27.12 req/sec, which is better but still 4-5 times slower (133
+I have got 27.12 req/sec, which is better but still 4-5 times slower (133
with Maxclients of 50)
<P>
@@ -5705,32 +6168,36 @@
<P>
The important parameters are MaxClients and MaxRequestsPerChild. MaxClients
-should be not to big so it'll not abuse your machine's memory resources and
-not too small, when users will be forced to wait for the children to become
-free to come serve them. MaxRequestsPerChild should be as big as possible,
-to take the full benefit of the mod_perl, but watch your server at the
-beginning to make sure your scripts aren't leaking memory causing your
-server (and your service) to die very fast.
+should be not to big so it will not abuse your machine's memory resources
+and not too small, when users will be forced to wait for the children to
+become free to come serve them. MaxRequestsPerChild should be as big as
+possible, to take the full benefit of the mod_perl, but watch your server
+at the beginning to make sure your scripts are not leaking memory causing
+your server (and your service) to die very fast.
<P>
-Also it's important to understand that we didn't test the respond times in
+Also it is important to understand that we didn't test the respond times in
the tests above, but the ability of the server to respond. If the script
that was used to test was heavier, the numbers would be different but the
conclusions are very similar.
<P>
-The benchmarks were run at: HW: RS6000, 1Gb RAM SW: AIX 4.1.5 . mod_perl
-1.16, apache 1.3.3 Machine running only mysql service, httpd docs and
-mod_perl servers. Machine was completely unloaded during the benchmarking.
+The benchmarks were run at:
<P>
+<PRE> HW: RS6000, 1Gb RAM
+ SW: AIX 4.1.5 . mod_perl 1.16, apache 1.3.3
+ Machine running only mysql service, httpd docs and mod_perl servers.
+ Machine was completely unloaded during the benchmarking.
+</PRE>
+<P>
After each server restart when I did changes to server's configurations, I
made sure the scripts were preloaded by fetching a script at least one time
by each child.
<P>
-It's important to notice that None of requests timeouted even if was kept
-in server's queue form more than 1 minute! (That's the way <STRONG>ab</STRONG>
+It is important to notice that None of requests timeouted even if was kept
+in server's queue form more than 1 minute! (That is the way <STRONG>ab</STRONG>
works, which is OK for the test but will not for the real world - user will
not wait for more than 5-10 secs for a request to complete, and the browser
will timeout in a 30 secs or so)
@@ -5773,7 +6240,7 @@
Conclusions: Here I wanted to show that when the application is slow not
because of perl loading, script compiling and execution, but bounded to
some external operation like mysqld querying which made the bottleneck - it
-almost doesn't matter what is the load we make - the RPS (Requests per
+almost does not matter what is the load we make - the RPS (Requests per
second) is almost the same (taken that all the requested has been served,
you have an ability to queue the clients, but be aware that something that
goes to queue means a waiting client and browser can get timeouted!)
@@ -5821,9 +6288,8 @@
StartServers 50
MaxClients 50
MaxRequestsPerChild 5000
-</PRE>
-<P>
-<PRE> NR NC RPS comment
+
+ NR NC RPS comment
------------------------------------------------
100 10 32.05
1000 10 33.14
@@ -5846,9 +6312,8 @@
StartServers 10
MaxClients 10
MaxRequestsPerChild 5000
-</PRE>
-<P>
-<PRE> NR NC RPS comment
+
+ NR NC RPS comment
------------------------------------------------
10 10 23.87 # not a reliable stats
100 10 32.64
@@ -5875,9 +6340,8 @@
MaxSpareServers 16
StartServers 10
MaxClients 50
-</PRE>
-<P>
-<PRE> NR NC MRPC RPS comment
+
+ NR NC MRPC RPS comment
------------------------------------------------
100 10 10 5.77
100 10 5 3.32
@@ -5896,9 +6360,8 @@
MaxSpareServers 16
StartServers 10
MaxClients 50
-</PRE>
-<P>
-<PRE> NR NC RPS comment
+
+ NR NC RPS comment
------------------------------------------------
100 10 1.12
1000 50 1.14
@@ -6280,15 +6743,14 @@
<CENTER><H1><A NAME="Persistent_DB_Connections">Persistent DB Connections</A></H1></CENTER>
<P>
Another popular use of mod_perl is to take advantage of it's persistence to
-maintain open database connections. The basic idea goes like so:
+maintain open database connections. The basic idea goes like so:
<P>
<PRE> #Apache::Registry script
use strict;
use vars qw($dbh);
-</PRE>
-<P>
-<PRE> $dbh ||= SomeDbPackage->connect(...);
+
+ $dbh ||= SomeDbPackage->connect(...);
</PRE>
<P>
Since <CODE>$dbh</CODE> is a global variable for the child, once the child
@@ -6307,9 +6769,10 @@
the ping method. If these two conditions are fulfilled it just returns the
database handle. If there is no appropriate database handle or if the ping
method fails, a new connection is established and the handle is stored for
-later re-use. <STRONG>There is no need to delete the disconnect statements from your
-code</STRONG>. They won't do anything because the Apache::DBI module overloads the
-disconnect method with a NOP.
+later re-use. <STRONG>There is no need to delete the disconnect statements from
+your code</STRONG>. They would not do anything because the Apache::DBI module overloads the
+disconnect method with a NOP. On child exit there is no explicit
+disconnect, the child dies and so does the database connection.
<P>
The usage is simple:
@@ -6318,10 +6781,11 @@
<PRE> httpd.conf
----------
PerlModule Apache::DBI
-
-It is important, to load this module before any other ApacheDBI module !
</PRE>
<P>
+It is important, to load this module before any other ApacheDBI module !
+
+<P>
<PRE> a script.perl
------------
use DBI;
@@ -6330,9 +6794,8 @@
my $dbh = DBI->connect( 'DBI:mysql:database', 'user', 'password',
{ autocommit => 0 }
) || die $DBI::errstr;
-</PRE>
-<P>
-<PRE> ...rest of program
+
+ ...rest of program
</PRE>
<P>
The module provides the additional method:
@@ -6348,7 +6811,7 @@
to see the requirements for this method.
<P>
-However be warned that some old DBD drivers aren't supporting this feature
+However be warned that some old DBD drivers are not supporting this feature
(ping method), so check the documentation of the driver you use.
<P>
@@ -6392,6 +6855,7 @@
information on the execution time of a Perl script and of the subs in that
script. This information can be used to determine which subroutines are
using the most time and which subroutines are being called most often.
+
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P><A HREF="index.html">[Back to the main page]</A></P>
@@ -6406,7 +6870,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/15/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
@@ -6439,6 +6903,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -6598,6 +7070,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -6689,7 +7169,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/13/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
@@ -6716,12 +7196,340 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
+ <TITLE>mod_perl guide: Perl Reference</TITLE>
+ <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
+ <META NAME="Author" CONTENT="Bekman Stas">
+ <META NAME="Description" CONTENT="mod_perl,perl,apache">
+ <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
+<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+Perl Reference</H1>
+<HR WIDTH="100%">
+ <!-- INDEX BEGIN -->
+<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+<UL>
+
+ <LI><A HREF="#Coverage">Coverage</A>
+ <LI><A HREF="#Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A>
+ <UL>
+
+ <LI><A HREF="#Making_the_variables_global">Making the variables global</A>
+ <LI><A HREF="#Making_the_variables_global_with">Making the variables global with strict pragma On</A>
+ <LI><A HREF="#Using_Exporter_pm_to_share_globa">Using Exporter.pm to share global variables</A>
+ <LI><A HREF="#Using_aliasing_perl_feature_to_s">Using aliasing perl feature to share global variables</A>
+ </UL>
+
+</UL>
+<!-- INDEX END -->
+
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<P>
+<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
+<P>
+This new document was born because some users reluctant to learn perl prior
+to jumping into a mod_perl. I will try to cover some of the most frequent
+pure perl questions being asked at the list.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A></H1></CENTER>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Making_the_variables_global">Making the variables global</A></H2></CENTER>
+<P>
+When you first wrote <CODE>$x</CODE> in your code you created a global
+variable. It is visible everywhere in the file you have use it. or if
+defined it inside a package - it is visible inside this package. But it
+will work only if you do not use <CODE>strict</CODE> pragma and you <STRONG>HAVE</STRONG> to use this pragma if you want to run your scripts under mod_perl. Read <A HREF="././porting.html#strict_pragma">Strict pragma</A> to find out why.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Making_the_variables_global_with">Making the variables global with strict pragma On</A></H2></CENTER>
+<P>
+First you use :
+
+<P>
+<PRE> use strict;
+</PRE>
+<P>
+Then you use:
+
+<P>
+<PRE> use vars qw($scalar %hash @array);
+</PRE>
+<P>
+Starting from this moment the variables are global in the package you
+defined them, if you want to share global variables between packages, here
+what you can do.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Using_Exporter_pm_to_share_globa">Using Exporter.pm to share global variables</A></H2></CENTER>
+<P>
+Assume that you want to share the <CODE>CGI.pm</CODE>'s object (I will use <CODE>$q</CODE>) between your modules. For example you create it in the <CODE>script.pl</CODE>, but want it to be visible in <CODE>My::HTML</CODE>. First - you make <CODE>$q</CODE> global.
+
+<P>
+<PRE> script.pl:
+ ----------------
+ use vars qw($q);
+ use CGI;
+ use My::HTML qw($q);
+ $q = new CGI;
+
+ My::HTML::printmyheader();
+ ----------------
+</PRE>
+<P>
+Note that we have imported <CODE>$q</CODE> from <CODE>My::HTML</CODE>. And the <CODE>My::HTML</CODE>
+which does the export of <CODE>$q</CODE>:
+
+<P>
+<PRE> My/HTML.pm
+ ----------------
+ package My::HTML;
+ use strict;
+
+ BEGIN {
+ use Exporter ();
+
+ @My::HTML::ISA = qw(Exporter);
+ @My::HTML::EXPORT = qw();
+ @My::HTML::EXPORT_OK = qw($q);
+
+ }
+
+ use vars qw($q);
+
+ sub printmyheader{
+ # Whatever you want to do with $q... e.g.
+ print $q->header();
+ }
+ -------------------
+</PRE>
+<P>
+So the <CODE>$q</CODE> is being shared between the <CODE>My::HTML</CODE> package and the
+<CODE>script.pl</CODE>. It will work vice versa as well, if you create the object in the <CODE>My::HTML</CODE> but use it in the <CODE>script.pl</CODE>. You have a true sharing, since if you change <CODE>$q</CODE> in <CODE>script.pl</CODE>, it will be changed in <CODE>My::HTML</CODE> as well.
+
+<P>
+What if you need to share <CODE>$q</CODE> between more than 2 packages? For example you want My::Doc to share <CODE>$q</CODE> as well.
+
+<P>
+You leave the <CODE>My::HTML</CODE> untouched, modify the script.pl to include:
+
+<P>
+<PRE> use My::Doc qw($q);
+</PRE>
+<P>
+And write the <CODE>My::Doc</CODE> exactly like <CODE>My::HTML</CODE> - of course that the content is different :).
+
+<P>
+One possible pitfall is when you want to use the <CODE>My::Doc</CODE> in both
+<CODE>My::HTML</CODE> and <CODE>script.pl</CODE>. Only if you add:
+
+<P>
+<PRE> use My::Doc qw($q);
+</PRE>
+<P>
+Into a <CODE>My::HTML</CODE>, the <CODE>$q</CODE> will be shared. Otherwise <CODE>My::Doc</CODE> will not share the <CODE>$q</CODE> anymore. To make things clear here is the code:
+
+<P>
+<PRE> script.pl:
+ ----------------
+ use vars qw($q);
+ use CGI;
+ use My::HTML qw($q);
+ use My::Doc qw($q);
+ $q = new CGI;
+
+ My::HTML::printmyheader();
+ ----------------
+</PRE>
+<P>
+<PRE> My/HTML.pm
+ ----------------
+ package My::HTML;
+ use strict;
+
+ BEGIN {
+ use Exporter ();
+
+ @My::HTML::ISA = qw(Exporter);
+ @My::HTML::EXPORT = qw();
+ @My::HTML::EXPORT_OK = qw($q);
+
+ }
+
+ use vars qw($q);
+ use My::Doc qw($q);
+
+ sub printmyheader{
+ # Whatever you want to do with $q... e.g.
+ print $q->header();
+
+ My::Doc::printtitle('Guide');
+ }
+ -------------------
+</PRE>
+<P>
+<PRE> My/Doc.pm
+ ----------------
+ package My::Doc;
+ use strict;
+
+ BEGIN {
+ use Exporter ();
+
+ @My::Doc::ISA = qw(Exporter);
+ @My::Doc::EXPORT = qw();
+ @My::Doc::EXPORT_OK = qw($q);
+
+ }
+
+ use vars qw($q);
+
+ sub printtitle{
+ my $title = shift || 'None';
+
+ print $q->h1($title);
+ }
+ -------------------
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Using_aliasing_perl_feature_to_s">Using aliasing perl feature to share global variables</A></H2></CENTER>
+<P>
+As the title says you can import a variable into a script/module without
+using an Exporter.pm. I have found it usefull to keep all the configuration
+variables in one module <CODE>My::Config</CODE>. But then I have to export all the variables in order to use them in other
+modules, which is bad for two reasons: polluting other packages' namespaces
+with extra tags which rise up the memory requirements, adding an overhead
+of keeping track of what variables should be exported from the config
+module and what imported for some particular package. I solve this problem
+by keeping all the variables in one hash <CODE>%c</CODE> and exporting only it. Here is an example of <CODE>My::Config</CODE>:
+
+<P>
+<PRE> package My::Config;
+ use strict;
+ use vars qw(%c);
+ %c = (
+ # All the configs go here
+ scalar_var => 5,
+
+ array_var => [
+ foo,
+ bar,
+ ],
+
+ hash_var => {
+ foo => 'Foo',
+ bar => 'BARRR',
+ },
+ );
+</PRE>
+<P>
+Now in packages that want to use the configuration variables I have either
+to use the fully qualified names like <CODE>$My::Config::test</CODE>, which I dislike or import them as described in the previous section. But
+hey, since we have only one variable to handle, we can make things even
+simpler and save the loading of the <CODE>Exporter.pm</CODE> package. We will use aliasing perl feature for exporting and saving the
+keystrokes:
+
+<P>
+<PRE> package My::HTML;
+ use strict;
+ # Global Configuration now aliased to global %c
+ use My::Config ();
+ use vars qw(%c);
+ *c = \%My::Config::c;
+
+ # Now you can access the variables from the My::Config
+ print $c{scalar_val};
+ print $c{array_val}[0];
+ print $c{hash_val}{foo};
+</PRE>
+<P>
+Of course <CODE>$c</CODE> is global everywhere you use it as described
+above, and if you change it somewhere it will affect any other packages you
+have aliased <CODE>$My::Config::c</CODE> to.
+
+<P>
+Note that aliases work either with global or <CODE>local()</CODE> vars - you cannot write:
+
+<P>
+<PRE> my *c = \%My::Config::c;
+</PRE>
+<P>
+Which is an error. But you can:
+
+<P>
+<PRE> local *c = \%My::Config::c;
+</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<P><A HREF="index.html">[Back to the main page]</A></P>
+
+<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
+</TR>
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
+ Written by <A HREF="help.html#author">Stas Bekman</A>.
+ <BR>Last Modified at 04/03/99
+ </FONT>
+ </B>
+ </TD>
+
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
+
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
+</TR>
+</TABLE></CENTER>
+
+</BODY>
+</HTML>
+
+
+<HR SIZE=6>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
<TITLE>mod_perl guide: Code Snippets</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -6737,6 +7545,8 @@
<LI><A HREF="#How_to_avoid_printing_the_header">How to avoid printing the header more than once.</A>
<LI><A HREF="#More_on_relative_paths">More on relative paths</A>
<LI><A HREF="#Watching_the_error_log_file_with">Watching the error_log file without telneting to the server.</A>
+ <LI><A HREF="#Accessing_variables_from_the_cal">Accessing variables from the caller's package</A>
+ <LI><A HREF="#Handling_cookies">Handling cookies</A>
</UL>
<!-- INDEX END -->
@@ -6748,7 +7558,7 @@
wish to change this behavior by setting in config file:
<P>
-<PRE> PerlSendHeader On
+<PRE> PerlSendHeader On
</PRE>
<P>
The safest bet is to use CGI.pm's <CODE>print header();</CODE> method (If you use this, you don't need the above setting)
@@ -6789,8 +7599,8 @@
this in the code or to use a nice <CODE>FindBin.pm</CODE> package.
<P>
-<PRE> use FindBin qw($Bin);
- use lib $Bin;
+<PRE> use FindBin qw($Bin);
+ use lib $Bin;
# or
open IN, "$Bin/foo.txt";
</PRE>
@@ -6851,7 +7661,6 @@
$q->end_form,
$q->hr;
-
print($q->b("$error_log doesn't exist!!!")),exit unless -e $error_log;
open LOG, "tail -$counts $error_log|" or die "Can't open tail on $error_log :$!\n";
@@ -6898,11 +7707,11 @@
? qq{<B><FONT COLOR="$colors{$type}">$context</FONT></B>}
: $context;
}
-
-
-=head1 Accessing variables from the caller's package
</PRE>
<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Accessing_variables_from_the_cal">Accessing variables from the caller's package</A></H1></CENTER>
+<P>
Sometimes you want to access some variables from the caller's package. One
way is to do:
@@ -6910,6 +7719,36 @@
<PRE> my $caller = caller;
print qq[$caller --- ${"${caller}::var"}];
</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Handling_cookies">Handling cookies</A></H1></CENTER>
+<P>
+Unless you use some well known modules like CGI.pm you can handle the
+cookies yourself.
+
+<P>
+Cookies come in the $ENV{HTTP_COOKIE} variable. You can print the raw
+cookie string as $ENV{HTTP_COOKIE}.
+
+<P>
+This is a fairly well-known bit of code to take cookie values and put them
+into a hash.
+
+<P>
+<PRE> sub getCookies {
+ # cookies are seperated by a semicolon and a space, this will
+ # split them and return a hash of cookies
+ local(@rawCookies) = split (/; /,$ENV{'HTTP_COOKIE'});
+ local(%cookies);
+
+ foreach(@rawCookies){
+ ($key, $val) = split (/=/,$_);
+ $cookies{$key} = $val;
+ }
+
+ return %cookies;
+ }
+</PRE>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P><A HREF="index.html">[Back to the main page]</A></P>
@@ -6924,7 +7763,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/16/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
@@ -7029,7 +7868,19 @@
<LI><A HREF="HTTP://www.modperl.com">www.modperl.com</A> - This is the home site
of The Apache Modules Book, a book about creating Web server modules using
-the Apache API, written by Lincoln Stein and Doug MacEachern.</LI>
+the Apache API, written by Lincoln Stein and Doug MacEachern.
+<P>
+Now you can purchase the book at your local bookstore or from the online dealer.
+O'Reilly lists this book as:
+<PRE>
+ Writing Apache Modules with Perl and C
+ By Lincoln Stein & Doug MacEachern
+ 1st Edition March 1999
+ 1-56592-567-X, Order Number: 567X
+ 746 pages, $34.95
+</PRE>
+
+</LI>
<LI><A HREF="http://perl.apache.org/dist/cgi_to_mod_perl.html">Quick guide
</A>for moving from CGI to mod_perl. </LI>
@@ -7154,7 +8005,7 @@
<TR ALIGN=CENTER VALIGN=TOP>
<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A HREF="help.html#author">Stas
Bekman</A>.<BR>
-Last Modified at 12/10/1998 </FONT></B></TD>
+Last Modified at 04/03/1998 </FONT></B></TD>
<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" BORDER=0 ALT="Mod Perl Icon" HEIGHT=59 WIDTH=150></A>
</TD>
1.9 +37 -29 modperl-site/guide/config.html
Index: config.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/config.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- config.html 1999/03/16 08:20:14 1.8
+++ config.html 1999/04/03 20:33:50 1.9
@@ -7,6 +7,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -87,9 +95,8 @@
# Apache::Registry mode
Alias /perl/ /usr/apps/myproject/cgi/
-</PRE>
-<P>
-<PRE> # Apache::PerlRun mode
+
+ # Apache::PerlRun mode
Alias /cgi-perl/ /usr/apps/myproject/cgi/
</PRE>
<P>
@@ -102,10 +109,10 @@
<STRONG>http://www.you.com/perl/test.pl</STRONG> will be mapped to
<STRONG>/usr/apps/myproject/cgi/test.pl</STRONG>. This means you can have all your CGIs located at the same place at
filesystem, and call the script in any of three modes simply by changing
-the directory name component of the URL (cgi-bin|perl|cgi-perl) - isn't
-that cool? (That's the configuration you see above - all three Aliases
+the directory name component of the URL (cgi-bin|perl|cgi-perl) - is not
+that cool? (That is the configuration you see above - all three Aliases
point to the same directory within your filesystem, but of course they can
-be different). If your script doesn't seem to be working while running
+be different). If your script does not seem to be working while running
under mod_perl, you can easily call the script in straight mod_cgi mode
without making any script changes (in most cases), but rather by changing
the URL you invoke it by.
@@ -121,10 +128,10 @@
<P>
Of course you can choose any other alias (you will use it later in
-http.conf), you can choose to use all three modes or only one of these
-(It's undesirable to run plain cgi-bin scripts from a mod_perl-enabled
-server - the price is too high, it's better to run these on plain Apache
-server. See <A HREF="././scenario.html#Making_a_strategic_decision">Real World scenario</A> for details.)
+http.conf), you can choose to use all three modes or only one of these (It
+is undesirable to run plain cgi-bin scripts from a mod_perl-enabled server
+- the price is too high, it is better to run these on plain Apache server.
+See <A HREF="././scenario.html#Making_a_strategic_decision">Real World scenario</A> for details.)
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -158,11 +165,11 @@
<P>
Remember the <STRONG>Alias</STRONG> from the section above? We must use the same Alias here, if you use
-Location that doesn't have the same Alias defined in srm.conf, the server
+Location that does not have the same Alias defined in srm.conf, the server
will fail to locate the script in the filesystem. (We're talking about
-script execution here -- there are cases where Location is something that's
-being executed by the server itself, without having the corresponding file,
-like <A HREF="#perl_status">perl-status</A>.)
+script execution here -- there are cases where Location is something that
+is being executed by the server itself, without having the corresponding
+file, like <A HREF="#perl_status">perl-status</A>.)
<P>
Note that sometimes you will have to add : PerlModule Apache::Registry
@@ -177,7 +184,7 @@
with mod_perl
<P>
-Here's a similar location configuration for Apache::PerlRun. (More about
+Here is a similar location configuration for Apache::PerlRun. (More about
<A HREF="././porting.html#Apache_PerlRun_a_closer_look">Apache::PerlRun</A>)
<P>
@@ -240,12 +247,13 @@
# (but not to import) its autoloaded methods.
use CGI ();
CGI->compile(':all');
-
+</PRE>
+<P>
Note that starting with CGI::VERSION 2.46, the recommended method to
precompile the code in CGI.pm is:
-</PRE>
+
<P>
-<PRE> use CGI qw(-compile :all);
+<PRE> use CGI qw(-compile :all);
</PRE>
<P>
But the old method is still available for backword compatibility.
@@ -263,7 +271,7 @@
on server restart, add:
<P>
-<PRE> PerlFreshRestart On
+<PRE> PerlFreshRestart On
</PRE>
<P>
Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
@@ -317,7 +325,7 @@
can then walk and grind the names and values of Perl variables/structures
through the Apache core configuration gears. Most of the configurations
directives can be represented as scalars (<STRONG>$scalar</STRONG>) or lists (<STRONG>@list</STRONG>). An <CODE>@List</CODE> inside these sections is simply converted into a space delimited string for
-you inside. Here's an example:
+you inside. Here is an example:
<P>
<PRE> #httpd.conf
@@ -356,12 +364,10 @@
<P>
<PRE> push @Redirect, "/foo", "<A HREF="http://www.foo.com/"">http://www.foo.com/"</A>;;
-</PRE>
-<P>
-<PRE> push @Redirect, "/imdb", "<A HREF="http://www.imdb.com/"">http://www.imdb.com/"</A>;;
-</PRE>
-<P>
-<PRE> push @Redirect, [qw(temp "/here" "<A HREF="http://www.there.com"">http://www.there.com"</A>;)];
+
+ push @Redirect, "/imdb", "<A HREF="http://www.imdb.com/"">http://www.imdb.com/"</A>;;
+
+ push @Redirect, [qw(temp "/here" "<A HREF="http://www.there.com"">http://www.there.com"</A>;)];
</PRE>
<P>
Other section counterparts include <STRONG>%VirtualHost</STRONG>,
@@ -402,8 +408,8 @@
Now you may run <STRONG>perl -cx httpd.conf</STRONG>.
<P>
-To configure this feature build with
-<STRONG>perl Makefile.PL PERL_SECTIONS=1' </STRONG>
+To configure this feature build with <STRONG>perl Makefile.PL
+PERL_SECTIONS=1' </STRONG>
@@ -455,6 +461,8 @@
variable in a startup file (PerlRequire):
<STRONG>$Apache::Registry::NameWithVirtualHost = 1;</STRONG>
+
+
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P><A HREF="index.html">[Back to the main page]</A></P>
@@ -469,7 +477,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/15/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
1.10 +68 -67 modperl-site/guide/control.html
Index: control.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/control.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- control.html 1999/03/16 08:20:14 1.9
+++ control.html 1999/04/03 20:33:50 1.10
@@ -7,6 +7,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -235,35 +243,33 @@
Crontab entry:
<P>
-0,30 * * * * /path/to/the/apache.watchdog >/dev/null 2>&1
-
+<PRE> 0,30 * * * * /path/to/the/apache.watchdog >/dev/null 2>&1
+</PRE>
<P>
The script:
<P>
<PRE> #!/bin/sh
-
+
# this script is a watchdog to see whether the server is online
# It tries to restart the server if it's
# down and sends an email alert to admin
-</PRE>
-<P>
-<PRE> # admin's email
+
+ # admin's email
EMAIL=webmaster@somewhere.far
#EMAIL=root@localhost
-
+
# the path to your PID file
PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid
-
+
# the path to your httpd binary, including options if necessary
HTTPD=/usr/apps/sbin/httpd_perl/httpd_perl
-
+
# check for pidfile
if [ -f $PIDFILE ] ; then
PID=`cat $PIDFILE`
-</PRE>
-<P>
-<PRE> if kill -0 $PID; then
+
+ if kill -0 $PID; then
STATUS="httpd (pid $PID) running"
RUNNING=1
else
@@ -274,7 +280,7 @@
STATUS="httpd (no pid file) not running"
RUNNING=0
fi
-
+
if [ $RUNNING -eq 0 ]; then
echo "$0 $ARG: httpd not running, trying to start"
if $HTTPD ; then
@@ -336,20 +342,17 @@
my $message = ($status == 0)
? "Server was down and successfully restarted!"
: "Server is down. Can't restart.";
-</PRE>
-<P>
-<PRE> my $subject = ($status == 0)
+
+ my $subject = ($status == 0)
? "Attention! Webserver restarted"
: "Attention! Webserver is down. can't restart";
-</PRE>
-<P>
-<PRE> # email the monitoring person
+
+ # email the monitoring person
my $to = $monitor_email;
my $from = $monitor_email;
send_mail($from,$to,$subject,$message);
-</PRE>
-<P>
-<PRE> # input: URL to check
+
+ # input: URL to check
# output: 1 if success, o for fail
#######################
sub checkurl{
@@ -369,9 +372,8 @@
#######################
sub send_mail{
my($from,$to,$subject,$messagebody) = @_;
-</PRE>
-<P>
-<PRE> open MAIL, "|$mail_program"
+
+ open MAIL, "|$mail_program"
or die "Can't open a pipe to a $mail_program :$!\n";
print MAIL <<__END_OF_MAIL__;
@@ -453,16 +455,25 @@
<PRE> % http_perl -Dsbekman
</PRE>
<P>
-At the end of the httpd.conf I wrote: # Personal development Server for
-sbekman # sbekman use the server running on port 8000 <IfDefine
-sbekman> Port 8000 PidFile
-/usr/apps/var/httpd_perl/run/httpd.pid.sbekman ErrorLog
-/usr/apps/var/httpd_perl/logs/error_log.sbekman Timeout 300 KeepAlive On
-MinSpareServers 2 MaxSpareServers 2 StartServers 1 MaxClients 3
-MaxRequestsPerChild 15 </IfDefine>
+At the end of the httpd.conf I wrote:
<P>
-<PRE> # Personal development Server for userfoo
+<PRE> # Personal development Server for sbekman
+ # sbekman use the server running on port 8000
+ <IfDefine sbekman>
+ Port 8000
+ PidFile /usr/apps/var/httpd_perl/run/httpd.pid.sbekman
+ ErrorLog /usr/apps/var/httpd_perl/logs/error_log.sbekman
+ Timeout 300
+ KeepAlive On
+ MinSpareServers 2
+ MaxSpareServers 2
+ StartServers 1
+ MaxClients 3
+ MaxRequestsPerChild 15
+ </IfDefine>
+
+ # Personal development Server for userfoo
# userfoo use the server running on port 8001
<IfDefine userfoo>
Port 8001
@@ -616,9 +627,8 @@
# we want to make a complete emulation, so we must remove the
# user's environment
@INC = ();
-</PRE>
-<P>
-<PRE> # local perl libs
+
+ # local perl libs
push @INC, ("$basedir/lib/perl5/5.00502/aix",
"$basedir/lib/perl5/5.00502",
"$basedir/lib/perl5/site_perl/5.005/aix",
@@ -727,24 +737,19 @@
<PRE> #!/usr/bin/perl -Tw
use strict;
use File::Basename;
-</PRE>
-<P>
-<PRE> $ENV{PATH} = "/usr/ucb:/bin:/usr/bin";
-</PRE>
-<P>
-<PRE> my $ROOT = "/WWW/apache"; # names are relative to this
+
+ $ENV{PATH} = "/usr/ucb:/bin:/usr/bin";
+
+ my $ROOT = "/WWW/apache"; # names are relative to this
my $CONF = "$ROOT/conf/httpd.conf"; # master conf
my $MIDNIGHT = "MIDNIGHT"; # name of program in each logdir
-</PRE>
-<P>
-<PRE> my ($user_id, $group_id, $pidfile); # will be set during parse of conf
+
+ my ($user_id, $group_id, $pidfile); # will be set during parse of conf
die "not running as root" if $>;
-</PRE>
-<P>
-<PRE> chdir $ROOT or die "Cannot chdir $ROOT: $!";
-</PRE>
-<P>
-<PRE> my %midnights;
+
+ chdir $ROOT or die "Cannot chdir $ROOT: $!";
+
+ my %midnights;
open CONF, "<$CONF" or die "Cannot open $CONF: $!";
while (<CONF>) {
if (/^User (\w+)/i) {
@@ -765,22 +770,20 @@
$midnights{$midnight}++;
}
close CONF;
-</PRE>
-<P>
-<PRE> die "missing User definition" unless defined $user_id;
+
+ die "missing User definition" unless defined $user_id;
die "missing Group definition" unless defined $group_id;
die "missing PidFile definition" unless defined $pidfile;
-</PRE>
-<P>
-<PRE> open PID, $pidfile or die "Cannot open $pidfile: $!";
+
+ open PID, $pidfile or die "Cannot open $pidfile: $!";
<PID> =~ /(\d+)/;
my $httpd_pid = $1;
close PID;
die "missing pid definition" unless defined $httpd_pid and $httpd_pid;
kill 0, $httpd_pid or die "cannot find pid $httpd_pid: $!";
-</PRE>
-<P>
-<PRE> for (sort keys %midnights) {
+
+
+ for (sort keys %midnights) {
defined(my $pid = fork) or die "cannot fork: $!";
if ($pid) {
## parent:
@@ -794,9 +797,8 @@
die "cannot exec $MIDNIGHT: $!";
}
}
-</PRE>
-<P>
-<PRE> kill 1, $httpd_pid or die "Cannot sighup $httpd_pid: $!";
+
+ kill 1, $httpd_pid or die "Cannot sighup $httpd_pid: $!";
</PRE>
<P>
And then individual MIDNIGHT scripts can look like this:
@@ -804,9 +806,8 @@
<P>
<PRE> #!/usr/bin/perl -Tw
use strict;
-</PRE>
-<P>
-<PRE> die "bad guy" unless getpwuid($<) =~ /^(root|nobody)$/;
+
+ die "bad guy" unless getpwuid($<) =~ /^(root|nobody)$/;
my @LOGFILES = qw(access_log error_log);
umask 0;
$^I = ".".time;
@@ -878,7 +879,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/16/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
1.8 +9 -1 modperl-site/guide/debug.html
Index: debug.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/debug.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- debug.html 1999/03/16 08:20:16 1.7
+++ debug.html 1999/04/03 20:33:50 1.8
@@ -7,6 +7,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -100,7 +108,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/13/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
1.2 +695 -631 modperl-site/guide/guide.tar.gz
<<Binary file>>
1.8 +15 -2 modperl-site/guide/help.html
Index: help.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/help.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- help.html 1999/01/23 18:06:54 1.7
+++ help.html 1999/04/03 20:33:51 1.8
@@ -101,9 +101,22 @@
<LI><A HREF="HTTP://www.modperl.com">www.modperl.com</A> - This is the home site
of The Apache Modules Book, a book about creating Web server modules using
-the Apache API, written by Lincoln Stein and Doug MacEachern.</LI>
+the Apache API, written by Lincoln Stein and Doug MacEachern.
+<P>
+Now you can purchase the book at your local bookstore or from the online dealer.
+O'Reilly lists this book as:
+<PRE>
+ Writing Apache Modules with Perl and C
+ By Lincoln Stein & Doug MacEachern
+ 1st Edition March 1999
+ 1-56592-567-X, Order Number: 567X
+ 746 pages, $34.95
+</PRE>
+</LI>
+
+
<LI><A HREF="http://perl.apache.org/dist/cgi_to_mod_perl.html">Quick guide
</A>for moving from CGI to mod_perl. </LI>
@@ -267,7 +280,7 @@
<TR ALIGN=CENTER VALIGN=TOP>
<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A HREF="help.html#author">Stas
Bekman</A>.<BR>
-Last Modified at 12/10/1998 </FONT></B></TD>
+Last Modified at 04/03/1998 </FONT></B></TD>
<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" BORDER=0 ALT="Mod Perl Icon" HEIGHT=59 WIDTH=150></A>
1.10 +12 -5 modperl-site/guide/index.html
Index: index.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/index.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- index.html 1999/03/16 08:20:19 1.9
+++ index.html 1999/04/03 20:33:51 1.10
@@ -15,9 +15,8 @@
to your perl cgi-bin scripts.</B></P></CENTER>
-<CENTER><P><B>Version 1.07 Mar, 16 1999</B></P></CENTER>
-
-
+<CENTER><P><B>Version 1.08 Apr, 3 1999</B></P></CENTER>
+
<P>
<HR WIDTH="100%"></P>
@@ -41,6 +40,9 @@
<LI><A HREF="control.html">Server Controlling and Monitoring</A></LI>
+<LI><A HREF="frequent.html">Frequent mod_perl problems</A></LI>
+
+
<LI><A HREF="porting.html">CGI to mod_perl Porting. mod_perl Coding guidelines.</A></LI>
@@ -59,6 +61,9 @@
<LI><A HREF="debug.html">Code Debugging techniques</A></LI>
+<LI><A HREF="perl.html">Perl Reference</A></LI>
+
+
<LI><A HREF="snippets.html">Code Snippets</A></LI>
@@ -74,7 +79,9 @@
<LI><A HREF="#search">Search perl.apache.org along with this guide</A></LI>
-<LI><A HREF="guide.tar.gz">Download as one file</A></LI>
+<LI>Download all files <A HREF="guide.tar.gz">guide.tar.gz</A>
+or sources and build scripts
+<A HREF="guide-src.tar.gz">guide-src.tar.gz</A></LI>
</UL>
@@ -117,7 +124,7 @@
<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A
HREF="help.html#author">Stas Bekman</A>.<BR> Last Modified at
-03/16/1999 </FONT></B></TD>
+04/03/1999 </FONT></B></TD>
<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" BORDER=0 ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
1.7 +73 -35 modperl-site/guide/intro.html
Index: intro.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/intro.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- intro.html 1999/03/16 08:20:20 1.6
+++ intro.html 1999/04/03 20:33:51 1.7
@@ -175,46 +175,84 @@
have used, please tell me and I'll add it for you.<P>
-<P> Credits go to ( alphabetically sorted );
+<P>Major contributors:
+
+
+<UL>
+ <LI><B>Doug MacEachern</B> - a big part of this guide is build upon his
+ email replies to the users' questions
+
+
+ <LI><B>Frank Cringle</B> - whose mod_perl FAQ lays in the basis of the guide.
+
+
+ <LI><B>Vivek Khera</B> - for his mod_perl performance tuning guide.
+
+
+ <LI><B>Steve Reppucci</B> - 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 :)
+
+
+ <LI><B>Eric Cholet</B> - who wrote complete sections for the guide, and
+ pointed out the errors the guide carried away.
+
+
+ <LI><B>Ken Williams</B> - who reviewed a lot of stuff in the guide, and
+ many snippets from his emails are included in the guide.
+
+
+</UL>
+
+
+<P> Credits go of course to ( alphabetically sorted ):
<UL>
- <LI>Andreas J. Koenig
- <LI>Ask Bjoern Hansen
- <LI>Brian Moseley
- <LI>Chad K. Lewis
- <LI>David Landgren
- <LI>Doug Bagley
- <LI>Doug MacEachern
- <LI>Edmund Mergl
- <LI>Eric Cholet
- <LI>Evan A. Zacks
- <LI>Frank Cringle
- <LI>G.Richter
- <LI>Gunther Birznieks
- <LI>Howard Jones
- <LI>Jeff Baker
- <LI>Jeff Rowe
- <LI>Jon Orwant
- <LI>Ken Williams
- <LI>Leslie Mikesell
- <LI>Lincoln Stein
- <LI>Mike Fletcher
- <LI>Nancy Lin
- <LI>Nathan Torkington
- <LI>Ralf Engelschall
- <LI>Randal Schwartz
- <LI>Steve Reppucci
- <LI>Vivek Khera
+ <LI><B>Andreas J. Koenig</B>
+ <LI><B>Ask Bjoern Hansen</B>
+ <LI><B>Brian Moseley </B>
+ <LI><B>Chad K. Lewis</B>
+ <LI><B>David Landgren</B>
+ <LI><B>Doug Bagley</B>
+ <LI><B>Ed Park</B>
+ <LI><B>Edmund Mergl</B>
+ <LI><B>Evan A. Zacks</B>
+ <LI><B>G.Richter</B>
+ <LI><B>Garr Updegraff</B>
+ <LI><B>Gunther Birznieks</B>
+ <LI><B>Henrique Pantarotto</B>
+ <LI><B>Howard Jones</B>
+ <LI><B>Jeff Baker</B>
+ <LI><B>Jeff Rowe</B>
+ <LI><B>Jon Orwant</B>
+ <LI><B>Jonathan Peterson</B>
+ <LI><B>Leslie Mikesell</B>
+ <LI><B>Lincoln Stein</B>
+ <LI><B>Mark Mills</B>
+ <LI><B>Marshall Dudley</B>
+ <LI><B>Mike Fletcher</B>
+ <LI><B>Nancy Lin</B>
+ <LI><B>Nathan Torkington</B>
+ <LI><B>Nathan Vonnahme</B>
+ <LI><B>Perrin Harkins</B>
+ <LI><B>Peter Skov</B>
+ <LI><B>Radu Greab</B>
+ <LI><B>Ralf Engelschall</B>
+ <LI><B>Randal Schwartz</B>
+ <LI><B>Richard Dice</B>
+ <LI><B>Tzvetan Stoyanov</B>
+ <LI><B>Ulrich Pfeifer</B>
<LI>
<LI>Did I miss you? Tell me!
</UL>
</P>
-<P>I want to thank all the people who donated their time and efforts to
-made this amazing idea of mod_perl to become 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 the bugs and advocate mod_perl around the world.</P>
+<P>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 the bugs and advocate mod_perl around
+the world.</P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
@@ -236,8 +274,8 @@
Modified at 03/16/1999 </FONT></B></TD>
-<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" BORDER=0 ALT="Mod Perl Icon" HEIGHT=59 WIDTH=150></A>
-</TD>
+<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg"
+BORDER=0 ALT="Mod Perl Icon" HEIGHT=59 WIDTH=150></A> </TD>
<TD><FONT SIZE=-2>Use of the Camel for Perl is <BR>
1.8 +281 -186 modperl-site/guide/obvious.html
Index: obvious.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/obvious.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- obvious.html 1999/01/23 18:06:54 1.7
+++ obvious.html 1999/04/03 20:33:52 1.8
@@ -1,25 +1,40 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: What is obvious for others but not for you</TITLE>
+ <TITLE>mod_perl guide: Things obvious to others, but not to you</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-What is obvious for others but not for you</H1>
+Things obvious to others, but not to you</H1>
<HR WIDTH="100%">
<!-- INDEX BEGIN -->
<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Coverage">Coverage</A>
- <LI><A HREF="#my_scoped_variable_in_the_nest">my() scoped variable in the nested subroutine</A>
+ <LI><A HREF="#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>
+ <UL>
+
+ <LI><A HREF="#The_poison">The poison</A>
+ <LI><A HREF="#The_diagnosis">The diagnosis</A>
+ <LI><A HREF="#The_remedy">The remedy</A>
+ </UL>
+
<LI><A HREF="#Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A>
<UL>
@@ -32,6 +47,7 @@
<LI><A HREF="#Debugging_your_code_in_Single_Se">Debugging your code in Single Server Mode</A>
<LI><A HREF="#_M_and_other_time_file_tests_u">-M and other time() file tests under mod_perl</A>
<LI><A HREF="#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>
+ <LI><A HREF="#Handling_the_server_timeout_case">Handling the server timeout cases</A>
<LI><A HREF="#Where_do_the_warnings_errors_go_">Where do the warnings/errors go?</A>
</UL>
<!-- INDEX END -->
@@ -40,111 +56,135 @@
<P>
<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
<P>
-This document describes ``special'' traps of running your plain cgis under
-Apache::Registry and Apache::PerlRun.
+This document describes ``special'' traps you may encounter when running
+your plain CGIs under Apache::Registry and Apache::PerlRun.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="my_scoped_variable_in_the_nest">my() scoped variable in the nested subroutine</A></H1></CENTER>
+<CENTER><H1><A NAME="my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A></H1></CENTER>
<P>
-When you write a code like:
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="The_poison">The poison</A></H2></CENTER>
+<P>
+In a non modperl script (standalone or CGI), there is no problem writing
+code like this:
<P>
-<PRE> #!perl -w
- my $x;
- sub y {
- $x
+<PRE> use CGI qw/param/;
+ my $x = param('x');
+ sub printit {
+ print "$x\n";
}
</PRE>
<P>
-there is no problem. But when you write:
+However, the script is run under Apache::Registry, it will in fact be
+repackaged into something like this:
<P>
-<PRE> #!perl -w
- sub x {
- my $x;
- sub y {
- $x
- }
+<PRE> package $mangled_package_name;
+ sub handler {
+ #line1 $original_filename
+ use CGI qw/param/;
+ my $x = param('x');
+ sub printit {
+ print "$x\n";
}
+ }
</PRE>
<P>
-it produces this warning:
+Now printit is an inner named subroutine. Because it is referencing a
+lexical variable from an enclosing scope, a closure is created.
<P>
-<PRE> Value of $x will not stay shared at - line 5.
-</PRE>
-<P>
-The tone of this message is definite because the code *will* fail if
-<CODE>&x</CODE> is called more than once. NOTE: Subroutines defined
-inside BEGIN{} and END{} cannot trigger this message, since each BEGIN{}
-and END{} is known to be called exactly once. (To understand why, read
-about the closures at perlref or perlfaq 13.12)
+The first time the script is run, the correct value of <CODE>$x</CODE> will
+be printed. However on subsequent runs, printit will retain the initial
+value of <CODE>$x</CODE> -- not what you want.
<P>
-Also, this slightly different code:
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="The_diagnosis">The diagnosis</A></H2></CENTER>
+<P>
+Always use -w (or/and PerlWarn ON)! Perl will then emit a warning like:
<P>
-<PRE> #!perl -w
- sub x {
- my $x;
- sub y {
- sub { $x }
- }
- }
+<PRE> Value of $x will not stay shared at - line 5.
</PRE>
<P>
-produces this warning:
+NOTE: Subroutines defined inside <STRONG>BEGIN{}</STRONG> and <STRONG>END{}</STRONG> cannot trigger this message, since each <STRONG>BEGIN{}</STRONG> and <STRONG>END{}</STRONG> is defined to be called exactly once. (To understand why, read about the
+closures at perlref or perlfaq 13.12)
<P>
-<PRE> Value of $x may be unavailable at - line 5.
+PERLDIAG manpage says:
+
+<P>
+<PRE> An inner (nested) named subroutine is referencing a lexical variable
+ defined in an outer subroutine.
</PRE>
<P>
-This message is less definite because the code can work correctly, if
-<CODE>&y</CODE> is called only from inside &x.
+When the inner subroutine is called, it will probably see the value of the
+outer subroutine's variable as it was before and during the *first* call to
+the outer subroutine; in this case, after the first call to the outer
+subroutine is complete, the inner and outer subroutines will no longer
+share a common value for the variable. In other words, the variable will no
+longer be shared.
<P>
-(this was partially extracted from perl5-porters post)
+Check your code by running Apache in single-child mode (httpd -X). Since
+the value of a my variable retain its initial value <CODE>per
+child process</CODE>, the closure problem can be difficult to track down in multi-user mode. It
+will appear to work fine until you have cycled through all the httpd
+children.
<P>
-Now hold on, you ask what it has to do with your cgi script?
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="The_remedy">The remedy</A></H2></CENTER>
<P>
-That's exactly the point that is not obvious. Apache::Registry wraps your
-code into a sub! You heard it right. So all your code's subs are nested.
-And while you don't see it, your code actually is the same as the simple
-snippet above. And all the behavior described above applies to your code!
+If a variable needs file scope, use a global variable:
<P>
-A solution?
+<PRE> use vars qw/$x/;
+ use CGI qw/param/;
+ $x = param('x');
+ sub printit {
+ print "$x\n";
+ }
+</PRE>
+<P>
+You can safely use a <CODE>my()</CODE> scoped variable if its value is constant:
<P>
-<PRE> use vars qw($x $a); at the top of your code
+<PRE> use vars qw/$x/;
+ use CGI qw/param/;
+ $x = param('x');
+ my $y = 5;
+ sub printit {
+ print "$x, $y\n";
+ }
</PRE>
<P>
Also see the clarification of <CODE>my()</CODE> vs. <CODE>use vars</CODE> - Ken Williams writes:
<P>
-<PRE> Yes, there's quite a bit of difference! With use vars(), you're
- making an entry in the symbol table, and you're telling the compiler
- that you're going to be referencing that entry without an explicit
- package name.
+<PRE> Yes, there is quite a bit of difference! With use vars(), you are
+ making an entry in the symbol table, and you are telling the
+ compiler that you are going to be referencing that entry without an
+ explicit package name.
</PRE>
<P>
-<PRE> With my(), NO ENTRY IS PUT IN THE SYMBOL TABLE. The compiler figures
- out _at_ _compile_time_ which my() variables (i.e. lexical variables)
- are the same as each other, and once you hit execute time you can't go
- looking those variables up in the symbol table.
+<PRE> With my(), NO ENTRY IS PUT IN THE SYMBOL TABLE. The compiler
+ figures out _at_ _compile_time_ which my() variables (i.e. lexical
+ variables) are the same as each other, and once you hit execute time
+ you can not go looking those variables up in the symbol table.
</PRE>
<P>
And <CODE>my()</CODE> vs. <CODE>local()</CODE> - Randal Schwartz writes:
<P>
-<PRE> local() creates a temporal-limited package-based scalar, array, hash,
- or glob -- when the scope of definition is exited at runtime, the
- previous value (if any) is restored. References to such a variable
- are *also* global... only the value changes. (Aside: that's what
- causes variable suicide. :)
+<PRE> local() creates a temporal-limited package-based scalar, array,
+ hash, or glob -- when the scope of definition is exited at runtime,
+ the previous value (if any) is restored. References to such a
+ variable are *also* global... only the value changes. (Aside: that
+ is what causes variable suicide. :)
</PRE>
<P>
<PRE> my() creates a lexically-limited non-package-based scalar, array, or
@@ -156,24 +196,28 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A></H1></CENTER>
<P>
-When you develop your plain cgi scripts you just change the code, and rerun
-the cgi in your browser. Since the script wasn't staying in the memory, the
-next time you call it - server recompile it from scratch so all the changes
-you apply are immediately taking the expected effect.
-
-<P>
-The situation is different with Apache::Registry. Since the whole idea was
-to get the maximum performance from the server. By default server wouldn't
-spend the time to go and check whether the code has been changed. It
-assumes that it wasn't, thus saving a few millisecs to stat the file (And
-if you have many of them it takes more time). The only check that is being
-done is whether your main script has been changed. So if you have only one
-script that doesn't require or use other Perl Modules (packages) there is
-nothing new about it. The files you <CODE>use()</CODE> or
-<CODE>require()</CODE> aren't being checked at all. So what are the
-workarounds?
+When you develop plain CGI scripts, you can just change the code, and rerun
+the CGI from your browser. Since the script isn't cached in memory, the
+next time you call it the server starts up a new perl process, which
+recompiles it from scratch. The effects of any modifications you've applied
+are immediately present.
+
+<P>
+The situation is different with Apache::Registry, since the whole idea is
+to get maximum performance from the server. By default, the server won't
+spend the time to check whether any included library modules have been
+changed. It assumes that they weren't, thus saving a few millisecs to stat
+the source file (multiplied by however many modules/libraries you are
+<STRONG>use</STRONG>/<STRONG>require</STRONG>-ing in your script.) The only check that is being done is whether your
+main script has been changed. So if you have only one script that doesn't <STRONG>use</STRONG> (or <STRONG>require</STRONG>) other perl modules (or packages), there is nothing new about it. If
+however, you are developing a script that includes other modules, the files
+you <STRONG>use()</STRONG> or <STRONG>require()</STRONG> aren't being checked to see if they have been modified.
<P>
+Acknowledging this, how do we get our modperl-enabled server to recognize
+changes in any library modules? Well, there are a couple of techniques:
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Restarting_the_server">Restarting the server</A></H2></CENTER>
<P>
@@ -183,33 +227,32 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Using_Apache_StatINC">Using Apache::StatINC</A></H2></CENTER>
<P>
-After restarting the server for about 100 times you will be tired and will
-look for another solutions. Here comes for a help the Apache::StatINC
-module.
+After restarting the server about 100 times, you will be tired and will
+look for another solutions. Help comes from the Apache::StatINC module.
<P>
Read its pod pages, but beware of the following note: Only the modules
-located in <CODE>@INC</CODE> are being reloaded on change, and you can
-change the <CODE>@INC</CODE> only before the server has been started.
-Whatever you do in you scripts/modules which are being
-<CODE>required()</CODE> after the server startup will not take an effect on
-@INC. When you do use lib <CODE>qw(foo/bar);</CODE> the <CODE>@INC</CODE>
-is being changed only for the time the code is being parsed. When it's over
-the <CODE>@INC</CODE> is being reset to its original value. To make sure
-that you have set a correct <CODE>@INC</CODE> fetch <A
+located in <STRONG>@INC</STRONG> are being reloaded on change, and you can change the <STRONG>@INC</STRONG> only before the server has been started. Whatever you do in your
+scripts/modules which are being <CODE>required()</CODE> after the server
+startup will not have any effect on <STRONG>@INC</STRONG>.
+
+<P>
+When you do <STRONG>use lib qw(foo/bar);</STRONG>, the <STRONG>@INC</STRONG> is being changed only for the time the code is being parsed. When it's over
+the <STRONG>@INC</STRONG> is being reset to its original value. To make sure that you have set a
+correct <STRONG>@INC</STRONG> fetch <A
HREF="http://your.perl.server/perl-status?inc">http://your.perl.server/perl-status?inc</A>
and watch the bottom of the page. (I assume you have configured the
-<Location /perl-status> section in httpd.conf as modperl docs shows.
+<Location /perl-status> section in httpd.conf as the mod_perl docs
+show.)
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Reloading_only_specific_files">Reloading only specific files</A></H2></CENTER>
<P>
-However checking all the Modules in <CODE>%INC</CODE> can add a some (big?)
-overhead to server response times, and you certainly wouldn't want
-Apache::StatINC module to be enabled in your production site's
-configuration. But sometimes you want to have some Configuration file
-(module) to be reloaded without restarting the whole server. For this you
+Checking all the Modules in <STRONG>%INC</STRONG> can add some (large?) overhead to server response times, and you certainly
+wouldn't want Apache::StatINC module to be enabled in your production
+site's configuration. But sometimes you want to have some Configuration
+file (module) be reloaded without restarting the whole server. For this you
will have to add something like this in your code:
<P>
@@ -259,10 +302,11 @@
}
</PRE>
<P>
-You will want to add debug printings to test this code in your application.
+You may want to add debug print statements to test this code in your
+application.
<P>
-Read also use versus require article for more info.
+Read the ``use versus require'' article for more info.
(http://www.perl.com/CPAN-local/doc/FMTEYEWTK/use_vs_require)
<P>
@@ -272,9 +316,9 @@
When using a regular expression that contains an interpolated Perl
variable, if it is known that the variable (or variables) will not vary
during the execution of the program, a standard optimization technique
-consists of adding the o modifier to the regexp pattern, to direct the
-compiler to build the internal table once, for the entire lifetime of the
-script, rather than every time the pattern is executed. Consider:
+consists of adding the <STRONG>/o</STRONG> modifier to the regexp pattern. This directs the compiler to build the
+internal table once, for the entire lifetime of the script, rather than
+every time the pattern is executed. Consider:
<P>
<PRE> my $pat = '^foo$'; # likely to be input from an HTML form field
@@ -283,13 +327,14 @@
}
</PRE>
<P>
-This is usually a big win in loops over lists, or when using grep or map.
+This is usually a big win in loops over lists, or when using
+<STRONG>grep</STRONG> or <STRONG>map</STRONG>.
<P>
In long-lived mod_perl scripts, however, this can pose a problem if the
variable changes according to the invocation. The first invocation of a
-fresh httpd child will compile the table and perform the search correctly,
-however, all subsequent uses by the httpd child will continue to match the
+fresh httpd child will compile the regex and perform the search correctly.
+However, all subsequent uses by the httpd child will continue to match the
original pattern, regardless of the current contents of the Perl variables
the pattern is dependent on. Your script will appear broken.
@@ -297,9 +342,9 @@
There are two solutions to this problem.
<P>
-The first is to use eval q//, to force the code to be evaluated each time.
-Just make sure that the eval block covers the entire loop of processing,
-and not just the pattern match itself.
+The first is to use <STRONG>eval q//</STRONG>, to force the code to be evaluated each time. Just make sure that the eval
+block covers the entire loop of processing, and not just the pattern match
+itself.
<P>
The above code fragment would be rewritten as:
@@ -313,7 +358,7 @@
}
</PRE>
<P>
-Just saying
+Just saying:
<P>
<PRE> eval q{ print if /$pat/o; };
@@ -322,11 +367,11 @@
is going to be a horribly expensive proposition.
<P>
-You use this approach if you require more than one pattern match operator
-in a given section of code. If the section contains only one operator (be
-it an m// or s///), you can rely on the property of the null pattern, that
-reuses the last pattern seen. This leads to the second solution, which also
-eliminates the use of eval.
+You can use this approach if you require more than one pattern match
+operator in a given section of code. If the section contains only one
+operator (be it an <STRONG>m//</STRONG> or <STRONG>s///</STRONG>), you can rely on the property of the null pattern, that reuses the last
+pattern seen. This leads to the second solution, which also eliminates the
+use of eval.
<P>
The above code fragment becomes:
@@ -341,8 +386,8 @@
<P>
The only gotcha is that the dummy match that boots the regular expression
engine must absolutely, positively succeed, otherwise the pattern will not
-be cached, and the // will match everything. If you can't count on fixed
-text to ensure the match succeeds, you have two possibilities.
+be cached, and the <STRONG>//</STRONG> will match everything. If you can't count on fixed text to ensure the match
+succeeds, you have two possibilities.
<P>
If you can guarantee that the pattern variable contains no meta-characters
@@ -412,12 +457,12 @@
Running in httpd -X mode. (good only for testing during development phase).
<P>
-You want to test your application that it handles correctly the global
-variables (if you have such - The less you have them the better, but
-sometimes you just can't without them). It's hard to test with multiply
-servers serving your cgi since each child has a different value for its
-global variables. Imagine that you have a <CODE>random()</CODE> sub that
-returns a random number and you have the following script.
+You want to test that your application correctly handles global variables
+(if you have any - the less you have of them the better, but sometimes you
+just can't without them). It's hard to test with multiple servers serving
+your cgi since each child has a different value for its global variables.
+Imagine that you have a <CODE>random()</CODE> sub that returns a random
+number and you have the following script.
<P>
<PRE> use vars qw($num);
@@ -425,46 +470,52 @@
print ++$num;
</PRE>
<P>
-This script initializes the <CODE>$num</CODE> with random value, then it
-increments on each request and print it out. Running this script in
-multiply server environment will result in something like 1,9,4,19 (number
-per reload), since ``each'' time your script will be served by a different
-child. (On some OSes parent process assign all the requests to the same
-child process if all of the children are idle... AIX...). But if you run in
-httpd -X single server mode you will get 2,3,4,5... (taken that the
-<CODE>random()</CODE> returned 1 at the first call)
+This script initializes the variable <STRONG>$num</STRONG> with a random value, then increments it on each request and prints it out.
+Running this script in multiple server environments will result in
+something like 1,9,4,19 (number per reload), since each time your script
+will be served by a different child. (On some OSes, the parent httpd
+process will assign all of the requests to the same child process if all of
+the children are idle... AIX...). But if you run in httpd -X single server
+mode you will get 2,3,4,5... (taken that the <CODE>random()</CODE> returned
+1 at the first call)
<P>
-But don't get too obsessive with this mode, since working only in single
+But do not get too obsessive with this mode, since working only in single
server mode sometimes hides problems that show up when you switch to multi
-server mode. Assume the following code:
+server mode. Consider an application that allows you to change the
+configuration at run time.
<P>
-Application that allows you to change the configuration at the run time.
Let's say the script produces a form to change the background color of the
-page. (It's not a good idea but for the sake of potential problem
-presentation we will assume that we don't write down the change on the
-disk). So you have typed in a new color , and as a respond you print back
+page. It's not a good design, but for the sake of demonstrating the
+potential problem, we will assume that our script doesn't write the changed
+background color to the disk, but simply changes it in memory.
+
+<P>
+So you have typed in a new color, and in response, your script prints back
the html with a new color - you think that's it! It was so simple. And if
you keep running in single server mode you will never notice that you have
-a problem... If you run the same code in the multi server environment ,
-after you submit the color change you will get the result as expected, but
-when you will call the same URL again (not reload!) chances are that you
-will get back the old color, since except the child who processed the color
-change request no one knows about their global variable change. Just
-remember that children can't share information, but the stuff they
-inherited from parent on their load.
+a problem...
<P>
-Also note that since the server is running in single mode - If the output
-returns HTML with IMG tags, the load of these will take a lot of time (read
-apache docs of httpd -X to learn why).
+If you run the same code in the multi server environment, after you submit
+the color change you will get the result as expected, but when you will
+call the same URL again (not reload!) chances are that you will get back
+the old color, since except the child who processed the color change
+request no one knows about their global variable change. Just remember that
+children can't share information, other than that which they inherited from
+their parent on their load.
<P>
+Also note that since the server is running in single mode, if the output
+returns HTML with IMG tags, then the load of these will take a lot of time
+(read apache docs of httpd -X to learn why).
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="_M_and_other_time_file_tests_u">-M and other time() file tests under mod_perl</A></H1></CENTER>
<P>
-Under mod_perl files that have been created after the server's (child?)
+Under mod_perl, files that have been created after the server's (child?)
startup are being reported with negative age with -M (-C -A) test. This is
obvious if you remember that you will get the negative result if the server
was started before the file was created and it's a normal behavior with any
@@ -478,18 +529,37 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A></H1></CENTER>
+<P>
+When a user presses the stop button, Apache will detect that via
+SIG{'PIPE'} and will cease the script execution. When we are talking about
+mod_cgi, there is generally no problem, since all opened files will be
+closed and all the resources will be freed (almost all -- if you happened
+to use external lock files, most likely the resources that are being locked
+by these will be left blocked and non-usable by any others who use this
+advisory locking scheme.)
+
<P>
-Ok, When user decided to press the stop button, apache will detect that
-thru the SIG{'PIPE'} and will cease the script execution. When we are
-talking about mod_cgi, there are generally no problem, since all opened
-files will be closed and all the resources will be freed (almost if you
-happened to use external lock files, most chances that the resources that
-are being locked by these will be left blocked and non-usable by any other,
-who will use this advisory locking scheme).
+Important to notice that when the user hits ``stop'' on the browser, the
+mod_perl script is blissfully unaware until it tries to send some data to
+the browser. At that point, Apache realizes that the browser is gone, and
+all the good cleanup stuff happens.
+<P>
+Starting from apache 1.3.6 apache will not catch SIGPIPE anymore and
+modperl will do it much better. Here is something from CHANGES from Apache
+1.3.6.
+
+<P>
+<PRE> *) SIGPIPE is now ignored by the server core. The request write
+ routines (ap_rputc, ap_rputs, ap_rvputs, ap_rwrite, ap_rprintf,
+ ap_rflush) now correctly check for output errors and mark the
+ connection as aborted.
+ Replaced many direct (unchecked) calls to ap_b* routines with the
+ analogous ap_r* calls. [Roy Fielding]
+</PRE>
<P>
-What's happening if your mod_perl script has some global variables, that
-are being used for resource locking?
+What happens if your mod_perl script has some global variables, that are
+being used for resource locking?
<P>
It's possible not to notice the pitfall if the critical code section
@@ -505,14 +575,14 @@
3. unlock resource
</PRE>
<P>
-If user presses 'Stop' and Apache sends SIGPIPE before stage 3, since we
-are in the mod_perl mode and we want the lock variable to be cached, it
-will be not unlocked. A kind of ``deadlock''.
+If user presses 'Stop' and Apache sends SIGPIPE before step 3, since we are
+in the mod_perl mode and we want the lock variable to be cached, it will be
+not unlocked. A kind of ``deadlock'' exists.
<P>
Here is the working example. Run the server with -X, Press 'Stop' before
the countup to 10 has been finished. Then rerun the script, it'll hang in
-<CODE>while(1)!</CODE> Resource is not available anymore.
+<CODE>while(1)!</CODE> The resource is not available anymore.
<P>
<PRE> -------------------------------------------------------------
@@ -521,12 +591,10 @@
$|=1;
my $q = new CGI;
print $q->header,$q->start_html;
-</PRE>
-<P>
-<PRE> print $q->p("$$ Going to lock!\n");
-</PRE>
-<P>
-<PRE> # actually the while loop below is not needed
+
+ print $q->p("$$ Going to lock!\n");
+
+ # actually the while loop below is not needed
# (since it's an internal lock and accessible only
# by the same process and it if it's locked... it's locked for the
# whole child's life
@@ -543,15 +611,14 @@
sleep 1;
print $c++,"\n<BR>";
}
-</PRE>
-<P>
-<PRE> print $q->p("Going to unlock!");
+
+ print $q->p("Going to unlock!");
$CACHE{LOCK} = 0;
print $q->p("Unlock!\n");
-------------------------------------------------------------
</PRE>
<P>
-You will ask, what is the solution for this problem? As noted in the
+You may ask, what is the solution for this problem? As noted in the
<A HREF="././porting.html#END_blocks">END blocks</A> any END blocks that are encountered during compilation of Apache::Registry
scripts are called after the script done is running, including subsequent
invocations when the script is cached in memory. So if you are running in
@@ -573,32 +640,56 @@
<PRE> $r->register_cleanup(sub {$CACHE{LOCK} = 0;});
</PRE>
<P>
+If you are into Apache API <CODE>Apache-</CODE>request->connection->aborted()> construct can be used to test for
+the aborted connection.
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Handling_the_server_timeout_case">Handling the server timeout cases</A></H1></CENTER>
+<P>
+A similar situation to <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Pressed Stop button disease</A> happens when client (browser) timeouts the connection (is it about 2
+minutes?) . There are cases when your script is about to perform a very
+long operation and there is a chance that its duration will be longer than
+the client's timeout. One case I can think about is the DataBase
+interaction, where the DB engine hangs or needs a lot of time to return
+results. If this is the case, use <CODE>$SIG{ALRM}</CODE> to prevent the timeouts:
+
+<P>
+<PRE> eval {
+ local $SIG{ALRM} = sub { die "timeout\n" };
+ alarm $timeout;
+ ... db stuff ...
+ alarm 0;
+ };
+
+ die $@ if $@;
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Where_do_the_warnings_errors_go_">Where do the warnings/errors go?</A></H1></CENTER>
<P>
-Your cgi doesn't work and you want to see what is the problem. The best
-idea is to checkout what the server error report. Where I can find this
-report?
+Your CGI doesn't work and you want to see what the problem is. The best
+idea is to check out any errors that the server may be reporting. Where I
+can find these errors?
<P>
-Generally all the errors are being logged into an error_log file. The exact
-file location and name are defined in the http.conf file. Watch the
-<CODE>ErrorLog</CODE> parameter. My httpd.conf says:
+Generally all errors are logged into an error_log file. The exact file
+location and name are defined in the http.conf file. Look for the <CODE>ErrorLog</CODE> parameter. My httpd.conf says:
<P>
<PRE> ErrorLog var/logs/error_log
</PRE>
<P>
-Hey, where is the beginning of the path? There is another apache's
-parameter called <CODE>ServerRoot</CODE>. Everytime apache sees a value of the parameter with no absolute path (e.g <CODE>/tmp/my.txt</CODE>) but with relative path (e.g <CODE>my.txt</CODE>) it prepends the value of the <CODE>ServerRoot</CODE> to this value. I have:
+Hey, where is the beginning of the path? There is another Apache parameter
+called <CODE>ServerRoot</CODE>. Everytime apache sees a value of the parameter with no absolute path (e.g <CODE>/tmp/my.txt</CODE>) but with relative path (e.g <CODE>my.txt</CODE>) it prepends the value of the <CODE>ServerRoot</CODE> to this value. I have:
<P>
<PRE> ServerRoot /usr/local/apache
</PRE>
<P>
So I will look for error_log file at
-<CODE>/usr/local/apache/var/logs/error_log</CODE>. Ofcourse you can use a absolute path to define the file's location at the
-filesystem.
+<CODE>/usr/local/apache/var/logs/error_log</CODE>. Of course you can also use an absolute path to define the file's location
+at the filesystem.
<P>
<META>: is this 100% correct?
@@ -607,16 +698,20 @@
But there are cases when errors don't go to the error_log file. For example
some errors are being printed to the console (tty) you have executed the
httpd from (unless you redirected the httpd's stderr flow). This happens
-when the server didn't open the error_log file for writing yet. So if the
-error happens when server executes PerlRequire or PerlModule directive you
-might see the errors goes to the tty.
+when the server didn't open the error_log file for writing yet.
+
+<P>
+For example, if you have mistakenly entered a non-existent directory path
+in your <STRONG>ErrorLog</STRONG> directive, the error message will be printed on the controlling tty. Or, if
+the error happens when server executes PerlRequire or PerlModule directive
+you might see the errors here also.
<P>
-You are probably wander where all the errors go when you are running the
-server in the single mode (httpd -X). They go to the console. That's
-because when running in the single mode there is no parent httpd process
-who performs all the logging. It includes all the status messages that
-generally show up in the error_log file.
+You are probably wonder where all the errors go when you are running the
+server in single mode (httpd -X). They go to the console. That is because
+when running in the single mode there is no parent httpd process to perform
+all the logging. It includes all the status messages that generally show up
+in the error_log file.
<P>
</META>
@@ -635,7 +730,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 01/23/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
1.10 +92 -73 modperl-site/guide/performance.html
Index: performance.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/performance.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- performance.html 1999/03/16 08:20:21 1.9
+++ performance.html 1999/04/03 20:33:52 1.10
@@ -7,6 +7,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -97,16 +105,24 @@
compile method of CGI.pm. The third test checks benefit the the Library
Perl Module preload but a few of them (too see more memory saved) and also
the effect of precompiling the Registry modules with
-Apache::RegistryLoader.
+Apache::RegistryLoader.
<P>
-Summary: 1. Library Perl Modules Preloading gave a good results everywhere.
+Summary:
+
+<P>
+1. Library Perl Modules Preloading gave a good results everywhere.
+
+<P>
2. compile method of CGI seems to make things worse (may be the speed is
-better?) 3. Apache::RegistryLoader might made the script load faster on the
-first request after the child has just started but the memory usage was
-worse!!! See the numbers by yourself.
+better?)
<P>
+3. Apache::RegistryLoader might made the script load faster on the first
+request after the child has just started but the memory usage was worse!!!
+See the numbers by yourself.
+
+<P>
HW/SW: The server is apache 1.3.2, mod_perl 1.16 running on AIX 4.1.5
<P>
@@ -329,7 +345,7 @@
httpd 26844 0.0 1.0 6748 5092 - A 17:23:12 0:00 httpd
</PRE>
<P>
-Observation: child httpd has grown even more 3316K ! Doesn't seem to be
+Observation: child httpd has grown even more 3316K ! Does not seem to be
good!
<P>
@@ -340,15 +356,16 @@
each child with Apache::DBI.
<P>
-<PRE> use Apache::DBI ();
- Apache::DBI->connect_on_init("DBI:mysql:test", '','', {
- RaiseError => 1,
- PrintError => 1,
- AutoCommit => 1,
- };
+<PRE> use Apache::DBI ();
+ Apache::DBI->connect_on_init("DBI:mysql:test", 'login','passwd',
+ {
+ RaiseError => 1,
+ PrintError => 1,
+ AutoCommit => 1,
+ };
</PRE>
<P>
-See also <A HREF="#Persistent_DB_Connections">Persistant DB Connections</A>
+See also <A HREF="#Persistent_DB_Connections">Persistent DB Connections</A>
@@ -379,7 +396,7 @@
warn "pre-load of `$url' failed, status=$status\n";
}
}, $perl_dir);
- }
+ }
</PRE>
<P>
Note that we don't use here the second argument to the
@@ -405,7 +422,7 @@
<P>
When possible, avoid importing of a module functions into your namespace.
The aliases which are created can take up quite a bit of space. Try to use
-method interfaces and fully qualified Package::function names instead.
+method interfaces and fully qualified Package::function names instead.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -429,7 +446,7 @@
<P>
Joel Wagner reports that calling an undefined subroutine in a module can
cause a tight loop that consumes all memory. Here is a way to catch such
-errors. Define an autoload subroutine
+errors. Define an autoload subroutine:
<P>
<PRE> sub UNIVERSAL::AUTOLOAD {
@@ -639,21 +656,18 @@
<P>
<PRE> Benchmark: timing 100 iterations of cgi, perl... [rate 1:28]
-</PRE>
-<P>
-<PRE> cgi: 56 secs ( 0.33 usr 0.28 sys = 0.61 cpu)
+
+ cgi: 56 secs ( 0.33 usr 0.28 sys = 0.61 cpu)
perl: 2 secs ( 0.31 usr 0.27 sys = 0.58 cpu)
Benchmark: timing 1000 iterations of cgi,perl... [rate 1:21]
-</PRE>
-<P>
-<PRE> cgi: 567 secs ( 3.27 usr 2.83 sys = 6.10 cpu)
+
+ cgi: 567 secs ( 3.27 usr 2.83 sys = 6.10 cpu)
perl: 26 secs ( 3.11 usr 2.53 sys = 5.64 cpu)
Benchmark: timing 10000 iterations of cgi, perl [rate 1:21]
-</PRE>
-<P>
-<PRE> cgi: 6494 secs (34.87 usr 26.68 sys = 61.55 cpu)
+
+ cgi: 6494 secs (34.87 usr 26.68 sys = 61.55 cpu)
perl: 299 secs (32.51 usr 23.98 sys = 56.49 cpu)
</PRE>
<P>
@@ -742,9 +756,8 @@
<P>
<PRE> % ./ab -n 100 -c 10 www.you.com:81/test/test.pl
-</PRE>
-<P>
-<PRE> Concurrency Level: 10
+
+ Concurrency Level: 10
Time taken for tests: 0.715 seconds
Complete requests: 100
Failed requests: 0
@@ -753,9 +766,8 @@
HTML transferred: 31900 bytes
Requests per second: 139.86
Transfer rate: 84.90 kb/s received
-</PRE>
-<P>
-<PRE> Connection Times (ms)
+
+ Connection Times (ms)
min avg max
Connect: 0 0 3
Processing: 13 67 71
@@ -797,10 +809,16 @@
500</CODE> derived 94.82 req/sec. It went down with the high load.
<P>
-This test was performed with the following configuration: MinSpareServers 8
-MaxSpareServers 6 StartServers 10 MaxClients 50 MaxRequestsPerChild 1500
+This test was performed with the following configuration:
<P>
+<PRE> MinSpareServers 8
+ MaxSpareServers 6
+ StartServers 10
+ MaxClients 50
+ MaxRequestsPerChild 1500
+</PRE>
+<P>
Now let's try this:
<P>
@@ -833,7 +851,7 @@
MaxRequestsPerChild 1500
</PRE>
<P>
-I've got 27.12 req/sec, which is better but still 4-5 times slower (133
+I have got 27.12 req/sec, which is better but still 4-5 times slower (133
with Maxclients of 50)
<P>
@@ -847,32 +865,36 @@
<P>
The important parameters are MaxClients and MaxRequestsPerChild. MaxClients
-should be not to big so it'll not abuse your machine's memory resources and
-not too small, when users will be forced to wait for the children to become
-free to come serve them. MaxRequestsPerChild should be as big as possible,
-to take the full benefit of the mod_perl, but watch your server at the
-beginning to make sure your scripts aren't leaking memory causing your
-server (and your service) to die very fast.
+should be not to big so it will not abuse your machine's memory resources
+and not too small, when users will be forced to wait for the children to
+become free to come serve them. MaxRequestsPerChild should be as big as
+possible, to take the full benefit of the mod_perl, but watch your server
+at the beginning to make sure your scripts are not leaking memory causing
+your server (and your service) to die very fast.
<P>
-Also it's important to understand that we didn't test the respond times in
+Also it is important to understand that we didn't test the respond times in
the tests above, but the ability of the server to respond. If the script
that was used to test was heavier, the numbers would be different but the
conclusions are very similar.
<P>
-The benchmarks were run at: HW: RS6000, 1Gb RAM SW: AIX 4.1.5 . mod_perl
-1.16, apache 1.3.3 Machine running only mysql service, httpd docs and
-mod_perl servers. Machine was completely unloaded during the benchmarking.
+The benchmarks were run at:
<P>
+<PRE> HW: RS6000, 1Gb RAM
+ SW: AIX 4.1.5 . mod_perl 1.16, apache 1.3.3
+ Machine running only mysql service, httpd docs and mod_perl servers.
+ Machine was completely unloaded during the benchmarking.
+</PRE>
+<P>
After each server restart when I did changes to server's configurations, I
made sure the scripts were preloaded by fetching a script at least one time
by each child.
<P>
-It's important to notice that None of requests timeouted even if was kept
-in server's queue form more than 1 minute! (That's the way <STRONG>ab</STRONG>
+It is important to notice that None of requests timeouted even if was kept
+in server's queue form more than 1 minute! (That is the way <STRONG>ab</STRONG>
works, which is OK for the test but will not for the real world - user will
not wait for more than 5-10 secs for a request to complete, and the browser
will timeout in a 30 secs or so)
@@ -915,7 +937,7 @@
Conclusions: Here I wanted to show that when the application is slow not
because of perl loading, script compiling and execution, but bounded to
some external operation like mysqld querying which made the bottleneck - it
-almost doesn't matter what is the load we make - the RPS (Requests per
+almost does not matter what is the load we make - the RPS (Requests per
second) is almost the same (taken that all the requested has been served,
you have an ability to queue the clients, but be aware that something that
goes to queue means a waiting client and browser can get timeouted!)
@@ -963,9 +985,8 @@
StartServers 50
MaxClients 50
MaxRequestsPerChild 5000
-</PRE>
-<P>
-<PRE> NR NC RPS comment
+
+ NR NC RPS comment
------------------------------------------------
100 10 32.05
1000 10 33.14
@@ -988,9 +1009,8 @@
StartServers 10
MaxClients 10
MaxRequestsPerChild 5000
-</PRE>
-<P>
-<PRE> NR NC RPS comment
+
+ NR NC RPS comment
------------------------------------------------
10 10 23.87 # not a reliable stats
100 10 32.64
@@ -1017,9 +1037,8 @@
MaxSpareServers 16
StartServers 10
MaxClients 50
-</PRE>
-<P>
-<PRE> NR NC MRPC RPS comment
+
+ NR NC MRPC RPS comment
------------------------------------------------
100 10 10 5.77
100 10 5 3.32
@@ -1038,9 +1057,8 @@
MaxSpareServers 16
StartServers 10
MaxClients 50
-</PRE>
-<P>
-<PRE> NR NC RPS comment
+
+ NR NC RPS comment
------------------------------------------------
100 10 1.12
1000 50 1.14
@@ -1422,15 +1440,14 @@
<CENTER><H1><A NAME="Persistent_DB_Connections">Persistent DB Connections</A></H1></CENTER>
<P>
Another popular use of mod_perl is to take advantage of it's persistence to
-maintain open database connections. The basic idea goes like so:
+maintain open database connections. The basic idea goes like so:
<P>
<PRE> #Apache::Registry script
use strict;
use vars qw($dbh);
-</PRE>
-<P>
-<PRE> $dbh ||= SomeDbPackage->connect(...);
+
+ $dbh ||= SomeDbPackage->connect(...);
</PRE>
<P>
Since <CODE>$dbh</CODE> is a global variable for the child, once the child
@@ -1449,9 +1466,10 @@
the ping method. If these two conditions are fulfilled it just returns the
database handle. If there is no appropriate database handle or if the ping
method fails, a new connection is established and the handle is stored for
-later re-use. <STRONG>There is no need to delete the disconnect statements from your
-code</STRONG>. They won't do anything because the Apache::DBI module overloads the
-disconnect method with a NOP.
+later re-use. <STRONG>There is no need to delete the disconnect statements from
+your code</STRONG>. They would not do anything because the Apache::DBI module overloads the
+disconnect method with a NOP. On child exit there is no explicit
+disconnect, the child dies and so does the database connection.
<P>
The usage is simple:
@@ -1460,10 +1478,11 @@
<PRE> httpd.conf
----------
PerlModule Apache::DBI
-
-It is important, to load this module before any other ApacheDBI module !
</PRE>
<P>
+It is important, to load this module before any other ApacheDBI module !
+
+<P>
<PRE> a script.perl
------------
use DBI;
@@ -1472,9 +1491,8 @@
my $dbh = DBI->connect( 'DBI:mysql:database', 'user', 'password',
{ autocommit => 0 }
) || die $DBI::errstr;
-</PRE>
-<P>
-<PRE> ...rest of program
+
+ ...rest of program
</PRE>
<P>
The module provides the additional method:
@@ -1490,7 +1508,7 @@
to see the requirements for this method.
<P>
-However be warned that some old DBD drivers aren't supporting this feature
+However be warned that some old DBD drivers are not supporting this feature
(ping method), so check the documentation of the driver you use.
<P>
@@ -1534,6 +1552,7 @@
information on the execution time of a Perl script and of the subs in that
script. This information can be used to determine which subroutines are
using the most time and which subroutines are being called most often.
+
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P><A HREF="index.html">[Back to the main page]</A></P>
@@ -1548,7 +1567,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/15/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
1.11 +399 -318 modperl-site/guide/porting.html
Index: porting.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/porting.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- porting.html 1999/03/16 08:20:22 1.10
+++ porting.html 1999/04/03 20:33:52 1.11
@@ -7,6 +7,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -27,7 +35,7 @@
<UL>
<LI><A HREF="#Script_s_namespace">Script's namespace</A>
- <LI><A HREF="#Names_collisions_with_Modules_an">Names collisions with Modules and libs</A>
+ <LI><A HREF="#Name_collisions_with_Modules_and">Name collisions with Modules and libs</A>
<LI><A HREF="#_END_or_DATA_tokens">__END__ or __DATA__ tokens</A>
<LI><A HREF="#Output_from_system_calls">Output from system calls</A>
<LI><A HREF="#Using_format_">Using format()</A>
@@ -39,16 +47,20 @@
<LI><A HREF="#BEGIN_blocks">BEGIN blocks </A>
<LI><A HREF="#END_blocks">END blocks </A>
<LI><A HREF="#Switches_w_T">Switches -w, -T</A>
- <LI><A HREF="#Switches_w_T">Switches -w, -T</A>
</UL>
<LI><A HREF="#strict_pragma">strict pragma</A>
<LI><A HREF="#Turning_warnings_ON">Turning warnings ON</A>
<LI><A HREF="#diagnostics_pragma">diagnostics pragma</A>
<LI><A HREF="#Global_Variables">Global Variables</A>
- <LI><A HREF="#Code_has_been_changed_but_seems">Code has been changed, but seems that script uses the old code</A>
- <LI><A HREF="#Memory_leakages">Memory leakages</A>
- <LI><A HREF="#Sometimes_it_works_Sometimes_Not">Sometimes it works Sometimes Not (Very important!)</A>
+ <LI><A HREF="#Code_has_been_changed_but_it_se">Code has been changed, but it seems the script is running the old code</A>
+ <LI><A HREF="#Memory_leakage">Memory leakage</A>
+ </UL>
+
+ <LI><A HREF="#Filehandlers_and_locks_leakages">Filehandlers and locks leakages</A>
+ <UL>
+
+ <LI><A HREF="#Sometimes_it_Works_Sometimes_Not">Sometimes it Works Sometimes Not (Very important!)</A>
<LI><A HREF="#The_Script_is_too_dirty_It_does">The Script is too dirty, It does the job and I can't afford rewriting it.</A>
<LI><A HREF="#Apache_PerlRun_a_closer_look">Apache::PerlRun - a closer look</A>
</UL>
@@ -61,32 +73,34 @@
<P>
<CENTER><H1><A NAME="Document_Coverage">Document Coverage</A></H1></CENTER>
<P>
-This document is relevant for both - writing a new cgi from scratch and
-migrating from the plain cgi to mod_perl.
+This document is relevant to both writing a new CGI from scratch and
+migrating an application from plain CGI to mod_perl.
<P>
-If you are in the porting stage use it as a reference for possible problems
-you might encounter when running the existent CGI in the new mode.
+If you are in the porting stage, use it as a reference for possible
+problems you might encounter when running the existent CGI in the new mode.
<P>
-If you are about to write a new cgi from scratch, it would be a good idea
+If you are about to write a new CGI from scratch, it would be a good idea
to learn most of the possible pitfalls and to avoid them in first place.
<P>
-It covers also the case when the script is too dirty, but does the job and
-I can't afford rewriting it. (Apache::PerlRun)
+It covers also the case where the CGI script being ported does the job, but
+is too dirty to be easily altered to run as a mod_perl program.
+(Apache::PerlRun)
<P>
-If your project in hurry, I would think of the following steps: First run
-all the scripts in the Apache::PerlRun mode - then as time allows you, move
-them into Apache::Registry mode.
+If your project schedule is tight, I would suggest converting to mod_perl
+in the following steps: Initially, run all the scripts in the
+Apache::PerlRun mode. Then as time allows, move them into Apache::Registry
+mode.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Before_you_start_to_code">Before you start to code</A></H1></CENTER>
<P>
-It can be a good idea to strengthen some of the programming skills, since
-Apache::Registry doesn't allow sloppiness programming.
+It can be a good idea to tighten up some of your Perl programming
+practices, since Apache::Registry doesn't allow sloppy programming.
<P>
You might want to read:
@@ -94,56 +108,60 @@
<UL>
<P><LI><STRONG><A NAME="item_Perl">Perl Module Mechanics</A></STRONG>
<P>
-This page describes the mechanics of creating, compiling, releasing and
+This page describes the mechanics of creating, compiling, releasing, and
maintaining Perl modules. <A
HREF="http://world.std.com/~swmcd/steven/perl/module_mechanics.html">http://world.std.com/~swmcd/steven/perl/module_mechanics.html</A>
<P><LI><STRONG><A NAME="item_Mod">Mod Perl Book</A></STRONG>
<P>
-(when it will be released) - you can find parts of the book online at <A
-HREF="http://www.modperl.com.">http://www.modperl.com.</A>
+A must have book! See the details at <A
+HREF="http://www.modperl.com">http://www.modperl.com</A> .
</UL>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Coding_with_mod_perl">Coding with mod_perl</A></H1></CENTER>
<P>
-First, before you start coding for Apache::Registry you have to change the
-state of your mind. Scripts running under mod_perl are like subroutines are
-being called from the daemon who runs all the time. Imagine the daemon
-process that when requested to process some of the scripts - reads it in,
-compiles it as a subroutine and finally executes it. On any subsequent
-request it'll just recall the already compiled subroutine. Hope that you
+Before you start coding for Apache::Registry, you have to change your
+programming state of mind. Scripts running under mod_perl are like
+subroutines are being called from a continually running daemon. Imagine a
+daemon process that when requested to process some script, reads it in,
+compiles it as a subroutine, and finally executes it. On any subsequent
+request, it'll just recall the already compiled subroutine. Hope that you
get the idea.
<P>
The best thing you do when coding from scratch is to make it clean and use
-packages, as you go thru the notes you will understand why.
+packages. By ``make it clean'' we mean make certain that you <STRONG>use strict;</STRONG>
+and that your script produces no warnings when tested via
+<STRONG>perl -cw myscript.pl</STRONG>. As you go thru the notes you will understand why.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="What_s_different_about_modperl">What's different about modperl</A></H2></CENTER>
<P>
-There are a few things that behaves differently under mod_perl. It's good
-to know what they are.
+There are a few things that behave differently under mod_perl. It's good to
+know what they are.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H3><A NAME="Script_s_namespace">Script's namespace</A></H3></CENTER>
<P>
-Scripts under Apache::Registry do not run in package <STRONG>main</STRONG>, they run in a unique namespace based on the requested uri. e.g if your
-uri is /perl/test.pl the package will be called
-Apache::ROOT::perl::test_2epl;
+Scripts under Apache::Registry do not run in package <STRONG>main</STRONG>, they run in a unique namespace based on the requested uri. For example,
+if your uri is <STRONG>/perl/test.pl</STRONG> the package will be called
+<STRONG>Apache::ROOT::perl::test_2epl;</STRONG>
+
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="Names_collisions_with_Modules_an">Names collisions with Modules and libs</A></H3></CENTER>
+<CENTER><H3><A NAME="Name_collisions_with_Modules_and">Name collisions with Modules and libs</A></H3></CENTER>
<P>
-Just to make things clear before we go into details: each server process
-has its own <CODE>%INC</CODE> array which is used to store the information
-about compiled modules. Where the keys are the names of the modules or
-parameters passed to <CODE>require().</CODE> And values are the real paths
+Just to make things clear before we go into detail: each server process has
+its own <CODE>%INC</CODE> hash which is used to store information about its
+compiled modules. The keys of the hash are the names of the modules or
+parameters passed to <CODE>require().</CODE> The values are the real paths
to these modules. So if you do (assume it's in the <CODE>@INC</CODE> path)
<P>
@@ -160,7 +178,7 @@
<P>
You can't have 2 identical module names running under the same server! Only
-the first one <CODE>use()d</CODE> or <CODE>require()d</CODE> will be
+the first one <CODE>use()'d</CODE> or <CODE>require()'d</CODE> will be
compiled into the package, the request to the other identical module will
be skipped since server will think that it's already compiled. It'll be
already in child's %INC. (See <A HREF="././status.html#Watching_the_server">Watching the server</A>
@@ -178,7 +196,7 @@
<P>
And both scripts do: <CODE>use Foo;</CODE> only the first one called will know about Foo, when you will call the
second script it will not know about Foo at all - it's like you've
-forgotten to write <CODE>use Foo;</CODE>. Run the server in the <A HREF="././control.html#Single_Mode_Running">single server mode</A> to solve that kind of bug immediately.
+forgotten to write <CODE>use Foo;</CODE>. Run the server in <A HREF="././control.html#Single_Mode_Running">single server mode</A> to solve that kind of bug immediately.
<P>
You will see the following in the error_log file:
@@ -215,7 +233,8 @@
<OL>
<P><LI>
<P>
-Add some special path so the fs layout will be something like
+Place your library modules in a subdirectory structure so that they have
+different path prefixes. The file system layout will be something like
<P>
<PRE> cgi/tool1/Tool1/Foo.pm
@@ -224,14 +243,14 @@
cgi/tool2/tool2.pl
</PRE>
<P>
-And you change the scripts:
+And change the scripts:
<P>
<PRE> use Tool1::Foo;
use Tool2::Foo;
</PRE>
<P>
-and respectively the package declaration in the modules:
+and respectively, the package declaration in the modules:
<P>
<PRE> package Tool1::Foo;
@@ -256,11 +275,12 @@
<P>
<PRE> use lib qw(.);
require "tool2-lib/config.pl";
+
</PRE>
<P><LI>
<P>
-Or use a full path to the script, so it'll be compiled into the name of the
-key in the %INC;
+Another option is to use a full path to the script, so it'll be compiled
+into the name of the key in the %INC;
<P>
<PRE> require "/full/path/to/the/config.pl";
@@ -276,8 +296,8 @@
package name for the key!
<P>
-But then you will have to use Package::function() method unless you will
-export the symbols from the <CODE>use()d</CODE> package like
+But then you will have to use <STRONG>Package::function()</STRONG> method unless you will export the symbols from the <CODE>use()'d</CODE>
+package like:
<P>
<PRE> use Package qw(:all_subs);
@@ -287,7 +307,7 @@
process.
<P>
-<STRONG>Important:</STRONG> Only this solution will work, if you have 2 scripts that
+<STRONG>Important:</STRONG> This solution will only work if you have two scripts that
<CODE>require()</CODE> the same file!
<P>
@@ -325,39 +345,38 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H3><A NAME="Output_from_system_calls">Output from system calls</A></H3></CENTER>
<P>
-Output of system, exec and open PIPE, ``|program'' calls will not be sent
-to the browser unless you Perl was configured with sfio.
+Output of <STRONG>system</STRONG>, <STRONG>exec</STRONG>, and <STRONG>open PIPE "|program"</STRONG> calls will not be sent to the browser unless your Perl was configured with
+sfio.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H3><A NAME="Using_format_">Using format()</A></H3></CENTER>
<P>
-Currently Possible Only if you have perl compiled with sfio
+Currently possible only if you have perl compiled with sfio
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H3><A NAME="Using_exit_">Using exit()</A></H3></CENTER>
<P>
-Perl's <CODE>exit()</CODE> built-in function cannot be used in mod_perl
-scripts. Unless you want the server child to exit (which makes the whole
-idea of using mod_perl irrelevant). The Apache::exit() function should be
-used instead.
+Perl's <STRONG>exit()</STRONG> built-in function cannot be used in mod_perl scripts. Calling it causes the
+server child to exit (which makes the whole idea of using mod_perl
+irrelevant.) The <STRONG>Apache::exit()</STRONG> function should be used instead.
<P>
-You might start you scripts with overriding the exit sub (if you use
-directly the Apache::exit() you will have the problem to test the script
-from the shell, unless you stuff <CODE>use Apache ();</CODE> into your code. I use the following code:
+You might start your scripts by overriding the exit sub (if you use
+<STRONG>Apache::exit()</STRONG> directly, you will have a problem testing the script from the shell, unless
+you stuff <CODE>use Apache ();</CODE> into your code.) I use the following code:
<P>
<PRE> BEGIN {
# Auto-detect if we are running under mod_perl or CGI.
- $USE_MOD_PERL = ( (exists $ENV{'GATEWAY_INTERFACE'} and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
+ $USE_MOD_PERL = ( (exists $ENV{'GATEWAY_INTERFACE'}
+ and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
or exists $ENV{'MOD_PERL'} ) ? 1 : 0;
}
use subs (exit);
-</PRE>
-<P>
-<PRE> # Select the correct exit way
+
+ # Select the correct exit way
########
sub exit{
# Apache::exit(-2) will cause the server to exit gracefully,
@@ -366,27 +385,27 @@
}
</PRE>
<P>
-Now every time the select code will be called and the correct exit will be
-picked, no matter if you run the script as cgi or from shell.
+Now each time the select code is called, the correct <STRONG>exit</STRONG>
+will be chosen, whether you run the script as a CGI or from the shell.
<P>
<STRONG>Note</STRONG> that if you run the script under <CODE>Apache::Registry</CODE>, <STRONG>The
Apache function `exit' overrides the Perl core built-in
function</STRONG>. While you see the <CODE>exit()</CODE> listed in <CODE>@EXPORT_OK</CODE>
of Apache package, Apache::Registry makes something you don't see and
-imports this function for you. (which means that if your script is running
-under Apache::Registry handler, you don't have to worry about
-<CODE>exit(),</CODE> Apache::PerlRun as well)
+imports this function for you. This means that if your script is running
+under Apache::Registry handler (Apache::PerlRun as well), you don't have to
+worry about <CODE>exit().</CODE>
<P>
<STRONG>Note</STRONG> that if you still use CORE::exit() in your scripts running under modperl,
the child will exit, but neither proper exit nor logging will happen on the
-way. CORE::exit() cuts off server's legs... If you need to properly
-shutdown the child , use $r->child_terminate (which sets the internal
-MaxRequestsPerChild so the child will exit).
+way. CORE::exit() cuts off the server's legs... If you need to properly
+shutdown the child , use $r->child_terminate (which sets the internal MaxRequestsPerChild so the child
+will exit).
<P>
-You can accomplish that in 2 ways - in the Apache::Registry script:
+You can accomplish this in 2 ways - in the Apache::Registry script:
<P>
<PRE> Apache->request->child_terminate;
@@ -403,17 +422,16 @@
<P>
Your scripts <CODE>*will</CODE> not* run from the command line (yet) unless
you use CGI::Switch or CGI.pm and 5.004+ and do not make any direct calls
-to Apache->methods. Since it's different environment and See also above.
+to Apache->methods.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H3><A NAME="I_O_is_different">I/O is different</A></H3></CENTER>
<P>
-If you are using Perl 5.004 most CGI scripts can run under mod_perl
-untouched. If you're using 5.003, Perl's built-in <CODE>read()</CODE> and
-<CODE>print()</CODE> functions do not work as they do under CGI. If you're
-using CGI.pm, use $query->print instead of plain 'ol
-<CODE>print().</CODE>
+If you are using Perl 5.004 or better, most CGI scripts can run under
+mod_perl untouched. If you're using 5.003, Perl's built-in
+<CODE>read()</CODE> and <CODE>print()</CODE> functions do not work as they
+do under CGI. If you're using CGI.pm, use $query->print instead of plain 'ol <CODE>print().</CODE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -431,11 +449,10 @@
terminating newline, your script must send that itself, e.g.:
<P>
-<PRE> print "Content-type: text/html\n\n";
+<PRE> print "Content-type: text/html\r\n\r\n";
</PRE>
<P>
-If you're using CGI.pm or CGI::Switch and 'print $q->header' you do
-_not_ need PerlSendHeader On.
+If you're using CGI.pm or CGI::Switch and <STRONG>print $q->header</STRONG> you do _not_ need PerlSendHeader On.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -448,11 +465,11 @@
<PRE> local $| = 1;
</PRE>
<P>
-And If you normally set PerlSendHeader On, add this to your httpd.conf:
+And if you normally set PerlSendHeader On, add this to your httpd.conf:
<P>
<PRE> <Files */nph-*>
- PerlSendHeader Off
+ PerlSendHeader Off
</Files>
</PRE>
<P>
@@ -461,32 +478,62 @@
<P>
Perl executes BEGIN blocks during the compile time of code as soon as
possible. The same is true under mod_perl. However, since mod_perl normally
-only compiles scripts and modules once, in the parent server or once
-per-child, BEGIN blocks in that code will only be run once. As perlmod
-explains, once a BEGIN has run, it is immediately undefined. In the
+only compiles scripts and modules once -- either in the parent server or
+once per-child -- BEGIN blocks in that code will only be run once. As
+perlmod explains, once a BEGIN has run, it is immediately undefined. In the
mod_perl environment, this means BEGIN blocks will not be run during each
incoming request unless that request happens to be one that is compiling
the code.
<P>
Modules and files pulled in via require/use which contain BEGIN blocks will
-be executed: - only once, if pulled in by the parent process - once
-per-child process if not pulled in by the parent process - an additional
-time, once per-child process if the module is pulled in off of disk again
-via Apache::StatINC - an additional time, in the parent process on each
-restart if PerlFreshRestart is On - unpredictable if you fiddle with
-<CODE>%INC</CODE> yourself.
+be executed:
+
+<DL>
+<P><DT><STRONG><A NAME="item__">-</A></STRONG><DD>
+<P>
+only once, if pulled in by the parent process.
+
+<P><DT><STRONG>-</STRONG><DD>
+<P>
+once per-child process if not pulled in by the parent process.
+<P><DT><STRONG>-</STRONG><DD>
<P>
-Apache::Registry scripts which contain BEGIN blocks will be executed: -
+an additional time, once per-child process if the module is pulled in off
+of disk again via Apache::StatINC.
+
+<P><DT><STRONG>-</STRONG><DD>
+<P>
+an additional time, in the parent process on each restart if
+PerlFreshRestart is On.
+
+<P><DT><STRONG>-</STRONG><DD>
+<P>
+unpredictable if you fiddle with <CODE>%INC</CODE> yourself.
+
+</DL>
+<P>
+Apache::Registry scripts which contain BEGIN blocks will be executed:
+
+<DL>
+<P><DT><STRONG>-</STRONG><DD>
+<P>
only once, if pulled in by the parent process via Apache::RegistryLoader -
-once per-child process if not pulled in by the parent process - an
-additional time, once per-child process if the script file has changed on
-disk - an additional time, in the parent process on each restart if pulled
-in by the parent process via Apache::RegistryLoader and PerlFreshRestart is
-On.
+once per-child process if not pulled in by the parent process.
+
+<P><DT><STRONG>-</STRONG><DD>
+<P>
+an additional time, once per-child process if the script file has changed
+on disk.
+<P><DT><STRONG>-</STRONG><DD>
<P>
+an additional time, in the parent process on each restart if pulled in by
+the parent process via Apache::RegistryLoader and PerlFreshRestart is On.
+
+</DL>
+<P>
Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
<P>
@@ -499,23 +546,23 @@
mod_perl does make a special case for Apache::Registry scripts.
<P>
-Normally, END blocks are executed by Perl during it's
-<CODE>perl_run()</CODE> function, which is called once each time the Perl
-program is executed, e.g. once per (mod_cgi) CGI scripts. However, mod_perl
-only calls <CODE>perl_run()</CODE> once, during server startup. Any END
-blocks encountered during main server startup, i.e. those pulled in by the
-PerlRequire or by any PerlModule are suspended and run at server shutdown,
-aka child_exit (requires apache 1.3b3+).
+Normally, END blocks are executed by Perl during its <STRONG>perl_run()</STRONG>
+function, which is called once each time the Perl program is executed, e.g.
+once per (mod_cgi) CGI scripts. However, mod_perl only calls
+<STRONG>perl_run()</STRONG> once, during server startup. Any END blocks encountered during main server
+startup, i.e. those pulled in by the PerlRequire or by any PerlModule, are
+suspended and run at server shutdown, aka child_exit (requires apache
+1.3b3+).
<P>
Any END blocks that are encountered during compilation of Apache::Registry
-scripts <STRONG>are called after the script done its
-running</STRONG> (not during the cleanup phase though) including subsequent invocations when
+scripts <STRONG>are called after the script has completed</STRONG>
+(not during the cleanup phase though) including subsequent invocations when
the script is cached in memory. All other END blocks encountered during
other Perl*Handler callbacks, e.g. PerlChildInitHandler, will be suspended
while the process is running and called during child_exit when the process
-is shutting down. Module authors may be wish to use $r->register_cleanup
-as an alternative to END blocks if this behavior is not desirable.
+is shutting down. Module authors may be wish to use $r->register_cleanup as an alternative to END blocks if this behavior is not
+desirable.
<P>
The last paragraph is very important for the <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>
@@ -527,17 +574,16 @@
<CENTER><H3><A NAME="Switches_w_T">Switches -w, -T</A></H3></CENTER>
<P>
Normally when you run perl from the command line or have the shell invoke
-it with `#!', you may choose to pass perl switch arguments such as -w or
--T. Most command line arguments have a equivalent special variable. For
-example, the $^W variable corresponds to the -w switch. Consult perlvar for
-more details. With mod_perl it is also possible to turn on warnings
-globally via the PerlWarn directive:
+it with `#!', you may choose to pass perl switch arguments such as <STRONG>-w</STRONG> or <STRONG>-T</STRONG>. Most command line arguments have a equivalent special variable. For
+example, the <STRONG>$^W</STRONG> variable corresponds to the <STRONG>-w</STRONG>
+switch. Consult perlvar for more details. With mod_perl it is also possible
+to turn on warnings globally via the PerlWarn directive:
<P>
<PRE> PerlWarn On
</PRE>
<P>
-You can turn it off with <CODE>local $^W = 0;</CODE> in your scripts on the local basis (or inside the block). If you write <CODE>$^W = 0;</CODE> you disable the warn mode everywhere, the same with <CODE>$^W = 1;</CODE>.
+You can turn it off with <CODE>local $^W = 0;</CODE> in your scripts on the local basis (or inside the block). If you write <CODE>$^W = 0;</CODE> you disable the warning mode everywhere, the same with <CODE>$^W = 1;</CODE>.
<P>
The switch which enables taint checks does not have a special variable, so
@@ -548,23 +594,20 @@
<PRE> PerlTaintCheck On
</PRE>
<P>
-Now, any and all code compiled inside httpd will be checked.
+Now, any and all code compiled inside httpd will be taint checked.
<P>
The environment variable PERL5OPT can be used to set additional perl
startup flags such as -d and -D. See perlrun.
<P>
-If you have the shebang line (#!/bin/perl -wT) in your script, <STRONG>-w</STRONG>
+If you have the shebang line (#!/bin/perl -Tw) in your script, <STRONG>-w</STRONG>
will be honored (which means that you have turned the warn mode on for the
scope of this script, <STRONG>-T</STRONG> will produce a warning if
<CODE>PerlTaintCheck</CODE> isn't <CODE>On</CODE>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="Switches_w_T">Switches -w, -T</A></H3></CENTER>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="strict_pragma">strict pragma</A></H2></CENTER>
<P>
It's absolutely mandatory to start all your scripts with:
@@ -573,8 +616,8 @@
<PRE> use strict; (at least for development)
</PRE>
<P>
-If you need you can always to turn off the 'strict' pragma inside the
-block, e.g:
+If needed, you can always turn off the 'strict' pragma inside the block,
+e.g:
<P>
<PRE> {
@@ -583,10 +626,9 @@
}
</PRE>
<P>
-It's more important to have use strict enabled under mod_perl Perl than
-anywhere else, while it's not required, it strongly recommended, it will
-save you more time in the long run. And, of course, clean scripts will
-still run under mod_cgi (plain CGI)!
+It's more important to have <STRONG>use strict;</STRONG> enabled under mod_perl than anywhere else. While it's not required, it is
+strongly recommended, it will save you more time in the long run. And, of
+course, clean scripts will still run under mod_cgi (plain CGI)!
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -594,46 +636,49 @@
<P>
Have a <CODE>$^W=1</CODE> in the script or PerlWarn ON at the server config file. Turning the warning
on will save you a lot of troubles with debugging your code. Note that
-first magic line <CODE>#!/perl -swithces</CODE>
-#is ignored by mod_perl so do the switches you used to write there.
+first magic line <CODE>#!/perl -switches</CODE>
+is ignored by mod_perl, so too are the switches you used to write there.
<P>
-If you need you can always turn off the warning with <CODE>$^W = 0</CODE> in your code, if you have some section you don't want the perl compiler to
+If you need you can always turn off the warning with <CODE>$^W = 0</CODE> in your code if you have some section you don't want the perl compiler to
warn in.
<P>
-In a production code it can be a good idea to have the Warnings Off.
-Otherwise if your code isn't very clean and spits a few lines of warns here
-and there, you will end up with a huge error_log file in a short time on
-the loaded server.
+In production code, it can be a good idea to turn warnings off. Otherwise
+if your code isn't very clean and spits a few lines of warnings here and
+there, you will end up with a huge error_log file in a short time on the
+loaded server. Also, enabling runtime warning checking has a small
+performance impact -- in any script, not just under mod_perl -- so your
+approach should be to enable warnings during development, and then disable
+them when your code is production-ready.
<P>
-<CODE>use diagnostics;</CODE> can put more light on the errors and warns you see, But you better don't
-use <CODE>use diagnostics;</CODE>
-in the production, since you end up in a huge overhead of the diagnostics
-pragma. (run the script with -dDprof to check the overhead. See
+<CODE>use diagnostics;</CODE> can shed more light on the errors and warnings you see, but again, it's
+better to not use <CODE>use diagnostics;</CODE>
+in production, since otherwise you incur the overhead of the diagnostics
+pragma. (You can run your script with -dDprof to check the overhead. See
Devel::Dprof for more info)
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="diagnostics_pragma">diagnostics pragma</A></H2></CENTER>
<P>
-Perl compiler pragma to force verbose warning diagnostics. Put at the start
-of your scripts:
+This is a Perl compiler pragma which forces verbose warning diagnostics.
+Put at the start of your scripts:
<P>
<PRE> use diagnostics;
</PRE>
<P>
-This pragma turns on the -w mode, but gives you a much better diagnostics
-of the errors and warnings. Generally it explains the reason for
-warnings/errors you get, shows you an example of code, where the same kind
-of warning is being triggered and tells you the remedy.
+This pragma turns on the -w mode, but gives you much better diagnostics of
+the errors and warnings encountered. Generally it explains the reason for
+warnings/errors you get, shows you an example of code where the same kind
+of warning is being triggered, and tells you the remedy.
<P>
-It's a bad idea to keep it in your production code! Since it'll spit
-zillions of diagnostics lines into your error_log file. And it'll add
-significant overhead to the cgi's runtime. (I discovered this by using
+Again, it's a bad idea to keep this in your production code, as it will
+spit zillions of diagnostics lines into your error_log file. Also, it will
+add significant overhead to the CGI's runtime. (I discovered this by using
Devel::DProf!)
<P>
@@ -641,12 +686,9 @@
<CENTER><H2><A NAME="Global_Variables">Global Variables</A></H2></CENTER>
<P>
It's always a good idea to stay away from global variables when possible.
-Some variables must be global so Perl can see them, such as a module's
-<CODE>@ISA</CODE> or <CODE>$VERSION</CODE> variables. In common practice, a
-combination of use strict and use vars keeps modules clean and reduces a
-bit of noise. However, use vars also creates aliases as the Exporter does,
-which eat up more space. When possible, try to use fully qualified names
-instead of use vars. Example:
+Some variables must be global so Perl can see them, such as a module's <STRONG>@ISA</STRONG> or
+<STRONG>$VERSION</STRONG> variables. In common practice, a combination of <STRONG>use strict</STRONG> and <STRONG>use vars</STRONG> keeps modules clean and reduces a bit of noise. However, <STRONG>use vars</STRONG> also creates aliases as the Exporter does, which eat up more space. When
+possible, try to use fully qualified names instead of use vars. Example:
<P>
<PRE> package MyPackage;
@@ -655,8 +697,8 @@
$MyPackage::VERSION = "1.00";
</PRE>
<P>
-<PRE> vs.
-</PRE>
+vs.
+
<P>
<PRE> package MyPackage;
use strict;
@@ -665,27 +707,30 @@
$VERSION = "1.00";
</PRE>
<P>
+Also see <A HREF="././perl.html#Using_global_variables_and_shari">Using global variables and sharing them</A>
+
+
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Code_has_been_changed_but_seems">Code has been changed, but seems that script uses the old code</A></H2></CENTER>
+<CENTER><H2><A NAME="Code_has_been_changed_but_it_se">Code has been changed, but it seems the script is running the old code</A></H2></CENTER>
<P>
-Files pulled in via use or require statements are not automatically
-reloaded when changed on disk. See <A HREF="././obvious.html#Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A> for more info.
+Files pulled in via <STRONG>use</STRONG> or <STRONG>require</STRONG> statements are not automatically reloaded when changed on disk. See <A HREF="././obvious.html#Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A> for more info.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Memory_leakages">Memory leakages</A></H2></CENTER>
+<CENTER><H2><A NAME="Memory_leakage">Memory leakage</A></H2></CENTER>
<P>
Scripts under mod_perl can very easily leak memory! Global variables stay
-around indefinitely, lexical variables (declared with <Cmy()> are
-destroyed when they go out of scope, provided there are no references to
-them from outside of that scope.
+around indefinitely, lexical variables (declared with <CODE>my()</CODE> are destroyed when they go out of scope, provided there are no references
+to them from outside of that scope.
<P>
-Perl doesn't return back the memory it acquired from the kernel. It does
-reuse it so!
+Perl doesn't return the memory it acquired from the kernel. It does reuse
+it though!
<P>
-<STRONG>First example</STRONG> is file reading:
+<STRONG>First example</STRONG> demonstrates reading a file:
<P>
<PRE> open IN, $file or die $!;
@@ -694,40 +739,43 @@
close IN;
</PRE>
<P>
-If you file is of a 5Mb - The child who served that script will grow
-exactly by that size. Now if you have 20 children and all of them will
-serve this cgi, all of them will consume additional 20*5M = 100M of RAM! If
-that's the case try to use other approaches of processing the file, if
-possible of course. Try to process line at a time and print it back to the
-file (if you need to modify the file itself, use temporary file for that,
-when finished overwrite the src file, make sure to provide locking
-mechanism!).
+If your file is 5Mb, the child who served that script will grow exactly by
+that size. Now if you have 20 children and all of them will serve this CGI,
+all of them will consume additional 20*5M = 100M of RAM! If that's the
+case, try to use other approaches of processing the file, if possible of
+course. Try to process a line at a time and print it back to the file. (If
+you need to modify the file itself, use a temporary file. When finished,
+overwrite the source file, making sure to provide a locking mechanism!)
<P>
-<STRONG>Second example</STRONG> is copying variables between functions (passing variables by value). Let's
-use the example above. Assuming we have no choice and the whole file had to
-be read before any data processing. Now you have a very nice sub
+<STRONG>Second example</STRONG> demonstrates copying variables between functions (passing variables by
+value). Let's use the example above, assuming we have no choice but to read
+the whole file before any data processing. Now you have a very nice sub
<CODE>process()</CODE> that processes the data and returns it back. What
happens if you pass the <CODE>$content</CODE> by value? You have just
-copied another 5M and the child has grew up up by another 5M in size (watch
-your swap space!) now multiply it again by factor of 10 you have 200M of
-wasted RAM, which will be apparently reused but it's a waste! Whenever you
-think the variable can grow bigger than few Kb pass it by reference! Once I
-wrote the script that passed a content of the little DB to the function and
-it was OK, but then the DB become huge - I had to make a decision, whether
-to buy more memory or to rewrite the code. So it's better to plan ahead and
-pass the variables by reference. There are few approaches for that:
+copied another 5M and the child has grown by another 5M in size (watch your
+swap space!) now multiply it again by factor of 20 you have 200M of wasted
+RAM, which will be apparently reused but it's a waste! Whenever you think
+the variable can grow bigger than few Kb, pass it by reference!
+
+<P>
+Once I wrote the script that passed a content of the little DB to the
+function and it was OK, but then the DB become huge - I had to make a
+decision, whether to buy more memory or to rewrite the code. So it's better
+to plan ahead and pass the variables by reference. There are few approaches
+for that:
<P>
<PRE> sub process{
my $content_r = shift;
- ... some processing on $$content here ($$var_r - dereference the scalar)
- [nothing returned - the variable $content outside is already changed
+ ... some processing on $$content here
+ ($$var_r - dereference the scalar)
+ [nothing returned - the variable $content
+ outside is already changed]
}
process(\$content);
-</PRE>
-<P>
-<PRE> @{$var_lr} - dereference an array
+
+ @{$var_lr} - dereference an array
%{$var_hr} = dereference a hash
</PRE>
<P>
@@ -736,14 +784,16 @@
<P>
-Other approach would be to use directly the <CODE>@_</CODE> variable. Using
-directly the <CODE>@_</CODE> array serves the job of passing by reference!
+Another approach would be to directly use the <CODE>@_</CODE> variable.
+Using directly the <CODE>@_</CODE> array serves the job of passing by
+reference!
<P>
<PRE> sub process{
$_[0] =~ s/A/a/gs;
- ... some processing on $_[0] here
- [nothing returned - the variable $content outside is already changed
+ ... some processing on $_[0] here
+ [nothing returned - the variable $content
+ outside is already changed]
}
process($content);
</PRE>
@@ -751,18 +801,18 @@
From <CODE>perldoc perlsub</CODE>: The array <CODE>@_</CODE> is a local array, but its elements are aliases
for the actual scalar parameters. In particular, if an element $_[0] is
updated, the corresponding argument is updated (or an error occurs if it is
-not possible to update)....
+not possible to update)...
<P>
-<STRONG>Third example</STRONG> is work with DataBases. If you do some DB processing, many times you have
-lots of records that you read into you program, and then print them to the
-browser after they were formatted. (I even don't mention the horrible case
-where programmers read in the whole DB and then let the perl to process
-it!!! Use relational DB and let the SQL do the job, so you get only the
-records you need!!!).
+<STRONG>Third example</STRONG> demonstrates work with DataBases. If you do some DB processing, many times
+you encounter the need to read lots of records into your program, and then
+print them to the browser after they are formatted. (I don't even mention
+the horrible case where programmers read in the whole DB and then use perl
+to process it!!! Use a relational DB and let the SQL do the job, so you get
+only the records you need!!!).
<P>
-We will use DBI for that (assume we are already connected to the DB) (read
+We will use DBI for this (assume we are already connected to the DB) (read
perldoc DBI for complete info):
<P>
@@ -775,14 +825,15 @@
<P>
In the example above the httpd_process will grow up by the size of the
variables that have been allocated for the records that matched the query.
-(Again remember to multiply it by the number of the children server runs!).
+(Again remember to multiply it by the number of the children your server
+runs!).
<P>
-What you want to do is to not accumulate the records but print them as they
-are fetched from the DB. More over we use a bind_col and
-$sth->fetchrow_arrayref (aliased to $sth->fetch) methods, to get the
-the fastest way to fetch data. The example below prints the TABLE with
-matched data, the only memory that is being used is a @cols.
+A better approach is to not accumulate the records, but rather print them
+as they are fetched from the DB. Moreover, we use the <STRONG>bind_col</STRONG>
+and <STRONG>$sth->fetchrow_arrayref</STRONG> (aliased to <STRONG>$sth->fetch</STRONG>) methods, to fetch the data in the fastest possible way. The example below
+prints the TABLE with matched data, the only memory that is being used is a
+@cols.
<P>
<PRE> my @select_fields = qw(a b c);
@@ -795,21 +846,20 @@
$sth->bind_columns(undef,\(@cols));
print "<TABLE>";
while($sth->fetch) {
- print "<TR>";
- print map { "<TD>$_</TD>" } @cols;
- print "</TR>";
+ print "<TR>",
+ map("<TD>$_</TD>", @cols),
+ "</TR>";
}
print "</TABLE>";
</PRE>
<P>
-Note: the above method doesn't allow you to know how many records has been
+Note: the above method doesn't allow you to know how many records have been
matched. The workaround is to run an identical query before the code above
-where you use 'SELECT <CODE>count(*)</CODE> ...' instead of 'SELECT * ...',
-so you get the number of matched records.
+where you use <STRONG>SELECT count(*) ...</STRONG> instead of <STRONG>'SELECT *
+...</STRONG> to get the number of matched records.
<P>
-For those who think that $sth->rows will do the job, here is the quote
-from the DBI manpage:
+For those who think that <STRONG>$sth->rows</STRONG> will do the job, here is the quote from the DBI manpage:
<BLOCKQUOTE>
@@ -832,9 +882,9 @@
</BLOCKQUOTE>
<P>
-Just as a bonus, I wanted to write a single sub that process any query but
-very flexible, since it accepts: conditions, callback closure sub, select
-fields and restrictions.
+As a bonus, I wanted to write a single sub that flexibly processes any
+query, accepting: conditions, callback closure sub, select fields and
+restrictions.
<P>
<PRE> # $o->dump(\%conditions,\&callback_closure,\@select_fields,@restrictions)
@@ -844,36 +894,29 @@
my $rsub = shift;
my @select_fields = @{+shift}; # dereference list
my @restrict = shift || '';
-</PRE>
-<P>
-<PRE> # create a list of cols values
+
+ # create a list of cols values
my @cols = ();
@cols[0..$#select_fields] = ();
-</PRE>
-<P>
-<PRE> my $do_sql = '';
+
+ my $do_sql = '';
my @where = ();
-</PRE>
-<P>
-<PRE> # make a @where list
+
+ # make a @where list
map { push @where, "$_=\'$param{$_}\'" if $param{$_};} keys %param;
-</PRE>
-<P>
-<PRE> # prepare the sql statement
+
+ # prepare the sql statement
$do_sql = "SELECT ";
$do_sql .= join(" ", @restrict) if @restrict;# append the restriction list
$do_sql .= " " .join(",", @select_fields) ; # append the select list
$do_sql .= " FROM $DBConfig{TABLE} "; # from table
-</PRE>
-<P>
-<PRE> # we will not add the WHERE clause if @where is empty
+
+ # we will not add the WHERE clause if @where is empty
$do_sql .= " WHERE " . join " AND ", @where if @where;
-</PRE>
-<P>
-<PRE> print "SQL: $do_sql \n" if $debug;
-</PRE>
-<P>
-<PRE> $dbh->{RaiseError} = 1; # do this, or check every call for errors
+
+ print "SQL: $do_sql \n" if $debug;
+
+ $dbh->{RaiseError} = 1; # do this, or check every call for errors
$sth = $dbh->prepare($do_sql);
$sth->execute;
# Bind perl variables to columns.
@@ -881,36 +924,38 @@
while($sth->fetch) {
&$rsub(@cols);
}
- # print the tail or "no records found" message according to the previous calls
+ # print the tail or "no records found" message
+ # according to the previous calls
&$rsub();
-</PRE>
-<P>
-<PRE> } # end of sub dump
+
+ } # end of sub dump
</PRE>
<P>
Now a callback closure sub can do lots of things. We need a closure to know
-what stage are we in: header, body or tail. For example a callback closure
-for formatting the rows we want to print:
+what stage are we in: header, body or tail. For example, we want a callback
+closure for formatting the rows to print:
<P>
<PRE> my $rsub = eval {
- # make a copy of @fields list, since it might go out of scope when this closure will be called
+ # make a copy of @fields list, since it might go
+ # out of scope when this closure will be called
my @fields = @fields;
my @query_fields = qw(user dir tool act); # no date field!!!
my $header = 0;
my $tail = 0;
my $counter = 0;
my %cols = (); # columns name=> value hash
-</PRE>
-<P>
-<PRE> # Closure with the following behavior:
- # 1. Header's code will be executed on the first call only and if @_ was set
+
+ # Closure with the following behavior:
+ # 1. Header's code will be executed on the first call only and
+ # if @_ was set
# 2. Row's printing code will be executed on every call with @_ set
- # 3. Tail's code will be executed only if Header's code was printed and @_ isn't set
- # 4. "No record found" code will be executed if Header's code wasn't executed
-</PRE>
-<P>
-<PRE> sub {
+ # 3. Tail's code will be executed only if Header's code was
+ # printed and @_ isn't set
+ # 4. "No record found" code will be executed if Header's code
+ # wasn't executed
+
+ sub {
# Header
if (@_ and !$header){
print "<TABLE>\n";
@@ -936,24 +981,65 @@
unless ($header){
print $q->p($q->center($q->b("No record was found!\n")));
}
+
+ } # end of sub {}
+ }; # end of my $rsub = eval {
</PRE>
<P>
-<PRE> } # end of sub {}
- }; # end of my $rsub = eval {
+You might also want to check <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>
+and <A HREF="././performance.html#Limiting_the_resources_used_by_h">Limiting the resources used by httpd children</A>.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Filehandlers_and_locks_leakages">Filehandlers and locks leakages</A></H1></CENTER>
+<P>
+At the beginning there was:
+
+<P>
+<PRE> open IN, "in.txt" or die "Cannot open in.txt for reading : $!\n";
</PRE>
<P>
-You might want to check also <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>
- and <A HREF="././performance.html#Limiting_the_resources_used_by_h">Limiting the resources used by httpd children</A>.
+But it was not perfect for mod_perl, since you have had to make sure you
+do:
<P>
+<PRE> close IN;
+</PRE>
+<P>
+somewhere before the end of the script, since if you do not, you will get a
+file descriptor leakage and unlock problem. Even if you do have it, but for
+some reason the interpreter did not make it to it, because of various
+reasons, such as user aborted script (<A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>) the leakage is still there.
+
+<P>
+What do we do? We use <CODE>IO::File</CODE> (and other <CODE>IO::*</CODE>), which allows us to assign the filehandler to variable, which can be <CODE>my()</CODE>
+scoped. And when this variable goes out of scope the file or other
+filesystem entity will be preperly closed and unlocked (if was locked).
+
+<P>
+<PRE> {
+ my $fh = new IO::File("filename") or die $!;
+ # read from $fh
+ } # ...$fh is closed automatically at end of block, without leaks.
+</PRE>
+<P>
+But even faster and lighter technique is to use <CODE>Symbol.pm</CODE>:
+
+<P>
+<PRE> {
+ my $fh = Symbol::gensym();
+ open $fh, "filename" or die $!
+ }
+</PRE>
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Sometimes_it_works_Sometimes_Not">Sometimes it works Sometimes Not (Very important!)</A></H2></CENTER>
+<CENTER><H2><A NAME="Sometimes_it_Works_Sometimes_Not">Sometimes it Works Sometimes Not (Very important!)</A></H2></CENTER>
<P>
-When you start running the scripts under mod_perl you might find yourself
-in situation that scripts seems to work, but sometimes it screws up. And
-the more it runs without restart the more it screws up. Many times you can
-resolve this problem very easily. You have to test your script under with
-Server running as a
+When you start running your scripts under mod_perl, you might find yourself
+in situation where a script seems to work, but sometimes it screws up. And
+the more it runs without a restart, the more it screws up. Many times you
+can resolve this problem very easily. You have to test your script under
+with Server running as a
<A HREF="././control.html#Single_Mode_Running">single process</A>.
<P>
@@ -962,21 +1048,21 @@
change it, you can find your scripts do ``fancy'' things.
<P>
-The first example is amazing. Web Services. Imagine that you enter some
+The first example is amazing -- Web Services. Imagine that you enter some
site you have your account on (Free Email Account?). Now you want to see
what other users read.
<P>
-You type in your name and passwd, and you are expecting to enter to your
-account, but instead to enter the account of someone else. This is cool
-isn't it? Is it a bug or feature. (For some of us it's a feature, while for
-others it's a bug :( You say, why in the world this happens? The answer is
+You type in your name and passwd, and you expect to enter to your account,
+but instead you enter the account of someone else. This is cool isn't it?
+Is it a bug or feature. (For some of us it's a feature, while for others
+it's a bug.) You say, why in the world does this happen? The answer is
simple: Global Variables. You have entered the account of someone who
-happened to be served by the same server child as you, because of the
-sloppiness programming, the global variable was not reset at the beginning
-of the program and voila you can easily peek into other people emails! You
-would ask it can't happen, since you have entered the login and passwd. I
-tell you, it happens! See for yourself:
+happened to be served by the same server child as you. Because of sloppy
+programming, a global variable was not reset at the beginning of the
+program and voila, you can easily peek into other people's emails! You
+would think that it can't happen, since you have entered the login and
+passwd. I tell you, it happens! See for yourself:
<P>
<PRE> use vars ($authenticated);
@@ -988,27 +1074,24 @@
die "Wrong passwd" unless $authenticated == 1;
# user is OK, fetch user's data
show_user($username);
-</PRE>
-<P>
-<PRE> sub authenticate{
+
+ sub authenticate{
my ($username,$passwd) = @_;
# some checking
$authenticated = 1 if (SOMETHING);
}
</PRE>
<P>
-Do you see the catch? I can type in any valid username and any dummy passwd
-and enter that's user account, with the code above if someone has
+Do you see the catch? With the code above, I can type in any valid username
+and any dummy passwd and enter that user's account, if someone has
successfully entered his account before me using the same child process!
-Since <CODE>$authenticated</CODE> is global - if it becomes 1 once it'll be
-1 for the whole child's life!!! The solution is trivial - reset the
-<CODE>$authenticated</CODE> to 0 at the beginning of the program. (Or many
-other different solutions). Of course the example is too trivial - but
-believe me it happens!
+Since <STRONG>$authenticated</STRONG> is global - if it becomes 1 once it'll be 1 for the remainder of the
+child's life!!! The solution is trivial -- reset <STRONG>$authenticated</STRONG> to 0 at the beginning of the program. (Or many other different solutions).
+Of course this example is trivial -- but believe me it happens!
<P>
-Just another little one liner that can make your day spoiled, assuming you
-forgot to reset the $allowed. It's perfectly OK in plain mod_cgi:
+Just another little one liner that can spoil your day, assuming you forgot
+to reset the <STRONG>$allowed</STRONG> variable. It works perfectly OK in plain mod_cgi:
<P>
<PRE> $allowed = 1 if $username eq 'admin';
@@ -1018,17 +1101,18 @@
assuming you have used the same child prior to some user request).
<P>
-Another good example is usage of /o in regexp. After you restart the server
-most likely you will not detect the problem, if on every request you will
-use a different pattern that will be used in regexp and it'll happen that
-each time a different child will serve the new request. Only arriving to
-the child who has already cached the regexp will reveal the problem, but
-generally you miss that and when you press reload - You see that it works
-(new fresh child) and then it doesn't (child that already cached the regexp
-and wouldn't recompile because of /o).
+Another good example is usage of the <STRONG>/o</STRONG> regular expression qualifier, which compiles a regular expression once, on
+its first execution. This problem can be difficult to detect, as after
+restarting the server each request you make will be served by a different
+child process, and thus the regex pattern for that child will be compiled
+fresh. Only when you make a request that happens to be served by a child
+which has already cached the regexp will you see the problem. Generally you
+miss that and when you press reload, you see that it works (with a new,
+fresh child) and then it doesn't (with a child that already cached the
+regexp and wouldn't recompile because of <STRONG>/o</STRONG>.)
<P>
-So to make sure you don't miss these bugs always test your CGI in
+To make sure you don't miss these bugs always test your CGI in
<A HREF="././control.html#Single_Mode_Running">single process</A>. To solve this particular <STRONG>/o</STRONG> problem refer to <A HREF="././obvious.html#Compiled_Regular_Expressions">Compiled Regular Expressions</A>.
<P>
@@ -1038,16 +1122,15 @@
You still can win from using mod_perl.
<P>
-One approach it to replace the Apache::Registry handler with
-Apache::PerlRun and defined a new location (the script can reside in the
+One approach is to replace the Apache::Registry handler with
+Apache::PerlRun and define a new location (the script can reside in the
same directory on the disk.
<P>
<PRE> # srm.conf
Alias /cgi-perl/ /home/httpd/cgi/
-</PRE>
-<P>
-<PRE> # httpd.conf
+
+ # httpd.conf
<Location /cgi-perl>
#AllowOverride None
SetHandler perl-script
@@ -1081,24 +1164,23 @@
write scripts that run under CGI or mod_perl without any change. Unlike
Apache::Registry, the Apache::PerlRun handler does not cache the script
inside of a subroutine. Scripts will be ``compiled'' on each request. After
-the script has run, it's namespace is flushed of all variables and
+the script has run, its namespace is flushed of all variables and
subroutines. Still, you don't have the overhead of loading the perl and
compilation time of the standard modules (If your script is very light, but
uses lots of standard modules - you will see no difference between
Apache::PerlRun and Apache::Registry !).
<P>
-Be aware though, that if you use some packages that use internals variables
-that has circular references, they will be not flushed!!!
+Be aware though, that if you use packages that use internal variables that
+have circular references, they will be not flushed!!!
<P>
Apache::PerlRun only flushes your script's namespace, which does not
-include any other required package's namespace. If there's a reference to
-<CODE>my()</CODE> scoped variable that's keeping it from being DESTROYed
-after leaving the eval scope (of Apache::PerlRun), that cleanup might not
-be taken care of until the server is shutdown and
-<CODE>perl_destruct()</CODE> is run, which always happens after running
-command line scripts. Consider this example:
+include any other required packages' namespaces. If there's a reference to
+a <STRONG>my()</STRONG> scoped variable that's keeping it from being DESTROYed after leaving the
+eval scope (of Apache::PerlRun), that cleanup might not be taken care of
+until the server is shutdown and <CODE>perl_destruct()</CODE> is run, which
+always happens after running command line scripts. Consider this example:
<P>
<PRE> package Foo;
@@ -1106,16 +1188,14 @@
sub DESTROY {
warn "Foo->DESTROY\n";
}
-</PRE>
-<P>
-<PRE> eval <<'EOF';
+
+ eval <<'EOF';
package my_script;
my $self = Foo->new;
#$self->{circle} = $self;
EOF
-</PRE>
-<P>
-<PRE> print $@ if $@;
+
+ print $@ if $@;
print "Done with script\n";
</PRE>
<P>
@@ -1155,7 +1235,7 @@
to see the error message, but I want it to be emailed to me if it's severe
enough. The handler traps various errors and performs accordingly to the
defined logic. My handler was written for the modperl environment, but
-works correctly when is being called from the shell. A stipped version of
+works correctly when is being called from the shell. A stripped version of
the code is shown here:
<P>
@@ -1265,9 +1345,10 @@
</PRE>
<P>
-You have noticed that I trap the CGI.pm's <CODE>die()</CODE> calls here, I
-don't see any reason why my users should see an ugly error messages, but
-that's the way CGI.pm written. The workaround was to trap them myself.
+You may have noticed that I trap the CGI.pm's <CODE>die()</CODE> calls
+here, I don't see any reason why my users should see an ugly error
+messages, but that's the way CGI.pm written. The workaround is to trap them
+myself.
<P>
Please note that as of ver 2.49, CGI.pm provides a <CODE>cgi_error()</CODE>
@@ -1288,7 +1369,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/16/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
1.9 +150 -37 modperl-site/guide/scenario.html
Index: scenario.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/scenario.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- scenario.html 1999/03/16 08:20:23 1.8
+++ scenario.html 1999/04/03 20:33:52 1.9
@@ -7,6 +7,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -27,7 +35,9 @@
<LI><A HREF="#httpd_perl_Server_mod_perl_">httpd_perl Server (mod_perl):</A>
</UL>
+ <LI><A HREF="#More_mod_perl_deploying_schemas">More mod_perl deploying schemas</A>
<LI><A HREF="#Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A>
+ <LI><A HREF="#Is_it_possible_to_determine_whic">Is it possible to determine which options were given to modperl's Makefile.PL</A>
</UL>
<!-- INDEX END -->
@@ -36,12 +46,12 @@
<CENTER><H1><A NAME="Making_a_Strategic_Decision">Making a Strategic Decision</A></H1></CENTER>
<P>
When running your scripts under mod_perl, you will notice that the httpd
-processes consume a huge amount of memory, from 5M to 25M and more. That's
+processes consume a huge amount of memory, from 5M to 25M and more. That is
the price you pay for the great speed improvements under mod_perl -- the
-function of Perl has has embedded in the Apache server binary.
+function of Perl embedded in the Apache server binary.
<P>
-It's overkill to serve the static objects like images and html docs with
+It is overkill to serve the static objects like images and html docs with
these larger processes. The best approach is to run two servers: a light
Apache server with no mod_perl compiled in serving the static pages, and a
heavy Apache/mod_perl server serving the CGIs in mod_perl mode only. This
@@ -53,11 +63,14 @@
Since we run two apache servers we will need two different configuration
files, log files and etc. We need a special directory layout. While some of
the directories can be shared between the two servers (assuming that both
-are built from the same source distribution) others should be separated.
-We'll refer to these two servers as <STRONG>httpd_docs</STRONG>
-(vanilla Apache) and <STRONG>httpd_perl</STRONG> (Apache/mod_perl).
+are built from the same source distribution) others should be separated. We
+will refer to these two servers as <STRONG>httpd_docs</STRONG> (vanilla Apache) and <STRONG>httpd_perl</STRONG>
+(Apache/mod_perl).
<P>
+Of course there are more ways to use mod_perl. Please read <A HREF="././scenario.html#More_mod_perl_deploying_schemas">More mod_perl deploying schemas</A>.
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Deciding_on_a_Directory_Layout">Deciding on a Directory Layout</A></H1></CENTER>
<P>
@@ -104,15 +117,15 @@
drwxr-xr-x 8 stas stas 2048 Oct 29 17:38 modperl-1.16/
</PRE>
<P>
-Time to decide one the desired directory structure layout (where the apache
-files go):
+Time to decide on the desired directory structure layout (where the apache
+files go):
<P>
-<PRE> ROOT = /usr/apps
+<PRE> ROOT = /usr/apps
</PRE>
<P>
The two servers can share the following directories (so we will not
-duplicate data):
+duplicate data):
<P>
<PRE> /usr/apps/bin/
@@ -130,13 +143,11 @@
<P>
<PRE> /usr/apps/etc/httpd_docs/
httpd_perl/
-</PRE>
-<P>
-<PRE> /usr/apps/sbin/httpd_docs/
+
+ /usr/apps/sbin/httpd_docs/
httpd_perl/
-</PRE>
-<P>
-<PRE> /usr/apps/var/httpd_docs/logs/
+
+ /usr/apps/var/httpd_docs/logs/
proxy/
run/
httpd_perl/logs/
@@ -158,15 +169,12 @@
<P><DT><STRONG><A NAME="item_Configuration">Configuration</A></STRONG><DD>
<P>
<PRE> % cd /usr/apps/usr/src/httpd_docs/apache_1.3.2
-</PRE>
-<P>
-<PRE> % make clean
-</PRE>
-<P>
-<PRE> # gcc - compiles httpd by 100K+ smaller on AIX!
-</PRE>
-<P>
-<PRE> % env CC=gcc \
+
+ % make clean
+
+ # gcc - compiles httpd by 100K+ smaller on AIX!
+
+ % env CC=gcc \
./configure --prefix=/usr/apps \
--sbindir=/usr/apps/sbin/httpd_docs \
--sysconfdir=/usr/apps/etc/httpd_docs \
@@ -183,11 +191,10 @@
<P><DT><STRONG><A NAME="item_Compilation">Compilation:</A></STRONG><DD>
<P>
<PRE> % make
+
+ % make install
</PRE>
<P>
-<PRE> % make install
-</PRE>
-<P>
Rename 'httpd' to 'http_docs'
<P>
@@ -198,7 +205,8 @@
favorite text editor or by using perl)
<P>
-<PRE> % perl -p -i -e 's|httpd_docs/httpd|httpd_docs/httpd_docs|' /usr/apps/sbin/httpd_docs/apachectl
+<PRE> % perl -p -i -e 's|httpd_docs/httpd|httpd_docs/httpd_docs|' \
+ /usr/apps/sbin/httpd_docs/apachectl
</PRE>
</DL>
<P>
@@ -206,12 +214,13 @@
<CENTER><H2><A NAME="httpd_perl_Server_mod_perl_">httpd_perl Server (mod_perl):</A></H2></CENTER>
<P>
Before you start to configure the mod_perl sources, you should be aware
-that there a few Perl modules that have to be installed before building
-mod_perl. You will be alerted of any missing required when you run the
-<CODE>perl Makefile.PL</CODE> command line below. If you discover that you don't have these, go to your
+that there are a few Perl modules that have to be installed before building
+mod_perl. You will be alerted if any required modules are missing when you
+run the <CODE>perl Makefile.PL</CODE> command line below. If you discover that you do not have these, go to your
nearest CPAN repository (if you don't know what is it, go to <A
HREF="http://www.perl.com/CPAN">http://www.perl.com/CPAN</A> ) or run the
-CPAN interactive shell via the command line <CODE>perl -MCPAN -e shell</CODE> .
+CPAN interactive shell via the command line <CODE>perl -MCPAN -e
+shell</CODE> .
<P>
Now back to installation.
@@ -260,14 +269,16 @@
/usr/apps/usr/src/httpd_perl/apache_1.3.2/src/httpd
<P>
-Note: You have noted that we didn't go to the apache's source dir and run <CODE>make install</CODE>. When <CODE>USE_APACI</CODE> is enabled, <CODE>APACHE_PREFIX</CODE> will specify the --prefix option for Apache's configure script, specifying
+Note: You may have noted that we did not go to the apache's source dir and
+run <CODE>make install</CODE>. When <CODE>USE_APACI</CODE> is enabled,
+<CODE>APACHE_PREFIX</CODE> will specify the --prefix option for Apache's configure script, specifying
the installation path for Apache. When this option is used, mod_perl's make
install will also make install on the Apache side, installing the httpd
binary, support tools, along with the configuration, log and document
trees.
<P>
-If make test fails, look into t/logs and see what's in there.
+If make test fails, look into t/logs and see what is in there.
<P>
Rename the 'httpd' to 'httpd_perl'
@@ -280,13 +291,82 @@
by using perl)
<P>
-<PRE> % perl -p -i -e 's|httpd_perl/httpd|httpd_perl/httpd_perl|' /usr/apps/sbin/httpd_perl/apachectl
+<PRE> % perl -p -i -e 's|httpd_perl/httpd|httpd_perl/httpd_perl|' \
+ /usr/apps/sbin/httpd_perl/apachectl
</PRE>
<P>
Now proceed to the <A HREF="././config.html#">Server Configuration</A> section.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="More_mod_perl_deploying_schemas">More mod_perl deploying schemas</A></H1></CENTER>
+<P>
+There are several different ways to build, configure and deploy your
+mod_perl enabled site. Some of the ways are:
+
+<OL>
+<P><LI>
+<P>
+1 binary and 1 config file (suffer a big binary for all kind of objects)
+
+<P><LI>
+<P>
+2 binaries and 2 config files (one big binary for mod_perl and one small
+for static object like images)
+
+<P><LI>
+<P>
+1 DSO style compile and 2 confs (Dynamic linking lets you compile once and
+have a big and a small binary in memory BUT you have to deal with a freshly
+made solution that has week documentation and is still subject to change
+and is rather more complex)
+
+<P><LI>
+<P>
+Any of the 3 approaches above plus proxy server in the http accelerator
+mode (squid was reported to be the best as of this writing).
+
+<P>
+<META> The proxy section should be added shortly. I am still trying
+to figure out how to ride the beast. If you have the experience with squid,
+your contributions are very important and welcome.</META>
+
+</OL>
+<P>
+If you are a newbie, I would recommend you to start with the first option
+and work on getting your feet wet with apache and mod_perl, then decide
+whether to move to a second one for production work or move up to the more
+state-of-the-art-yet-suspiciously-new DSO system (third) )or/and proven to
+be good forth option from above.
+
+<P>
+Option 1 will kill you in production if you load out a lot of static data
+with a 2-12 MB webserver process. On the other hand while testing you will
+have no other server interaction to mask or add to your errors.
+
+<P>
+Option 2 means keeping two compiles but lets you seriously tune the two
+binaries to their exact purpose. On the other hand you have to deal with
+proxying or fancy site design to keep the two servers in step. Choose
+serving on multiple ports, multiple IPs, etc...
+
+<P>
+Option 3 (DSO) -- as mentioned above -- means playing with the bleeding
+edge. Also the <CODE>mod_so</CODE> adds size and complexity to your binaries. The benefit being that modules
+can be added and removed with out recompiling and even shared amongst
+multiple servers. Again, it is bleeding edge and still sort of platform
+wonky so YMMV.
+
+<P>
+<META> Does anyone want to write a section for DSO? </META>
+
+<P>
+Option 4 (proxy in http accelerator mode) - should make you lots of good
+things, once correctly configured and tuned. Stay tuned for more
+information.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A></H1></CENTER>
<P>
Yes, no problem with that. Follow the instructions above and when you
@@ -331,6 +411,39 @@
<P>
<STRONG>c</STRONG>. Look for another ISP with lots of resources or one that supports mod_perl
(not likely)
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Is_it_possible_to_determine_whic">Is it possible to determine which options were given to modperl's Makefile.PL</A></H1></CENTER>
+<P>
+It is possible to determine which options were given to modperl's
+Makefile.PL during the configuration stage, so to be used later in
+recreating the same build tree when rebuilding the server. This is relevant
+only if did not use the default config parameters and altered some of them
+during the configuration stage.
+
+<P>
+I was into this problem many times. I'm going to build something pass some
+non default parameters to the config script and then later when I need to
+rebuild the tool either to upgrade it or to make an indentical copy at some
+other machine, I have found that I do not remember what parameters did I
+altered.
+
+<P>
+The best solution for this problem is to prepare the run file with all the
+parameters that are about to be used and then run it instead of typing it
+all by hand. So later I will have the script handy to be reused.
+
+<P>
+mod_perl suggests using the <CODE>makepl_args.mod_perl</CODE> file which comes with mod_perl distribution. This is the file you specify
+all the parameters you are going to use.
+
+<P>
+But if you have found yourself with a compiled tool and no traces of the
+specified parameters left, you can still find them out if the sources were
+not <CODE>make clean</CODE>'d. So you will find the apache specific parameters in <CODE>apache_x.x.x/config.status</CODE> and modperl's at in
+<CODE>mod_perl_x.xx/apaci/mod_perl.config</CODE>.
+
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P><A HREF="index.html">[Back to the main page]</A></P>
@@ -345,7 +458,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/14/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
1.8 +47 -8 modperl-site/guide/snippets.html
Index: snippets.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/snippets.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- snippets.html 1999/03/16 08:20:24 1.7
+++ snippets.html 1999/04/03 20:33:53 1.8
@@ -7,6 +7,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -22,6 +30,8 @@
<LI><A HREF="#How_to_avoid_printing_the_header">How to avoid printing the header more than once.</A>
<LI><A HREF="#More_on_relative_paths">More on relative paths</A>
<LI><A HREF="#Watching_the_error_log_file_with">Watching the error_log file without telneting to the server.</A>
+ <LI><A HREF="#Accessing_variables_from_the_cal">Accessing variables from the caller's package</A>
+ <LI><A HREF="#Handling_cookies">Handling cookies</A>
</UL>
<!-- INDEX END -->
@@ -33,7 +43,7 @@
wish to change this behavior by setting in config file:
<P>
-<PRE> PerlSendHeader On
+<PRE> PerlSendHeader On
</PRE>
<P>
The safest bet is to use CGI.pm's <CODE>print header();</CODE> method (If you use this, you don't need the above setting)
@@ -74,8 +84,8 @@
this in the code or to use a nice <CODE>FindBin.pm</CODE> package.
<P>
-<PRE> use FindBin qw($Bin);
- use lib $Bin;
+<PRE> use FindBin qw($Bin);
+ use lib $Bin;
# or
open IN, "$Bin/foo.txt";
</PRE>
@@ -136,7 +146,6 @@
$q->end_form,
$q->hr;
-
print($q->b("$error_log doesn't exist!!!")),exit unless -e $error_log;
open LOG, "tail -$counts $error_log|" or die "Can't open tail on $error_log :$!\n";
@@ -183,11 +192,11 @@
? qq{<B><FONT COLOR="$colors{$type}">$context</FONT></B>}
: $context;
}
-
-
-=head1 Accessing variables from the caller's package
</PRE>
<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Accessing_variables_from_the_cal">Accessing variables from the caller's package</A></H1></CENTER>
+<P>
Sometimes you want to access some variables from the caller's package. One
way is to do:
@@ -195,6 +204,36 @@
<PRE> my $caller = caller;
print qq[$caller --- ${"${caller}::var"}];
</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Handling_cookies">Handling cookies</A></H1></CENTER>
+<P>
+Unless you use some well known modules like CGI.pm you can handle the
+cookies yourself.
+
+<P>
+Cookies come in the $ENV{HTTP_COOKIE} variable. You can print the raw
+cookie string as $ENV{HTTP_COOKIE}.
+
+<P>
+This is a fairly well-known bit of code to take cookie values and put them
+into a hash.
+
+<P>
+<PRE> sub getCookies {
+ # cookies are seperated by a semicolon and a space, this will
+ # split them and return a hash of cookies
+ local(@rawCookies) = split (/; /,$ENV{'HTTP_COOKIE'});
+ local(%cookies);
+
+ foreach(@rawCookies){
+ ($key, $val) = split (/=/,$_);
+ $cookies{$key} = $val;
+ }
+
+ return %cookies;
+ }
+</PRE>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P><A HREF="index.html">[Back to the main page]</A></P>
@@ -209,7 +248,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/16/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
1.9 +29 -19 modperl-site/guide/start.html
Index: start.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/start.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- start.html 1999/03/16 08:20:25 1.8
+++ start.html 1999/04/03 20:33:53 1.9
@@ -7,6 +7,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -18,7 +26,7 @@
<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
- <LI><A HREF="#Coverage">Coverage </A>
+ <LI><A HREF="#Coverage">Coverage</A>
<LI><A HREF="#Downloading_the_needed_component">Downloading the needed components.</A>
<UL>
@@ -39,7 +47,7 @@
<UL>
<LI><A HREF="#Testing_by_checking_the_error_lo">Testing by checking the error_log file</A>
- <LI><A HREF="#Testing_by_viewing_perl_status">Testing by viewing /perl-status </A>
+ <LI><A HREF="#Testing_by_viewing_perl_status">Testing by viewing /perl-status</A>
<LI><A HREF="#Testing_via_telnet">Testing via telnet</A>
<LI><A HREF="#Testing_via_a_CGI_script">Testing via a CGI script</A>
<LI><A HREF="#Testing_via_lwp_request">Testing via lwp-request</A>
@@ -75,28 +83,28 @@
Perl is most likely already installed on your machine, but you should at
least check the version you using. It is highly recommended that you have
at least perl version 5.004 or higher. You can get the latest perl version
-from <A HREF="http://www.perl.com/.">http://www.perl.com/.</A> Try the
+from <A HREF="http://www.perl.com/">http://www.perl.com/</A> . Try the
direct download link <A
-HREF="http://www.perl.com/pace/pub/perldocs/latest.html.">http://www.perl.com/pace/pub/perldocs/latest.html.</A>
-
+HREF="http://www.perl.com/pace/pub/perldocs/latest.html">http://www.perl.com/pace/pub/perldocs/latest.html</A>
+.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Apache_Download">Apache Download</A></H2></CENTER>
<P>
Get the latest apache webserver from <A
-HREF="http://www.apache.org.">http://www.apache.org.</A> Try the direct
+HREF="http://www.apache.org">http://www.apache.org</A> . Try the direct
download link <A
-HREF="http://www.apache.org/dist/.">http://www.apache.org/dist/.</A>
+HREF="http://www.apache.org/dist/">http://www.apache.org/dist/</A> .
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Mod_Perl_Download">Mod_Perl Download</A></H2></CENTER>
<P>
Get the latest mod_perl from <A
-HREF="http://perl.apache.org.">http://perl.apache.org.</A> Try the direct
+HREF="http://perl.apache.org">http://perl.apache.org</A> . Try the direct
download link <A
-HREF="http://perl.apache.org/dist/.">http://perl.apache.org/dist/.</A>
+HREF="http://perl.apache.org/dist/">http://perl.apache.org/dist/</A> .
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -136,7 +144,7 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Mod_Perl">Mod_Perl</A></H2></CENTER>
<P>
-Now we come to the main point of this document.
+Now we come to the main point of this document.
<P>
Here I'll give only a short example of mod_perl installation. You should
@@ -278,8 +286,8 @@
</PRE>
<P>
Now fetch the URL <A
-HREF="http://www.you.com:8080/perl/test.pl.">http://www.you.com:8080/perl/test.pl.</A>
-You should see something like this (part of the output was snipped).
+HREF="http://www.you.com:8080/perl/test.pl">http://www.you.com:8080/perl/test.pl</A>
+. You should see something like this (part of the output was snipped).
<P>
<PRE> SERVER_SOFTWARE Apache/1.3.2 (Unix) mod_perl/1.16_01
@@ -296,8 +304,8 @@
(you'll need to add the perl line #!/bin/perl for the above script) and
fetch <A
HREF="http://www.you.com/cgi-bin/test.pl">http://www.you.com/cgi-bin/test.pl</A>
+.
-
<P>
<PRE> SERVER_SOFTWARE Apache/1.3.2 (Unix)
GATEWAY_INTERFACE CGI/1.1
@@ -332,7 +340,7 @@
<CENTER><H2><A NAME="Testing_via_lwp_request">Testing via lwp-request</A></H2></CENTER>
<P>
Yet another one. Why do I show all these approaches? While here they are
-serving a very simple purpose, they can be helpful in other situations.
+serving a very simple purpose, they can be helpful in other situations.
<P>
Assuming you have the libwww-perl (LWP) package installed (you will need it
@@ -342,7 +350,7 @@
<PRE> % lwp-request -e -d www.site.com
</PRE>
<P>
-Will show you all the headers. (The <CODE>-d</CODE> option disables printing the response content.)
+Will show you all the headers. (The <CODE>-d</CODE> option disables printing the response content.)
<P>
<PRE> % lwp-request -e -d www.site.com | egrep '^Server:'
@@ -354,14 +362,16 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Starting_to_use_the_server">Starting to use the server</A></H1></CENTER>
<P>
-Now you are ready to start writing CGIs. Note here -- you had better start
+Now you are ready to start writing CGIs. Note here -- you better start
writing your scripts with an eye towards making them clean (i.e., <CODE>use strict;</CODE>), and with understanding of the new running environment. You have to learn
-how to write correctly for mod_perl. This is nothing new, the major item to
-remember is that your script won't die after it finishes serving the
+how to write correctly for mod_perl. There is nothing new, the major item
+to remember is that your script would not die after it finishes serving the
request, but will stay in memory and might affect all other scripts running
under the same server process (child). You will read more about it in the
following sections: <A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs</A>
+
+
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P><A HREF="index.html">[Back to the main page]</A></P>
@@ -376,7 +386,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/01/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
1.9 +8 -0 modperl-site/guide/status.html
Index: status.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/status.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- status.html 1999/03/16 08:20:25 1.8
+++ status.html 1999/04/03 20:33:53 1.9
@@ -7,6 +7,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
1.9 +66 -53 modperl-site/guide/warnings.html
Index: warnings.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/warnings.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- warnings.html 1999/03/16 08:20:26 1.8
+++ warnings.html 1999/04/03 20:33:53 1.9
@@ -7,6 +7,14 @@
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
@@ -18,7 +26,7 @@
<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
- <LI><A HREF="#A_general_advice">A general advice </A>
+ <LI><A HREF="#General_Advice">General Advice </A>
<LI><A HREF="#Value_of_x_will_not_stay_shared">Value of $x will not stay shared at - line 5</A>
<LI><A HREF="#Value_of_x_may_be_unavailable_a">Value of $x may be unavailable at - line 5.</A>
<LI><A HREF="#mod_perl_rwrite_returned_1">mod_perl: rwrite returned -1</A>
@@ -40,9 +48,9 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<CENTER><H1><A NAME="A_general_advice">A general advice</A></H1></CENTER>
+<CENTER><H1><A NAME="General_Advice">General Advice</A></H1></CENTER>
<P>
-Using the <CODE>use diagnostics;</CODE> generally helps you to determine the source of the problem and how to solve
+Enabling <CODE>use diagnostics;</CODE> generally helps you to determine the source of the problem and how to solve
it. See <A HREF="././porting.html#diagnostics_pragma">diagnostics pragma</A> for more info.
<P>
@@ -77,10 +85,9 @@
[modperl] process 1234 going to Apache::exit with status...
</PRE>
<P>
-That's the $SIG{PIPE} handler installed by mod_perl/Apache::SIG, called if
-a connection timesout or Client presses the 'Stop' button. It gives you an
-opportunity to make cleanups if the script was aborted in the middle of its
-execution. See <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A> for more info.
+That's the <STRONG>$SIG{PIPE}</STRONG> handler installed by mod_perl/Apache::SIG, called if a connection timesout
+or Client presses the 'Stop' button. It gives you an opportunity to do
+cleanups if the script was aborted in the middle of its execution. See <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A> for more info.
<P>
If your mod_perl version < 1.17 you might get the message in the
@@ -103,8 +110,7 @@
That's a mandatory warning inside Perl. It happens only if you modify your
script and Apache::Registry reloads it. Perl is warning you that the
<CODE>subroutine(s)</CODE> were redefined. It is mostly harmless. If you
-don't like seeing those, just kill -USR2 (graceful restart) apache when you
-modify your scripts.
+don't like seeing those, just <CODE>kill -USR2</CODE> (graceful restart) apache when you modify your scripts.
<P>
<PRE> <META>
@@ -122,8 +128,8 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Global_symbol_foo_requires_ex">Global symbol "$foo" requires explicit package name</A></H1></CENTER>
<P>
-A script below will print a warning like above, moreover it will print the
-whole script as a part of the warning message:
+The script below will print a warning like above, moreover it will print
+the whole script as a part of the warning message:
<P>
<PRE> #!/usr/bin/perl -w
@@ -158,13 +164,12 @@
/lib/perl5/site_perl/5.005/aix/Apache/Constants.pm line 23.
</PRE>
<P>
-The error is simple to fix. When you use <CODE>use strict;</CODE> pragma (and you better do that), all variables should be defined before
-being used.
+The error is simple to fix. When you use the <CODE>use strict;</CODE> pragma (and you should...), all variables should be defined before being
+used.
<P>
-The bad thing is that sometimes the whole script that can be of thousands
-lines is being printed to error_log file as a code that the server has
-tried to <CODE>eval()uate.</CODE>
+The bad thing is that sometimes the whole script (possibly, thousands of
+lines) is printed to error_log file as a code that the server has tried to <STRONG>eval()</STRONG>uate.
<P>
As Doug answered to this question:
@@ -195,47 +200,52 @@
<P>
This problem is caused when, a client drops the connection while httpd is
in the middle of a write, httpd timeout happens, sending a SIGPIPE, and
-Perl in that child is stuck in the middle of it's eval context. This is
+Perl in that child is stuck in the middle of its eval context. This is
fixed by the Apache::SIG module which is called by default. This should not
-happen unless you have code that is messing with $SIG{PIPE}. It's also
-triggered only when you've changed your script on disk and mod_perl is
-trying to reload it.
+happen unless you have code that is messing with <STRONG>$SIG{PIPE}</STRONG>. It's also triggered only when you've changed your script on disk and
+mod_perl is trying to reload it.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Use_of_uninitialized_value_at_e">Use of uninitialized value at (eval 80) line 12.</A></H1></CENTER>
<P>
-If you compile with the experimental PERL_MARK_WHERE=1, it shows you
-``exactly'' where this is happening. many times compiler makes a shift for
-``unknown'' reasons in it's line counter. You can always stuff you code
-with special compiler directives, to reset it's counter to the value you
-will tell. At the beginning of the line you should write (# sticked to the
-leftmost side):
+If you compile with the experimental <STRONG>PERL_MARK_WHERE=1</STRONG>, it shows you ``exactly'' where this is happening. many times compiler
+makes a shift for ``unknown'' reasons in its line counter. You can always
+stuff your code with special compiler directives, to reset its counter to
+the value you will tell. At the beginning of the line you should write (the
+'#' in column 1):
<P>
<PRE> #line 298 myscript.pl
</PRE>
<P>
-(myscript.pl is optional). It specifies the line number of the _following_
-line, not the line the directive is on. You can use a little script to
-stuff every N lines of your code with this directives, but then you will
-have to rerun this script every time you add remove code lines. The script:
+(myscript.pl is optional.) This specifies the line number of the
+<STRONG>following</STRONG> line, not the line the directive is on. You can use a little script to
+stuff every N lines of your code with these directives, but then you will
+have to rerun this script every time you add or remove code lines. The
+script:
<P>
+<PRE> <META>
+ This example was double incrementing $counter.
+ I took the second increment out -- sgr.
+ </META>
+</PRE>
+<P>
<PRE> #!/usr/bin/perl
# Puts Perl line markers in a Perl program for debugging purposes.
# Also takes out old line markers.
die "No filename to process.\n" unless @ARGV;
- my $filename = $ARGV[0];
+ my $filename = $ARGV[0];
my $lines = 100;
open IN, $filename or die "Cannot open file: $filename: $!\n";
- open OUT, ">$filename.marked" or die "Cannot open file: $filename.marked: $!\n";
+ open OUT, ">$filename.marked"
+ or die "Cannot open file: $filename.marked: $!\n";
my $counter = 1;
while (<IN>) {
print OUT "# line $counter\n" unless $counter++ % $gap;
next if $_ =~ /^# line /;
print OUT $_;
- $counter++;
}
close OUT;
close IN;
@@ -260,9 +270,9 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Can_t_load_auto_DBI_DBI_so_">Can't load '.../auto/DBI/DBI.so' for module DBI</A></H1></CENTER>
<P>
-Checkout that all your modules are compiled with the same perl that is
-being compiled into mod_perl. perl5.005 and 5.004 are binary incompatible
-by default.
+Check that all your modules are compiled with the same perl that is being
+compiled into mod_perl. perl 5.005 and 5.004 are not binary compatible by
+default.
<P>
Other known causes of this problem: OS distributions that ship with a
@@ -270,8 +280,8 @@
library are somehow built with different binary compatibility flags.
<P>
-The solution to these problems is to rebuild Perl and extension modules
-from a fresh source tree. Tip for running Perl's Configure script, use the
+The solution to these problems is to rebuild Perl and any extension modules
+from a fresh source tree. Tip for running Perl's Configure script: use the
`-des' flags to accepts defaults and `-D' flag to override certain
attributes:
@@ -305,8 +315,8 @@
<P>
-I've just discovered that the server is not responding and error log filled
-up the remaining space on the file system (about a gig's worth). The
+I've just discovered that my server is not responding and its error log has
+filled up the remaining space on the file system (about a gig's worth). The
error_log includes millions of lines:
<P>
@@ -322,7 +332,7 @@
error, so Perl is stuck in a loop writing that same message to stderr.
<P>
-Perl 5.005+ plus is recommended for it's improved malloc.c and features
+Perl 5.005+ plus is recommended for its improved malloc.c and features
mentioned in mod_perl_traps.pod on by default.
<P>
@@ -330,10 +340,10 @@
<CENTER><H1><A NAME="Out_of_memory_">Out of memory!</A></H1></CENTER>
<P>
If something goes really wrong with your code, Perl may die with an ``Out
-of memory!'' message and or ``Callback called exit''. A common cause of
-this are never-ending loops, deep recursion or calling an undefined
-subroutine. Here's one way to catch the problem: See Perl's INSTALL
-document for this item:
+of memory!'' message and/or ``Callback called exit''. Common causes of this
+are never-ending loops, deep recursion, or calling an undefined subroutine.
+Here's one way to catch the problem: See Perl's INSTALL document for this
+item:
<P>
<PRE> =item -DPERL_EMERGENCY_SBRK
@@ -344,8 +354,8 @@
variable $^M. See perlvar(1) for more details.
</PRE>
<P>
-If you compile with that option and add 'use Apache::Debug level => 4;'
-to your PerlScript, it will allocate the $^M emergency pool and the
+If you compile with that option and add '<CODE>use Apache::Debug level =&gt;
+4;</CODE>' to your PerlScript, it will allocate the $^M emergency pool and the
$SIG{__DIE__} handler will call Carp::confess, giving you a stack trace
which should reveal where the problem is. See the Apache::Resource module
for prevention of spinning httpds.
@@ -376,20 +386,23 @@
the corresponding filesystem path. Most of failures happen when one passes
a file path instead of URI. (A reminder: /home/httpd/perl/test.pl is a file
path, while /perl/test.pl is an URI). In most cases all you have to do is
-to path something that RegistryLoader expects to get - the URI, but there
-are more complex cases, RegistryLoader's man page shows how to handle these
+to pass something that RegistryLoader expects to get - the URI, but there
+are more complex cases. RegistryLoader's man page shows how to handle these
cases as well (watch for the <CODE>trans()</CODE> sub).
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A></H1></CENTER>
<P>
-Not all Perl modules can survive a reload. PerlFreshRestart does nothing
+Not all Perl modules can survive a reload. PerlFreshRestart does not much
more than:
<P>
-while (my($k,$v) = each %INC) { delete $INC{$k}; require $k; }
-
+<PRE> while (my($k,$v) = each %INC) {
+ delete $INC{$k};
+ require $k;
+ }
+</PRE>
<P>
Besides that, it flushes the Apache::Registry cache, and empties any
dynamic stacked handlers (e.g. PerlChildInitHandler).
@@ -412,7 +425,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 03/15/99
+ <BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
1.1 modperl-site/guide/frequent.html
Index: frequent.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>mod_perl guide: Frequent mod_perl problems</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
<style type="text/css">
<!--
@import url(style.css);
-->
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Frequent mod_perl problems</H1>
<HR WIDTH="100%">
<!-- INDEX BEGIN -->
<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Coverage">Coverage</A>
<LI><A HREF="#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>
<LI><A HREF="#Segfaults_caused_by_PerlFreshRes">Segfaults caused by PerlFreshRestart</A>
</UL>
<!-- INDEX END -->
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
<P>
This new document was born because some problems come up so often on the
mailing list that should be stressed in the guide as one of the most
important things to read/beware of. So I have tried to enlist them in this
document. If you think some important problem that is being reported
frequently on the list and covered in the guide but not included below,
please tell.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A></H1></CENTER>
<P>
<A HREF="././obvious.html#my_scoped_variable_in_nested_s">More info</A>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Segfaults_caused_by_PerlFreshRes">Segfaults caused by PerlFreshRestart</A></H1></CENTER>
<P>
<A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P><A HREF="index.html">[Back to the main page]</A></P>
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
<TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
<HR>
</TD>
</TR>
<TR ALIGN=CENTER VALIGN=TOP>
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
<BR>Last Modified at 04/02/99
</FONT>
</B>
</TD>
<TD>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
</TD>
<TD>
<FONT SIZE=-2>
Use of the Camel for Perl is <BR>
a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
and is used by permission.
</FONT>
</TD>
</TR>
</TABLE></CENTER>
</BODY>
</HTML>
1.1 modperl-site/guide/guide-src.tar.gz
<<Binary file>>
1.1 modperl-site/guide/perl.html
Index: perl.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>mod_perl guide: Perl Reference</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
<META NAME="Description" CONTENT="mod_perl,perl,apache">
<META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
<style type="text/css">
<!--
@import url(style.css);
-->
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Perl Reference</H1>
<HR WIDTH="100%">
<!-- INDEX BEGIN -->
<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Coverage">Coverage</A>
<LI><A HREF="#Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A>
<UL>
<LI><A HREF="#Making_the_variables_global">Making the variables global</A>
<LI><A HREF="#Making_the_variables_global_with">Making the variables global with strict pragma On</A>
<LI><A HREF="#Using_Exporter_pm_to_share_globa">Using Exporter.pm to share global variables</A>
<LI><A HREF="#Using_aliasing_perl_feature_to_s">Using aliasing perl feature to share global variables</A>
</UL>
</UL>
<!-- INDEX END -->
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
<P>
This new document was born because some users reluctant to learn perl prior
to jumping into a mod_perl. I will try to cover some of the most frequent
pure perl questions being asked at the list.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A></H1></CENTER>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Making_the_variables_global">Making the variables global</A></H2></CENTER>
<P>
When you first wrote <CODE>$x</CODE> in your code you created a global
variable. It is visible everywhere in the file you have use it. or if
defined it inside a package - it is visible inside this package. But it
will work only if you do not use <CODE>strict</CODE> pragma and you <STRONG>HAVE</STRONG> to use this pragma if you want to run your scripts under mod_perl. Read <A HREF="././porting.html#strict_pragma">Strict pragma</A> to find out why.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Making_the_variables_global_with">Making the variables global with strict pragma On</A></H2></CENTER>
<P>
First you use :
<P>
<PRE> use strict;
</PRE>
<P>
Then you use:
<P>
<PRE> use vars qw($scalar %hash @array);
</PRE>
<P>
Starting from this moment the variables are global in the package you
defined them, if you want to share global variables between packages, here
what you can do.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Using_Exporter_pm_to_share_globa">Using Exporter.pm to share global variables</A></H2></CENTER>
<P>
Assume that you want to share the <CODE>CGI.pm</CODE>'s object (I will use <CODE>$q</CODE>) between your modules. For example you create it in the <CODE>script.pl</CODE>, but want it to be visible in <CODE>My::HTML</CODE>. First - you make <CODE>$q</CODE> global.
<P>
<PRE> script.pl:
----------------
use vars qw($q);
use CGI;
use My::HTML qw($q);
$q = new CGI;
My::HTML::printmyheader();
----------------
</PRE>
<P>
Note that we have imported <CODE>$q</CODE> from <CODE>My::HTML</CODE>. And the <CODE>My::HTML</CODE>
which does the export of <CODE>$q</CODE>:
<P>
<PRE> My/HTML.pm
----------------
package My::HTML;
use strict;
BEGIN {
use Exporter ();
@My::HTML::ISA = qw(Exporter);
@My::HTML::EXPORT = qw();
@My::HTML::EXPORT_OK = qw($q);
}
use vars qw($q);
sub printmyheader{
# Whatever you want to do with $q... e.g.
print $q->header();
}
-------------------
</PRE>
<P>
So the <CODE>$q</CODE> is being shared between the <CODE>My::HTML</CODE> package and the
<CODE>script.pl</CODE>. It will work vice versa as well, if you create the object in the <CODE>My::HTML</CODE> but use it in the <CODE>script.pl</CODE>. You have a true sharing, since if you change <CODE>$q</CODE> in <CODE>script.pl</CODE>, it will be changed in <CODE>My::HTML</CODE> as well.
<P>
What if you need to share <CODE>$q</CODE> between more than 2 packages? For example you want My::Doc to share <CODE>$q</CODE> as well.
<P>
You leave the <CODE>My::HTML</CODE> untouched, modify the script.pl to include:
<P>
<PRE> use My::Doc qw($q);
</PRE>
<P>
And write the <CODE>My::Doc</CODE> exactly like <CODE>My::HTML</CODE> - of course that the content is different :).
<P>
One possible pitfall is when you want to use the <CODE>My::Doc</CODE> in both
<CODE>My::HTML</CODE> and <CODE>script.pl</CODE>. Only if you add:
<P>
<PRE> use My::Doc qw($q);
</PRE>
<P>
Into a <CODE>My::HTML</CODE>, the <CODE>$q</CODE> will be shared. Otherwise <CODE>My::Doc</CODE> will not share the <CODE>$q</CODE> anymore. To make things clear here is the code:
<P>
<PRE> script.pl:
----------------
use vars qw($q);
use CGI;
use My::HTML qw($q);
use My::Doc qw($q);
$q = new CGI;
My::HTML::printmyheader();
----------------
</PRE>
<P>
<PRE> My/HTML.pm
----------------
package My::HTML;
use strict;
BEGIN {
use Exporter ();
@My::HTML::ISA = qw(Exporter);
@My::HTML::EXPORT = qw();
@My::HTML::EXPORT_OK = qw($q);
}
use vars qw($q);
use My::Doc qw($q);
sub printmyheader{
# Whatever you want to do with $q... e.g.
print $q->header();
My::Doc::printtitle('Guide');
}
-------------------
</PRE>
<P>
<PRE> My/Doc.pm
----------------
package My::Doc;
use strict;
BEGIN {
use Exporter ();
@My::Doc::ISA = qw(Exporter);
@My::Doc::EXPORT = qw();
@My::Doc::EXPORT_OK = qw($q);
}
use vars qw($q);
sub printtitle{
my $title = shift || 'None';
print $q->h1($title);
}
-------------------
</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Using_aliasing_perl_feature_to_s">Using aliasing perl feature to share global variables</A></H2></CENTER>
<P>
As the title says you can import a variable into a script/module without
using an Exporter.pm. I have found it usefull to keep all the configuration
variables in one module <CODE>My::Config</CODE>. But then I have to export all the variables in order to use them in other
modules, which is bad for two reasons: polluting other packages' namespaces
with extra tags which rise up the memory requirements, adding an overhead
of keeping track of what variables should be exported from the config
module and what imported for some particular package. I solve this problem
by keeping all the variables in one hash <CODE>%c</CODE> and exporting only it. Here is an example of <CODE>My::Config</CODE>:
<P>
<PRE> package My::Config;
use strict;
use vars qw(%c);
%c = (
# All the configs go here
scalar_var => 5,
array_var => [
foo,
bar,
],
hash_var => {
foo => 'Foo',
bar => 'BARRR',
},
);
</PRE>
<P>
Now in packages that want to use the configuration variables I have either
to use the fully qualified names like <CODE>$My::Config::test</CODE>, which I dislike or import them as described in the previous section. But
hey, since we have only one variable to handle, we can make things even
simpler and save the loading of the <CODE>Exporter.pm</CODE> package. We will use aliasing perl feature for exporting and saving the
keystrokes:
<P>
<PRE> package My::HTML;
use strict;
# Global Configuration now aliased to global %c
use My::Config ();
use vars qw(%c);
*c = \%My::Config::c;
# Now you can access the variables from the My::Config
print $c{scalar_val};
print $c{array_val}[0];
print $c{hash_val}{foo};
</PRE>
<P>
Of course <CODE>$c</CODE> is global everywhere you use it as described
above, and if you change it somewhere it will affect any other packages you
have aliased <CODE>$My::Config::c</CODE> to.
<P>
Note that aliases work either with global or <CODE>local()</CODE> vars - you cannot write:
<P>
<PRE> my *c = \%My::Config::c;
</PRE>
<P>
Which is an error. But you can:
<P>
<PRE> local *c = \%My::Config::c;
</PRE>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P><A HREF="index.html">[Back to the main page]</A></P>
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
<TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
<HR>
</TD>
</TR>
<TR ALIGN=CENTER VALIGN=TOP>
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#author">Stas Bekman</A>.
<BR>Last Modified at 04/03/99
</FONT>
</B>
</TD>
<TD>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
</TD>
<TD>
<FONT SIZE=-2>
Use of the Camel for Perl is <BR>
a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
and is used by permission.
</FONT>
</TD>
</TR>
</TABLE></CENTER>
</BODY>
</HTML>