The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
mod_perl-1.99_09
River stage three • 155 direct dependents • 183 total dependents
/ Porting

NAME

Porting Apache:: Perl Modules from mod_perl 1.0 to 2.0

Description

This document describes the various options for porting a mod_perl 1.0 Apache module so that it runs on a Apache 2.0 / mod_perl 2.0 server. It's also helpful to those who start developing mod_perl 2.0 handlers.

Developers who need to port modules using XS code, should also read about porting Apache:: XS modules.

Introduction

In the vast majority of cases, a perl Apache module that runs under mod_perl 1.0 will not run under mod_perl 2.0 without at least some degree of modification.

Even a very simple module that does not in itself need any changes will at least need the mod_perl 2.0 Apache modules loaded, because in mod_perl 2.0 basic functionality, such as access to the request object and returning an HTTP status, is not found where, or implemented how it used to be in mod_perl 1.0.

Most real-life modules will in fact need to deal with the following changes:

  • methods that have moved to a different (new) package

  • methods that must be called differently (due to changed prototypes)

  • methods that have ceased to exist (functionality provided in some other way)

Do not be alarmed! One way to deal with all of these issues is to load the Apache::compat compatibility layer bundled with mod_perl 2.0. This magic spell will make almost any 1.0 module run under 2.0 without further changes. It is by no means the solution for every case, however, so please read carefully the following discussion of this and other options.

There are three basic options for porting. Let's take a quick look at each one and then discuss each in more detail.

1 Run the module on 2.0 under Apache::compat with no further changes

As we have said mod_perl 2.0 ships with a module, Apache::compat, that provides a complete drop-in compatibility layer for 1.0 modules. Apache::compat does the following:

  • Loads all the mod_perl 2.0 Apache:: modules

  • Adjusts method calls where the prototype has changed

  • Provides Perl implementation for methods that no longer exist in 2.0

The drawback to using Apache::compat is the performance hit, which can be significant.

Authors of CPAN and other publicly distributed modules should not use Apache::compat since this forces its use in environments where the administrator may have chosen to optimize memory use by making all code run natively under 2.0.

2 Modify the module to run only under 2.0

If you are not interested in providing backwards compatibility with mod_perl 1.0, or if you plan to leave your 1.0 module in place and develop a new version compatible with 2.0, you will need to make changes to your code. How significant or widespread the changes are depends largely of course on your existing code.

Several sections of this document provide detailed information on how to rewrite your code for mod_perl 2.0 Several tools are provided to help you, and it should be a relatively painless task and one that you only have to do once.

3 Modify the module so that it runs under both 1.0 and 2.0

You need to do this if you want to keep the same version number for your module, or if you distribute your module on CPAN and want to maintain and release just one codebase.

This is a relatively simple ehancement of option (2) above. The module tests to see which version of mod_perl is in use and then executes the appropriate method call.

The following sections provide more detailed information and instructions for each of these three porting strategies.

Using the Apache::compat Layer

The Apache::compat module tries to hide the changes in API prototypes between version 1.0 and 2.0 of mod_perl, and implements "virtual methods" for the methods and functions that actually no longer exist.

Apache::compat is extremely easy to use. Either add at the very beginning of startup.pl:

  use Apache2;
  use Apache::compat;

or add to httpd.conf:

  PerlModule Apache2
  PerlModule Apache::compat

That's all there is to it. Now you can run your 1.0 module unchanged.

Remember, however, that using Apache::compat will make your module run slower. It can create a larger memory footprint than you need and it implements functionality in pure Perl that is provided in much faster XS in mod_perl 1.0 as well as in 2.0. This module was really designed to assist in the transition from 1.0 to 2.0. Generally you will be better off if you port your code to use the mod_perl 2.0 API.

It's also especially important to repeat that CPAN module developers are requested not to use this module in their code, since this takes the control over performance away from users.

Porting a Perl Module to Run under mod_perl 2.0

Note: API changes are listed in the backwards compatibility document.

The following sections will guide you through the steps of porting your modules to mod_perl 2.0.

Using ModPerl::MethodLookup to Discover Which mod_perl 2.0 Modules Need to Be Loaded

It would certainly be nice to have our mod_perl 1.0 code run on the mod_perl 2.0 server unmodified. So first of all, try your luck and test the code.

It's almost certain that your code won't work when you try, however, because mod_perl 2.0 splits functionality across many more modules than version 1.0 did, and you have to load these modules before the methods that live in them can be used. So the first step is to figure out which these modules are and use() them.

The MethodLookup module provided with mod_perl 2.0 allows you to find out which module contains the functionality you are looking for. Simply provide it with the name of the mod_perl 1.0 method that has moved to a new module, and it will tell you what the module is.

For example, let's say we have a mod_perl 1.0 code snippet:

  $r->content_type('text/plain');
  $r->print("Hello cruel world!");

