NAME

FCGI::Async - Module to allow use of FastCGI asynchronously

SYNOPSIS

This module allows a program to respond to FastCGI requests using an asynchronous model. The program would typically be structured as a select() loop.

    use FCGI::Async;

    my $fcgi = FCGI::Async->new();
    
    while( 1 ) {
       $fcgi->select();
       # perform non-blocking tasks here
    }

FUNCTIONS

$fcgi = FCGI::Async->new( %args )

This function returns a new instance of a FCGI::Async object, containing a master socket to listen on. The constructor returns immediately; it does not make any blocking calls.

The function operates in one of three ways, depending on arguments passed in the %args hash:

  • Listening on an existing socket.

     socket => $socket

    This must be a socket opened in listening mode, derived from IO::Socket, or any other class that handles the fileno and accept methods in a similar way.

  • Creating a new listening socket.

     port => $port

    A new IO::Socket::INET socket will be opened on the given port number. It will listen on all interfaces, from all addresses.

  • Using the socket passed as STDIN from a webserver.

    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, pass neither of the above options.

$fcgi->pre_select( $readref, $writeref, $exceptref, $timeref )

In combination with the post_select method, this method allows the FCGI::Async object to interact with a program's existing select() loop. By passing in references to three scalars of bitvectors, this method will register its interest in read- or writability on the given file descriptors, so that they will be included when the program calls select().

The method also takes a reference to the timeout value, for completeness, though it is currently ignored.

This method modifies the scalars referenced, and does not return any useful value.

$fcgi->post_select( $readvec, $writevec, $exceptvec )

This method allows the FCGI::Async object to interact with a program's existing select() loop. After the program has called select(), this method allows the FCGI object to operate with any of the file descriptors that have now become ready.

This method returns no useful value.

$ret = $fcgi->select()

This method wraps calls to the pre_select() and post_select() methods, and a select() syscall. It exists for convenience in cases where there are no other file descriptors the program wishes to wait on.

It returns the value returned from the select() syscall, though this value is unlikely to be interesting to the application.

$req = $fcgi->waitingreq

This method obtains a FCGI::Async::Request object that is ready for some operation to be performed on it. If no request is ready, this method will return undef.

See FCGI::Async::Request for more details.

SEE ALSO

  • CGI::Fast - Fast CGI drop-in replacement of CGI; single-threaded, blocking mode.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 273:

You forgot a '=back' before '=head1'

Around line 277:

=back without =over