NAME

    Net::Async::FastCGI - use FastCGI with IO::Async

SYNOPSIS

    As an adapter:

       use Net::Async::FastCGI;
       use IO::Async::Loop;
    
       my $loop = IO::Async::Loop->new();
    
       my $fastcgi = Net::Async::FastCGI->new(
          on_request => sub {
             my ( $fastcgi, $req ) = @_;
    
             # Handle the request here
          }
       );
    
       $loop->add( $fastcgi );
    
       $fastcgi->listen(
          service => 1234,
          on_resolve_error => sub { die "Cannot resolve - $_[-1]\n" },
          on_listen_error  => sub { die "Cannot listen - $_[-1]\n" },
       );
    
       $loop->run;

    As a subclass:

       package MyFastCGIResponder;
       use base qw( Net::Async::FastCGI );
    
       sub on_request
       {
          my $self = shift;
          my ( $req ) = @_;
    
          # Handle the request here
       }
    
       ...
    
       use IO::Async::Loop;
    
       my $loop = IO::Async::Loop->new();
    
       my $fastcgi;
       $loop->add( $fastcgi = MyFastCGIResponder->new( service => 1234 ) );
    
       $fastcgi->listen(
          service => 1234,
          on_resolve_error => sub { die "Cannot resolve - $_[-1]\n" },
          on_listen_error  => sub { die "Cannot listen - $_[-1]\n" },
       );
    
       $loop->run;

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
    Net::Async::FastCGI::Request.

EVENTS

    The following events are invoked, either using subclass methods or CODE
    references in parameters:

 on_request $req

    Invoked when a new FastCGI request is received. It will be passed a new
    Net::Async::FastCGI::Request object.

PARAMETERS

    The following named parameters may be passed to new or configure:

    on_request => CODE

      CODE references for on_request event handler.

    default_encoding => STRING

      Sets the default encoding used by all new requests. If not supplied
      then UTF-8 will apply.

    stream_stdin => BOOL

      If true, requests will expect to handling streaming of stdin data. In
      this mode, the on_request event handler will be invoked once
      parameters for a new request have been received, even if the stdin
      stream is not yet complete.

METHODS

 listen

       $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:

       $Net::Async::FastCGI::MAX_CONNS = 1024;
       $Net::Async::FastCGI::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.

      * http://hoohoo.ncsa.uiuc.edu/cgi/interface.html - The Common Gateway
      Interface Specification

      * http://www.fastcgi.com/devkit/doc/fcgi-spec.html - FastCGI
      Specification

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>