NAME

FCGI::Async::Request - Class to represent one active FastCGI request

SYNOPSIS

This module would not be used directly by a program using FCGI::Async, but rather, objects in this class are passed into the on_request callback of the containing FCGI::Async object.

use FCGI::Async;
use IO::Async::Loop;

my $fcgi = FCGI::Async->new(
   on_request => sub {
      my ( $fcgi, $req ) = @_;

      my $path = $req->param( "PATH_INFO" );
      $req->print_stdout( "Status: 200 OK\r\n" .
                          "Content-type: text/plain\r\n" .
                          "\r\n" .
                          "You requested $path" );
      $req->finish();
   }
);

my $loop = IO::Async::Loop->new();

$loop->add( $fcgi );

$loop->loop_forever;

To serve contents of files on disk, it may be more efficient to use stream_stdout_then_finish:

on_request => sub {
   my ( $fcgi, $req ) = @_;

   open( my $file, "<", "/path/to/file" );
   $req->print_stdout( "Status: 200 OK\r\n" .
                       "Content-type: application/octet-stream\r\n" .
                       "\r\n" );

   $req->stream_stdout_then_finish(
      sub { read( $file, my $buffer, 8192 ) or return undef; return $buffer },
      0
   );
}

METHODS

$hashref = $req->params

This method returns a reference to a hash containing a copy of the request parameters that had been sent by the webserver as part of the request.

$p = $req->param( $key )

This method returns the value of a single request parameter, or undef if no such key exists.

$line = $req->read_stdin_line

This method works similarly to the <HANDLE> operator. If at least one line of data is available then it is returned, including the linefeed, and removed from the buffer. If not, then any remaining partial line is returned and removed from the buffer. If no data is available any more, then undef is returned instead.

$data = $req->read_stdin( $size )

This method works similarly to the read(HANDLE) function. It returns the next block of up to $size bytes from the STDIN buffer. If no data is available any more, then undef is returned instead. If $size is not defined, then it will return all the available data.

$req->print_stdout( $data )

This method appends the given data to the STDOUT stream of the FastCGI request, sending it to the webserver to be sent to the client.

$req->print_stderr( $data )

This method appends the given data to the STDERR stream of the FastCGI request, sending it to the webserver.

$req->stream_stdout_then_finish( $readfn, $exitcode )

This method installs a callback for streaming data to the STDOUT stream. Whenever the output stream is otherwise-idle, the function will be called to generate some more data to output. When this function returns undef it indicates the end of the stream, and the request will be finished with the given exit code.

If this method is used, then care should be taken to ensure that the number of bytes written to the server matches the number that was claimed in the Content-Length, if such was provided. This logic should be performed by the containing application; FCGI::Async will not track it.

$req->finish( $exitcode )

When the request has been dealt with, this method should be called to indicate to the webserver that it is finished. After calling this method, no more data may be appended to the STDOUT stream. At some point after calling this method, the request object will be removed from the containing FCGI::Async object, once all the buffered outbound data has been sent.

If present, $exitcode should indicate the numeric status code to send to the webserver. If absent, a value of 0 is presumed.

$req->is_aborted

Returns true if the webserver has already closed the control connection. No further work on this request is necessary, as it will be discarded.

It is not required to call this method; if the request is aborted then any output will be discarded. It may however be useful to call just before expensive operations, in case effort can be avoided if it would otherwise be wasted.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm FCGI::Async

perl -MCPAN -e shell
install FCGI::Async