GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  PLACK::HANDLER::APACHE2 (3)

.ds Aq ’

NAME

Plack::Handler::Apache2 - Apache 2.0 mod_perl handler to run PSGI application

CONTENTS

SYNOPSIS



  # in your httpd.conf
  <Location />
  SetHandler perl-script
  PerlResponseHandler Plack::Handler::Apache2
  PerlSetVar psgi_app /path/to/app.psgi
  </Location>

  # Optionally preload your apps in startup
  PerlPostConfigRequire /etc/httpd/startup.pl



See STARTUP FILE for more details on writing a startup.pl.

DESCRIPTION

This is a mod_perl handler module to run any PSGI application with mod_perl on Apache 2.x.

If you want to run PSGI applications behind Apache instead of using mod_perl, see Plack::Handler::FCGI to run with FastCGI, or use standalone HTTP servers such as Starman or Starlet proxied with mod_proxy.

CREATING CUSTOM HANDLER

If you want to create a custom handler that loads or creates PSGI applications using other means than loading from .psgi files, you can create your own handler class and use call_app class method to run your application.



  package My::ModPerl::Handler;
  use Plack::Handler::Apache2;

  sub get_app {
    # magic!
  }

  sub handler {
    my $r = shift;
    my $app = get_app();
    Plack::Handler::Apache2->call_app($r, $app);
  }



STARTUP FILE

Here is an example startup.pl to preload PSGI applications:



    #!/usr/bin/env perl

    use strict;
    use warnings;
    use Apache2::ServerUtil ();

    BEGIN {
        return unless Apache2::ServerUtil::restart_count() > 1;

        require lib;
        lib->import(/path/to/my/perl/libs);

        require Plack::Handler::Apache2;

        my @psgis = (/path/to/app1.psgi, /path/to/app2.psgi);
        foreach my $psgi (@psgis) {
            Plack::Handler::Apache2->preload($psgi);
        }
    }

    1; # file must return true!



See <http://perl.apache.org/docs/2.0/user/handlers/server.html#Startup_File> for general information on the startup.pl file for preloading perl modules and your apps.

Some things to keep in mind when writing this file:
o multiple init phases

You have to check that restart_count in Apache2::ServerUtil is > 1, otherwise your app will load twice and the env vars you set with PerlSetEnv <http://perl.apache.org/docs/2.0/user/config/config.html#C_PerlSetEnv_> will not be available when your app is loading the first time.

Use the example above as a template.

o @INC

The startup.pl file is a good place to add entries to your @INC. Use lib to add entries, they can be in your app or .psgi as well, but if your modules are in a local::lib or some such, you will need to add the path for anything to load.

Alternately, if you follow the example above, you can use:



    PerlSetEnv PERL5LIB /some/path



or



    PerlSwitches -I/some/path



in your httpd.conf, which will also work.

o loading errors

Any exceptions thrown in your startup.pl will stop Apache from starting at all.

You probably don’t want a stray syntax error to bring your whole server down in a shared or development environment, in which case it’s a good idea to wrap the preload call in an eval, using something like this:



    require Plack::Handler::Apache2;

    my @psgis = (/path/to/app1.psgi, /path/to/app2.psgi);

    foreach my $psgi (@psgis) {
        eval {
            Plack::Handler::Apache2->preload($psgi); 1;
        } or do {
            my $error = $@ || Unknown Error;
            # STDERR goes to the error_log
            print STDERR "Failed to load psgi $psgi: $error\n";
        };
    }



o dynamically loaded modules

Some modules load their dependencies at runtime via e.g. Class::Load. These modules will not get preloaded into your parent process by just including the app/module you are using.

As an optimization, you can dump %INC from a request to see if you are using any such modules and preload them in your startup.pl.

Another method is dumping the difference between the %INC on process start and process exit. You can use something like this to accomplish this:



    my $start_inc = { %INC };

    END {
        my @m;
        foreach my $m (keys %INC) {
            push @m, $m unless exists $start_inc->{$m};
        }

        if (@m) {
            # STDERR goes to the error_log
            print STDERR "The following modules need to be preloaded:\n";
            print STDERR "$_\n" for @m;
        }
    }



AUTHOR

Tatsuhiko Miyagawa

CONTRIBUTORS

Paul Driver

AEvar Arnfjoerd` Bjarmason

Rafael Kitover

SEE ALSO

Plack
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 PLACK::HANDLER::APACHE2 (3) 2015-06-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.