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 4 - Content Handlers / Chaining Content Handlers
Other Types of Stacked Handlers

Content handlers aren't the only type of Apache Perl API handler that can be stacked. Translation handlers, type handlers, authorization handlers, and in fact all types of handlers can be chained using exactly the same techniques we used for the content phase.

A particularly useful phase for stacking is the cleanup handler. Your code can use this to register any subroutines that should be called at the very end of the transaction. You can deallocate resources, unlock files, decrement reference counts, or clear globals. For example, the CGI.pm module maintains a number of package globals controlling various programmer preferences. In order to continue to work correctly in the persistent environment of mod_perl, CGI.pm has to clear these globals after each transaction. It does this by arranging for an internal routine named _reset_globals() to be called at the end of each transaction using this line of code:

$r->push_handlers('PerlCleanupHandler',\&CGI::_reset_globals);

Your program can push as many handlers as it likes, but you should remember that despite its name, the handler stack doesn't act like the classic LIFO (last-in/first-out) stack. Instead it acts like a FIFO (first-in/first-out) queue. Also remember that if the same handler is pushed twice, it will be invoked twice.

Footnotes

³ At the time this was written, the Apache developers were discussing a layered I/O system which will be part of the Apache 2.0 API.

⁴ The more obvious name, Apache::Filter, is already taken by a third-party module that does output chaining in a slightly different manner.

⁵ For historical reasons this facility is limited to Unix versions of Netscape Navigator, to PowerPC versions of Navigator on the Macintosh, and to some other Unix-based browsers such as W3-Emacs. However, now that Navigator's source code has been released to the developer community, we hope to see a more widespread implementation of this useful feature.

⁶ Andreas Koenig's Apache::GzipChain module, which does much the same thing as this one, contains a hardcoded pattern match for the browser type contained in the User-Agent field. You can add this sort of test yourself if you wish, or wait for the browser developers to implement Accept-Encoding correctly.