view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        apache modules are stored (try /usr/lib/apache)

    *   Edit your httpd.conf (try /etc/httpd/conf/httpd.conf) and add the
        following lines. The path at the end of the LoadModule directive may
        be different in your installation -- look at other LoadModules to
        see.

            LoadModule persistentperl_module modules/mod_persistentperl.so

        If you are using Apache-1, also add:

            AddModule mod_persistentperl.c

  Apache Configuration

    Once mod_persistentperl is installed, it has to be configured to be used
    for your perl scripts. There are two methods.

    Warning! The instructions below may compromise the security of your web
    site. The security risks associated with PersistentPerl are similar to
    those of regular CGI. If you don't understand the security implications
    of the changes below then don't make them.

    1. Path Configuration
        This is similar to the way /cgi-bin works - everything under this
        path is handled by PersistentPerl. Add the following lines near the
        top of your httpd.conf - this will cause all scripts in your cgi-bin
        directory to be handled by PersistentPerl when they are accessed as
        /perperl/script-name.

            Alias /perperl/ /home/httpd/cgi-bin/
            <Location /perperl>
                SetHandler persistentperl-script
                Options ExecCGI
                allow from all
            </Location>

    2. File Extension Configuration
        This will make PersistentPerl handle all files with a certain
        extension, similar to the way .cgi files work. Add the following
        lines near the top of your httpd.conf file - this will set up the
        file extension ".perperl" to be handled by PersistentPerl.

            AddHandler persistentperl-script .perperl
            <Location />
                Options ExecCGI
            </Location>

FREQUENTLY ASKED QUESTIONS
    How does the perperl front end connect to the back end process?
        Via a Unix socket in /tmp. A queue is kept in a shared file in /tmp
        that holds an entry for each process. In that queue are the pids of
        the perl processes waiting for connections. The frontend pulls a
        process out of this queue, connects to its socket, sends over the
        environment and argv, and then uses this socket for stdin/stdout to
        the perl process.

    If another request comes in while PersistentPerl script is running, does the client
    have to wait or is another process started?  Is there a way to set a limit
    on how many processes get started?
        If another request comes while all the perl processes are busy, then
        another perl process is started. Just like in regular perl there is
        normally no limit on how many processes get started. But, the
        processes are only started when the load is so high that they're
        necessary. If the load goes down, the processes will die off due to
        inactivity, unless you disable the timeout.

        Starting in version 1.8.3 an option was added to limit the number of
        perl backends running. See MaxBackends in the section on "Options
        Available" above.

    How much of perl's state is kept when perperl starts another request?
    Do globals keep their values?  Are destructors run after the request?
        Globals keep their values. Nothing is destroyed after the request.
        STDIN/STDOUT/STDERR are closed -- other files are not. `%ENV' and
        `@ARGV' are the only globals changed between requests.

    How can I make sure perperl restarts when I edit a perl library used
    by the CGI?
        Do a touch on the main cgi file that is executed. The mtime on the
        main file is checked each time the front-end runs.

    Do I need to be root to install and/or run PersistentPerl?
        No, root is not required.

    How can I determine if my perl app needs to be changed to work with
    perperl?  Or is there no modification necessary?
        You may have to make modifications.

        Globals retain their values between runs, which can be good for
        keeping persistent database handles for example, or bad if your code
        assumes they're undefined.

        Also, if you create global variables with "my", you shouldn't try to
        reference those variables from within a subroutine - you should pass
        them into the subroutine instead. Or better yet just declare global
        variables with "use vars" instead of "my" to avoid the problem
        altogether.

        Here's a good explanation of the problem - it's for mod_perl, but
        the same thing applies to persistentperl:

            http://perl.apache.org/docs/general/perl_reference/perl_reference.html#my___Scoped_Variable_in_Nested_Subroutines

        If all else fails you can disable persistence by setting MaxRuns to
        1. The only benefit of this over normal perl is that perperl will
        pre-compile your script.

    How do I keep a persistent connection to a database?
        Since globals retain their values between runs, the best way to do
        this is to store the connection in a global variable, then check on
        each run to see if that variable is already defined.

        For example, if your code has an "open_db_connection" subroutine
        that returns a database connection handle, you can use the code
        below to keep a persistent connection:

            use vars qw($dbh);
            unless (defined($dbh)) {
                $dbh = &open_db_connection;
            }