development2Add my vote for this tag performance1Add my vote for this tag plugin1Add my vote for this tag create new tag
, view all tags

How To Write mod_perl Compliant Plugins

ModPerl is one of the most popular accelerators for CGI programs written in perl. However, the book Practical mod_perl (924 pages) may be a bit too time consuming to read if all you want to do is to write a plugin for TWiki. So this is a first start for you.

The Basics
ModPerl draws its speed benefit from the fact that perl is "compiled into" the server, enabling one apache process to answer many consecutive requests. All the compilation is done only once, die doesn't die, and exit doesn't exit.

So what does that mean for a plugin author? There are some simple rules:

  1. Use global variables for constants only. In particular, use use vars ... only for the stuff you already find in EmptyPlugin.
    • If you absolutely must use a global variable, for example to shuffle data around between different stages of your plugin, make sure that you explicitly initialize the variable in your initPlugin routine. initPlugin is called for every TWiki request.
  2. Don't use variables declared with my outside of subroutines in your module.
  3. Don't use circular references.
    • If you really feel you need a circular reference, make sure to "break" it in one of the final handlers of your plugin. Otherwise perl's garbage collection will not be able to return all the memory.
  4. Don't use BEGIN blocks for things which need to be done for every request. There's initPlugin for initialisation.
  5. Don't use END blocks.
  6. Don't use //o optimization for regexes if the regex contains request parameters.
  7. If you open files (or sockets), make sure you close them explicitly under all circumstances. Just calling die in case of an error isn't sufficient!
    • don't open files in one handler (e.g. beforeSaveHandler), and then close them again in a different handler (e.g. afterSaveHandler). TWiki may encounter an error condition, such as an access control violation, after the first handler being called that results in the second handler being ignored.
    • You can reliably trap all dies by using the Error module. For example:
  8. Use the use strict; pragram
use Error qw( :try );
sub commonTagsHandler {
   try {
      open(FILE, "<diskfile") || die "open failed $!";
   } finally {
This will result in the close being called under all circumstances.

-- Contributors: HaraldJoerg, CrawfordCurrie


Thanks Harald for writing this! I linked it from the relevant SupplementalDocuments so that people can find it easily.

On open files, a die is out of the control of Plugins since TWiki can do that happily anywhere in the core. Some notes on how to make sure one's handlers are closed would be helpful.

-- PeterThoeny - 28 Mar 2006

Some interesting reading there.

-- StephaneLenclud - 08 Apr 2008

Now let's say I want to right a plug-in or possibly a RcsFile implementation that assumes mod_perl is enabled. I should then be able to use global variables in my module and I can expect its value to be persistent until Apache is restarted right?

-- StephaneLenclud - 08 Apr 2008

Persistent in that interpreter instance, yes. Other interpreter instances will have different values.

-- CrawfordCurrie - 08 Apr 2008

See also mod_perl overview and coding.

-- StephaneLenclud - 10 Apr 2008

Edit | Attach | Watch | Print version | History: r7 < r6 < r5 < r4 < r3 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r7 - 2008-04-10 - StephaneLenclud
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.