view release on metacpan or  search on metacpan

lib/CGI/SpeedyCGI.pm  view on Meta::CPAN

the script from:

    #!/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.


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.



=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

=item BackendProg

    Command Line    : -p<string>
    Default Value   : "/usr/bin/speedy_backend"
    Context         : mod_speedycgi, speedy

    Description:

	Path to the speedy backend program.

=item BufsizGet

    Command Line    : -B<number>
    Default Value   : 131072
    Context         : speedy

    Description:

	Use <number> bytes as the maximum size for the buffer that
	receives data from the perl backend.

=item BufsizPost

lib/CGI/SpeedyCGI.pm  view on Meta::CPAN

    Description:

	Use <number> bytes as the maximum size for the buffer that
	sends data to the perl backend.

=item Group

    Command Line    : -g<string>
    Default Value   : "none"
    Context         : mod_speedycgi, speedy

    Description:

	Allow a single perl interpreter to run multiple scripts.
	All scripts that are run with the same group name and by
	the same user will be run by the same group of perl
	interpreters. If the group name is "none" then grouping is
	disabled and each interpreter will run one script.
	Different group names allow scripts to be separated into
	different groups. Name is case-sensitive, and only the
	first 12-characters are significant. Specifying an empty
	group name is the same as specifying the group name
	"default" - this allows just specifying "-g" on the command
	line to turn on grouping.

=item MaxBackends

    Command Line    : -M<number>
    Default Value   : 0 (no max)
    Context         : mod_speedycgi, speedy

    Description:

	If non-zero, limits the number of speedy backends running
	for this perl script to <number>.

=item MaxRuns

    Command Line    : -r<number>
    Default Value   : 500
    Context         : mod_speedycgi, module, speedy

    Description:

	Once the perl interpreter has run <number> times, re-exec
	the backend process.  Zero indicates no maximum.  This
	option is useful for processes that tend to consume
	resources over time.

=item PerlArgs

    Command Line    : N/A
    Default Value   : ""
    Context         : mod_speedycgi

    Description:

	Command-line options to pass to the perl interpreter.

=item Timeout

    Command Line    : -t<number>
    Default Value   : 3600 (one hour)
    Context         : mod_speedycgi, module, speedy

    Description:

	If no new requests have been received after <number>
	seconds, exit the persistent perl interpreter.	Zero
	indicates no timeout.

=item TmpBase

    Command Line    : -T<string>
    Default Value   : "/tmp/speedy"
    Context         : mod_speedycgi, speedy

    Description:

	Use the given prefix for creating temporary files.  This
	must be a filename prefix, not a directory name.

=item Version

    Command Line    : -v
    Context         : speedy

    Description:

	Print the SpeedyCGI version and exit.


=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