If we run this, mod_perl 2.0 will complain that the method content_type() can't be found. So we use ModPerl::MethodLookup to figure out which module provides this method. We can just run this from the command line:

  % perl -MApache2 -MModPerl::MethodLookup -e print_method content_type

This prints:

  to use method 'content_type' add:
           use Apache::RequestRec ();

We do what it says and add this use() statement to our code, restart our server (unless we're using Apache::Reload), and mod_perl will no longer complain about this particular method.

Since you may need to use this technique quite often you may want to define an alias. Once defined the last command line lookup can be accomplished with:

  % lookup content_type

ModPerl::MethodLookup also provides helper functions for finding which methods are defined in a given module, or which methods can be invoked on a given object.

Handling Methods Existing In More Than One Package

Some methods exists in several classes. For example this is the case with the print() method. We know the drill:

  % lookup print

This prints:

  There is more than one class with method 'print'
  try one of:
        use Apache::RequestIO ();
        use Apache::Filter ();

So there is more than one package that has this method. Since we know that we call the print() method with the $r object, it must be the Apache::RequestIO module that we are after. Indeed, loading this module solves the problem.

Using ModPerl::MethodLookup Programmatically

The issue of picking the right module, when more than one matches, can be resolved when using ModPerl::MethodLookup programmatically -- lookup_method accepts an object as an optional second argument, which is used if there is more than one module that contains the method in question. ModPerl::MethodLookup knows that Apache::RequestIO and and Apache::Filter expect an object of type Apache::RequestRec and type Apache::Filter respectively. So in a program running under mod_perl we can call:

  ModPerl::MethodLookup::lookup_method('print', $r);

Now only one module will be matched.

This functionality can be used in AUTOLOAD, for example, although most users will not have a need for this robust of solution.

Pre-loading All mod_perl 2.0 Modules

Now if you use a wide range of methods and functions from the mod_perl 1.0 API, the process of finding all the modules that need to be loaded can be quite frustrating. In this case you may find the function preload_all_modules() to be the right tool for you. This function preloads all mod_perl 2.0 modules, implementing their API in XS.

While useful for testing and development, it is not recommended to use this function in production systems. Before going into production you should remove the call to this function and load only the modules that are used, in order to save memory.

CPAN module developers should not be tempted to call this function from their modules, because it prevents the user of their module from optimizing her system's memory usage.

Handling Missing and Modified mod_perl 1.0 Methods and Functions

The mod_perl 2.0 API is modelled even more closely upon the Apache API than was mod_perl version 1.0. Just as the Apache 2.0 API is substantially different from that of Apache 1.0, therefore, the mod_perl 2.0 API is quite different from that of mod_perl 1.0. Unfortunately, this means that certain method calls and functions that were present in mod_perl version 1.0 are missing or modified in mod_perl 2.0.

If mod_perl 2.0 tells you that some method is missing and it can't be found using ModPerl::MethodLookup, it's most likely because the method doesn't exist in the mod_perl 2.0 API. It's also possible that the method does still exist, but nevertheless it doesn't work, since its usage has changed (e.g. its prototype has changed, or it requires ditfferent arguments, etc.).

In either of these cases, refer to the backwards compatibility document for an exhaustive list of API calls that have been modified or removed.

Methods that No Longer Exist

Some methods that existed in mod_perl 1.0 simply do not exist anywhere in version 2.0 and you must therefore call a different method o methods to get the functionality you want.

For example, suppose we have a mod_perl 1.0 code snippet:

  $r->log_reason("Couldn't open the session file: $@");

If we try to run this under mod_perl 2.0 it will complain about the call to log_reason(). But when we use ModPerl::MethodLookup to see which module to load in order to call that method, nothing is found:

  % perl -MApache2 -MModPerl::MethodLookup -le \
    'print((ModPerl::MethodLookup::lookup_method(shift))[0])' \
    log_reason

This prints:

  don't know anything about method 'log_reason'

Looks like we are calling a non-existent method! Our next step is to refer to the backwards compatibility document, wherein we find that as we suspected, the method log_reason() no longer exists, and that instead we should use the other standard logging functions provided by the Apache::Log module.

Methods Whose Usage Has Been Modified

Some methods still exist, but their usage has been modified, and your code must call them in the new fashion or it will generate an error. Most often the method call requires new or different arguments.

For example, say our mod_perl 1.0 code said:

  $parsed_uri = Apache::URI->parse($r, $r->uri);

This code causes mod_perl 2.0 to complain first about not being able to load the method parse() via the package Apache::URI. We use the tools described above to discover that the package containing our method has moved and change our code to load and use APR::URI:

  $parsed_uri = APR::URI->parse($r, $r->uri);

But we still get an error. It's a little cryptic, but it gets the point across:

  p is not of type APR::Pool at /path/to/OurModule.pm line 9.

What this is telling us is that the method parse requires an APR::Pool object as its first argument. (Some methods whose usage has changed emit more helpful error messages prefixed with "Usage: ...") So we change our code to:

  $parsed_uri = APR::URI->parse($r->pool, $r->uri);

and all is well in the world again.

Requiring a specific mod_perl version.

To require a module to run only under 2.0, simply add:

  use Apache2;
  use mod_perl 2.0;

META: In fact, before 2.0 is released you really have to say:

  use Apache2;
  use mod_perl 1.99;

And you can even require a specific version (for example when a certain API has been added only starting from that version). For example to require version 1.99_08, you can say:

  use mod_perl 1.9908;

Should the Module Name Be Changed?

If it is not possible to make your code run under both mod_perl versions (see below), you will have to maintain two separate versions of your own code. While you can change the name of the module for the new version, it's best to try to preserve the name and use some workarounds.

Let's say that you have a module Apache::Friendly whose release version compliant with mod_perl 1.0 is 1.57. You keep this version on CPAN and release a new version, 2.01, which is compliant with mod_perl 2.0 and preserves the name of the module. It's possible that a user may need to have both versions of the module on the same machine. Since the two have the same name they obviously cannot live under the same tree.

One attempt to solve this problem is to use Makefile.PL's MP_INST_APACHE2 option. If the module is configured as:

  % perl Makefile.PL MP_INST_APACHE2=1

it'll be installed relative to the Apache2/ directory.

META: but of course this won't work in non-core mod_perl, since a generic Makefile.PL has no idea what to do about MP_INST_APACHE2=1. Need to provide copy-n-paste recipe for this. Or even add to the core a supporting module that will handle this functionality.

The second step is to change the documentation of your 2.0 compliant module to instruct users to use Apache2 (); in their code (or in startup.pl or via PerlModule Apache2 in httpd.conf) before the module is required. This will cause @INC to be modified to include the Apache2/ directory first.

The introduction of the Apache2/ directory is similar to how Perl installs its modules in a version specific directory. For example:

  lib/5.7.1
  lib/5.7.2

Using Apache::compat As a Tutorial

Even if you have followed the recommendation and eschewed use of the Apache::compat module, you may find it useful to learn how the API has been changed and how to modify your own code. Simply look at the Apache::compt source code and see how the functionality should be implemented in mod_perl 2.0.

For example, mod_perl 2.0 doesn't provide the Apache->gensym method. As we can see if we look at the Apache/compat.pm source, the functionality is now available via the core Perl module Symbol and its gensym() function. (Since mod_perl 2.0 works only with Perl versions 5.6 and higher, and Symbol.pm is included in the core Perl distribution since version 5.6.0, there was no reason to keep providing Apache->gensym.)

So if the original code looked like:

  my $fh = Apache->gensym;
  open $fh, $file or die "Can't open $file: $!";

in order to port it mod_perl 2.0 we can write:

  my $fh = Symbol::gensym;
  open $fh, $file or die "Can't open $file: $!";

Or we can even skip loading Symbol.pm, since under Perl version 5.6 and higher we can just do:

  open my $fh, $file or die "Can't open $file: $!";

Porting a Module to Run under both mod_perl 2.0 and mod_perl 1.0

Sometimes code needs to work with both mod_perl versions. This is the case for writers of publically available and CPAN modules who wish to continue to maintain a single code base, rather than supplying two separate implementations.

Making Code Conditional on Running mod_perl Version

In this case you can test for which version of mod_perl your code is running under and act appropriately.

To continue our example above, let's say we want to support opening a filehandle in both mod_perl 2.0 and mod_perl 1.0. Our code can make use of the variable $mod_perl::VERSION:

  use mod_perl;
  use constant MP2 => ($mod_perl::VERSION >= 1.99);
  # ...
  require Symbol if MP2;
  # ...
  
  my $fh = MP2 ? Symbol::gensym : Apache->gensym;
  open $fh, $file or die "Can't open $file: $!";

Here's another way to find out the mod_perl version. In the server configuration file you can use a special configuration "define" symbol MODPERL2, which is magically enabled internally, as if the server had been started with -DMODPERL2.

  # in httpd.conf
  <IfDefine MODPERL2>
      # 2.0 configuration
  </IfDefine>
  <IfDefine !MODPERL2>
      # else
  </IfDefine>

From within Perl code this can be tested with Apache::exists_config_define(). For example, we can use this method to decide whether or not to call $r->send_http_header(), which no longer exists in mod_perl 2.0:

  sub handler {
      my $r = shift;
      $r->content_type('text/html');
      $r->send_http_header() unless Apache::exists_config_define("MODPERL2");
      ...
  }

Maintainers

Maintainer is the person(s) you should contact with updates, corrections and patches.

Stas Bekman <stas (at) stason.org>

Authors

  • Nick Tonkin <nick (at) tonkinresolutions.com>

  • Stas Bekman <stas (at) stason.org>

Only the major authors are listed above. For contributors see the Changes file.