Does this mean that Mason creates the parser/interp/handler for every
request (as it seems to state) or does Mason only create the objects for
each Directory/Virtual host?

It means that a new set of objects is created per request, as the docs say
("...for every request").
Right.  Well I guess it was less of an ambiguity and more of me thinking "gee that sounds silly and inefficient, they wouldn't _really_ do it that way would they?"  But after reading the code I realised this was exactly what was happening.  

I would prefer to use Apache config variables to setup my Mason vhosts
as it keeps all the config together in one place. However I don't want
to be penalized for doing so. In the past I wrote a fairly simple
handler.pl that created a hash with unique keys for each vhost and
inserted the Mason::ApacheHandler objects in it, reusing them for later
requests. Could this sort of functionality not be included in the
default Mason::ApacheHandler::handler sub?

I would like to do this.

The question is how to do it. How do I figure out what
directory/location/virtualhost block we're in?

The Apache API doesn't give all this info, unfortunately.

Well if apache doesn't provide a suitable API then perhaps we need to make our own.  How about a httpd.conf setting:  'PerlSetVar MasonAHCacheHint "uniquestring"'.  Then in HTML::Mason::ApacheHandler::_make_ah() we add this:

my $cache_hint = _get_string_param('AHCacheHint');
if(defined $cache_hint){
  if(exists $handlers_cache{$cache_hint} and $handlers_cache{$cache_hint}->isa("HTML::Mason::ApacheHandler")){
    $AH = $handlers_cache{$cache_hint};
  } else {
    $AH = $handlers_cache{$cache_hint} = HTML::Mason::ApacheHandler->new( interp => _make_interp(), %p );
  }
} else {
  $AH = HTML::Mason::ApacheHandler->new( interp => _make_interp(), %p );
}

return $AH;

Previously I was essentially doing this in my own custom handler.pl.  I put some PerlSetVar's in my httpd.conf and then used them to create a unique key for a hash of ApacheHandlers.  Doing the above allows for backwards compatibility.  It doesn't break existing behaviour but lets people worried about performance provide a cache-key.  It also lets people use the same AH for different vhosts/directories if that makes sense in their situation.  For example if you were mixing PHP and Mason in a site you could configure multiple <Directory> sections that used the same AH object and other <Directory> sections that used PHP, or whatever.

Is that a good enough solution?  I don't know about the naming of the PerlSetVar tho.  That could be improved.

Later
-- 
Oliver Jones - oliver@deeper.co.nz - Mobile: +64-21-41-2238
- Deeper Design Limited - http://www.deeperdesign.com