view release on metacpan or  search on metacpan

src/SpeedyCGI.src  view on Meta::CPAN

    #!/usr/bin/perl

to

    #!/usr/bin/speedy

After the script is initially run, instead of exiting, the perl
interpreter is kept running.  During subsequent runs, this interpreter is
used to handle new executions instead of starting a new perl interpreter
each time.  A very fast frontend program, written in C, is executed for
each request.  This fast frontend then contacts the persistent Perl
process, which is usually already running, to do the work and return
the results.

By default each perl script runs in its own Unix process, so one perl
script can't interfere with another.  Command line options can also be
used to deal with programs that have memory leaks or other problems that
might keep them from otherwise running persistently.

SpeedyCGI can be used to speed up perl CGI scripts.  It conforms to the
CGI specification, and does not run perl code inside the web server.
Since the perl interpreter runs outside the web server, it can't cause
problems for the web server itself.

SpeedyCGI also provides an Apache module so that under the Apache web
server, scripts can be run without the overhead of doing a fork/exec
for each request.  With this module a small amount of frontend code
is run within the web server - the perl interpreters still run outside
the server.

SP_DIRECTIVE BEGIN_NO_SUBSTITUTE

SpeedyCGI and PersistentPerl are currently both names for the same code.
SpeedyCGI was the original name, but because people weren't sure what it did,
the name PersistentPerl was picked as an alias.  At some point
SpeedyCGI will be replaced by PersistentPerl, or become
a sub-class of PersistentPerl to avoid always having two distributions.

SP_DIRECTIVE END_NO_SUBSTITUTE


=head1 OPTIONS

=head2 Setting Option Values

SpeedyCGI options can be set in several ways:

=over

=item Command Line

The speedy command line is the same as for regular perl, with the
exception that SpeedyCGI specific options can be passed in after a "--".

For example the line:

	#!/usr/bin/speedy -w -- -t300

at the top of your script will set the perl option
"C<-w>" and will pass the "C<-t>" option to SpeedyCGI, setting the
Timeout value to 300 seconds.

=back

=over

=item Environment

Environment variables can be used to pass in options.  This can only be
done before the initial execution, not from within the script itself.
The name of the environment variable is always SPEEDY_ followed by the
option name in upper-case.  For example to set the speedy Timeout option, use
the environment variable named SPEEDY_TIMEOUT.

=back

=over

=item Module

The CGI::SpeedyCGI module provides the setopt method to set options from
within the perl script at runtime.  There is also a getopt method to retrieve
the current options.  See L<"METHODS"> below.

=back

=over

=item Apache

If you are using the optional Apache module, SpeedyCGI options can be
set in the F<httpd.conf> file.  The name of the apache directive will always
be Speedy followed by the option name.  For example to set the
Timeout option, use the apache directive SpeedyTimeout.

=back

=head2 Context

Not all options below are available in all contexts.  The context for
which each option is valid is listed on the "Context" line in the section
below.  There are three contexts:

=over

=item speedy

The command-line "speedy" program, used normally with #! at the top of
your script or from a shell prompt.

=back

=over

=item mod_speedycgi

The optional Apache mod_speedycgi module.

=back

=over

=item module

During perl execution via the CGI::SpeedyCGI module's getopt/setopt methods.

=back

=head2 Options Available

=over

SP_DIRECTIVE INSERT_OPTIONS_POD_HERE

=back

=head1 METHODS

The following methods are available in the CGI::SpeedyCGI module.

=over

=item new

Create a new CGI::SpeedyCGI object.

    my $sp = CGI::SpeedyCGI->new;

=item register_cleanup($function_ref)

Register a function that will be called at the end of each request, after
your script finishes running, but before STDOUT and STDERR are closed.
Multiple functions can be added by calling the method more than once.
At the end of the request, each function will be called in the order
in which it was registered.

    $sp->register_cleanup(\&cleanup_func);

=item add_shutdown_handler($function_ref)

Add a function to the list of functions that will be called right before
the perl interpreter exits.  This is B<not> at the end of each request,
it is when the perl interpreter decides to exit completely due to a
Timeout or reaching MaxRuns.

    $sp->add_shutdown_handler(sub {$dbh->logout});

=item set_shutdown_handler($function_ref)

Deprecated.  Similar to C<add_shutdown_handler>, but only allows for a single
function to be registered.

    $sp->set_shutdown_handler(sub {$dbh->logout});

=item i_am_speedy

Returns a boolean telling whether this script is running under SpeedyCGI
or not.  A perl script can run under regular perl, or under SpeedyCGI.
This method allows the script to tell which environment it is in.

    $sp->i_am_speedy;

To make your script as portable as possible, you can use the following
test to make sure both the SpeedyCGI module is available and you are running
under SpeedyCGI:

    if (eval {require CGI::SpeedyCGI} && CGI::SpeedyCGI->i_am_speedy) {
	Do something SpeedyCGI specific here...

To increase the speed of this check you can also test whether the following
variable is defined instead of going through the object interface:

    $CGI::SpeedyCGI::i_am_speedy

=item setopt($optname, $value)

Set one of the SpeedyCGI options given in L<"Options Available">.  Returns
the option's previous value.  $optname is case-insensitive.

    $sp->setopt('TIMEOUT', 300);

=item getopt($optname)

Return the current value of one of the SpeedyCGI options.  $optname
is case-insensitive.

    $sp->getopt('TIMEOUT');

=item shutdown_now

Shut down the perl interpreter right away.  This function does not return.

    $sp->shutdown_now

=item shutdown_next_time

Shut down the perl interpreter as soon as this request is done.

    $sp->shutdown_next_time

=back

=head1 INSTALLATION