NAME
"FCGI::Async" - use FastCGI with IO::Async
SYNOPSIS
NOTE: The constructor API of this module has changed since version 0.13!
use FCGI::Async;
use IO::Async::Loop;
my $loop = IO::Async::Loop->new();
my $fcgi = FCGI::Async->new(
loop => $loop,
service => 1234,
on_request => sub {
my ( $fcgi, $req ) = @_;
# Handle the request here
}
);
$loop->loop_forever;
Or
my $fcgi = FCGI::Async->new(
on_request => ...
);
my $loop = ...
$loop->add( $fcgi );
$fcgi->listen( service => 1234 );
DESCRIPTION
This module allows a program to respond asynchronously to FastCGI
requests, as part of a program based on IO::Async. An object in this
class represents a single FastCGI responder that the webserver is
configured to communicate with. It can handle multiple outstanding
requests at a time, responding to each as data is provided by the
program. Individual outstanding requests that have been started but not
yet finished, are represented by instances of FCGI::Async::Request.
CONSTRUCTOR
$fcgi = FCGI::Async->new( %args )
This function returns a new instance of a "FCGI::Async" object.
If either a "handle" or "service" argument are passed to the
constructor, then the newly-created object is added to the given
"IO::Async::Loop", then the "listen" method is invoked, passing the
entire %args hash to it. For more detail, see the "listen" method below.
If either of the above arguments are given, then a "IO::Async::Loop"
must also be provided:
loop => IO::Async::Loop
A reference to the "IO::Async::Loop" which will contain the
listening sockets.
PARAMETERS
The following named parameters may be passed to "new" or "configure":
on_request => CODE
Reference to a handler to call when a new FastCGI request is
received. It will be invoked as
$on_request->( $fcgi, $request )
where $request will be a new FCGI::Async::Request object.
default_encoding => STRING
Sets the default encoding used by all new requests. If not
supplied then "UTF-8" will apply.
METHODS
$fcgi->listen( %args )
Start listening for connections on a socket, creating it first if
necessary.
This method may be called in either of the following ways. To listen on
an existing socket filehandle:
handle => IO
An IO handle referring to a listen-mode socket. This is now
deprecated; use the "handle" key to the "new" or "configure" methods
instead.
Or, to create the listening socket or sockets:
service => STRING
Port number or service name to listen on.
host => STRING
Optional. If supplied, the hostname will be resolved into a set of
addresses, and one listening socket will be created for each
address. If not, then all available addresses will be used.
This method may also require "on_listen_error" or "on_resolve_error"
callbacks for error handling - see IO::Async::Listener for more detail.
Limits in FCGI_GET_VALUES
The "FCGI_GET_VALUES" FastCGI request can enquire of the responder the
maximum number of connections or requests it can support. Because this
module puts no fundamental limit on these values, it will return some
arbitrary numbers. These are given in package variables:
$FCGI::Async::MAX_CONNS = 1024;
$FCGI::Async::MAX_REQS = 1024;
These variables are provided in case the containing application wishes
to make the library return different values in the request. These values
are not actually used by the library, other than to fill in the values
in response of "FCGI_GET_VALUES".
Using a socket on STDIN
When running a local FastCGI responder, the webserver will create a new
INET socket connected to the script's STDIN file handle. To use the
socket in this case, it should be passed as the "handle" argument.
SEE ALSO
* CGI::Fast - Fast CGI drop-in replacement of CGI; single-threaded,
blocking mode.
* - The Common
Gateway Interface Specification
* - FastCGI
Specification
AUTHOR
Paul Evans