Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Chapter 9 - Perl API Reference Guide / Special Global Variables, Subroutines, and Literals
Subroutines

Subroutines with capitalized names have special meaning to Perl. Familiar examples may include DESTROY and BEGIN. mod_perl also recognizes these subroutines and treats them specially.

BEGIN

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.

Once a BEGIN block has run, it is immediately undefined by removing it from the symbol table. In the mod_perl environment, this means BEGIN blocks will not be run during each incoming request unless that request happens to be the one that is compiling the code. When a .pm module or other Perl code file is pulled in via require or use, its BEGIN blocks will be executed as follows:

— Once at startup time if pulled in by the parent process by a PerlModule directive or in the Perl startup script.

— Once per child process if not pulled in by the parent process.

— An additional time in each child process if Apache::StatINC is loaded and the module is modified.

— An additional time in the parent process on each restart if PerlFreshRestart is On.

— At unpredictable times if you fiddle with %INC yourself. Don't do this unless you know what you are doing.

Apache::Registry scripts can contain BEGIN blocks as well. In this case, they will be executed as follows:

— Once at startup time 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 in each child process if the script file is modified.

— An additional time in the parent process on each restart if the script was pulled in by the parent process with Apache::RegistryLoader and Perl-Fresh-Restart is On.

END

In Perl, an END subroutine defined in a module or script is executed as late as possible, that is, when the interpreter is being exited. In the mod_perl environment, the interpreter does not exit until the server is shutdown. However, mod_perl does make a special case for Apache::Registry scripts.

Normally, END blocks are executed by Perl during its perl_run() function, which is called once each time the Perl program is executed, e.g., once per CGI (mod_cgi) script. However, mod_perl only calls perl_run() once during server startup. Any END blocks that are encountered during main server start-up, such as those pulled in by PerlRequire or PerlModule , are suspended and run at server shutdown time during the child_exit phase.

Any END blocks that are encountered during compilation of Apache::Registry scripts are called after the script has completed the response, 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 only during child_exit when the process is shutting down.

Module authors may wish to use $r->register_cleanup as an alternative to END blocks if this behavior is not desirable.

Magic Literals

Perl recognizes a few magic literals during script compilation. By and large, they act exactly like their counterparts in the standalone Perl interpreter.

__END__

This token works just as it does with the standalone Perl interpreter, causing compilation to terminate. However, this causes a problem for Apache::Registry scripts. Since the scripts are compiled inside of a subroutine, using __END__ will cut off the enclosing brace, causing script compilation to fail. If your Apache::Registry scripts use this literal, they will not run.

In partial compensation for this deficiency, mod_perl lets you use the __END__ token anywhere in your server configuration files to cut out experimental configuration or to make a notepad space that doesn't require you to use the # comment token on each line. Everything below the __END__ token will be ignored.

Special Package Globals

There are a number of useful globals located in the Apache::Server namespace that you are free to use in your own modules. Unless otherwise specified, treat them as read-only. Changing their values will lead to unpredictable results.

$Apache::Server::CWD

This variable is set to the directory from which the server was started.

$Apache::Server::Starting

If the code is running in the parent server when the server is first started, the value is set to 1; otherwise, it is set to 0.

$Apache::Server::ReStarting

If the code is running in the parent server when the server is restarted, this variable will be true; otherwise, it will be false. The value is incremented each time the server is restarted.

$Apache::Server::SaveConfig

As described in Chapter 8, <Perl> configuration sections are compiled inside the Apache::ReadConfig namespace. This namespace is normally flushed after mod_perl has finished processing the section. However, if the $Apache::Server::SaveConfig variable is set to a true value, the namespace will not be flushed, making configuration data available to Perl modules at request time.

<Perl>
$Apache::Server::SaveConfig = 1;

$DocumentRoot = ...
...
</Perl>

At request time, the value of $DocumentRoot can be accessed with the fully qualified name $Apache::ReadConfig::DocumentRoot.

The next chapters show the Apache API from the perspective of the C-language programmer, telling you everything you need to know to squeeze the last drop of performance out of Apache by writing extension modules in a fast compiled language.