.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "FCGI::EV 3pm" .TH FCGI::EV 3pm "2022-12-06" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" FCGI::EV \- Implement FastCGI protocol for use in EV\-based applications .SH "VERSION" .IX Header "VERSION" This document describes \s-1FCGI::EV\s0 version v2.0.1 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use FCGI::EV; \& use Some::FCGI::EV::Handler; \& \& # while in EV::loop, accept incoming connection from web server into \& # $sock, then start handling FastCGI protocol on that connection, \& # using Some::FCGI::EV::Handler for processing CGI requests: \& FCGI::EV\->new($sock, \*(AqSome::FCGI::EV::Handler\*(Aq); \& \& \& # \& # EXAMPLE: complete FastCGI server (without error handling code) \& # use FCGI::EV::Std handler (download separately from CPAN) \& # \& \& use Socket; \& use Fcntl; \& use EV; \& use FCGI::EV; \& use FCGI::EV::Std; \& \& my $path = \*(Aq/tmp/fastcgi.sock\*(Aq; \& \& socket my $srvsock, AF_UNIX, SOCK_STREAM, 0; \& unlink $path; \& my $umask = umask 0; # ensure 0777 perms for unix socket \& bind $srvsock, sockaddr_un($path); \& umask $umask; \& listen $srvsock, SOMAXCONN; \& fcntl $srvsock, F_SETFL, O_NONBLOCK; \& \& my $w = EV::io $srvsock, EV::READ, sub { \& accept my($sock), $srvsock; \& fcntl $sock, F_SETFL, O_NONBLOCK; \& FCGI::EV\->new($sock, \*(AqFCGI::EV::Std\*(Aq); \& }; \& \& EV::loop; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module implement FastCGI protocol for use in EV-based applications. (That mean you have to run EV::loop in your application or this module will not work.) .PP It receive and parse data from web server, pack and send data to web server, but it doesn't process \s-1CGI\s0 requests received from web server \- instead it delegate this work to another module called 'handler'. For one example of such handler, see FCGI::EV::Std. .PP \&\s-1FCGI::EV\s0 work using non-blocking sockets and initially was designed to use in event-based \s-1CGI\s0 applications (which able to handle multiple parallel \&\s-1CGI\s0 requests in single process without threads/fork). This require from \&\s-1CGI\s0 to avoid any operations which may block, like using \s-1SQL\s0 database \- instead \s-1CGI\s0 should delegate all such tasks to remote services and talk to these services in non-blocking mode. .PP It also possible to use it to run usual \s-1CGI\s0.pm\-based applications. If you will do this using FCGI::EV::Std handler, then only one \s-1CGI\s0 request will be executed at a time (which is probably not what you expect from FastCGI!), because FCGI::EV::Std doesn't implement any process-manager. But it's possible to develop another handlers for \s-1FCGI::EV,\s0 which will support process-management and so will handle multiple \s-1CGI\s0 request in parallel. .PP This module doesn't require from user to use \s-1CGI\s0.pm \- any module for parsing \s-1CGI\s0 params can be used in general (details depends on used \&\s-1FCGI::EV\s0 handler module). .SH "INTERFACE" .IX Header "INTERFACE" .SS "new" .IX Subsection "new" .Vb 1 \& FCGI::EV\->new( $sock, $class ); .Ve .PP Start talking FastCGI protocol on \f(CW$sock\fR (which should be socket open to just-connected web server), and use \f(CW$class\fR to handle received \s-1CGI\s0 requests. .PP Module \f(CW$class\fR should implement \*(L"\s-1FCGI::EV\s0 handler\*(R" interface. You can use either FCGI::EV::Std from \s-1CPAN\s0 or develop your own. .PP Return nothing. (Created \s-1FCGI::EV\s0 object will work in background and will be automatically destroyed after finishing I/O with web server.) .SH "HANDLER CLASS INTERFACE" .IX Header "HANDLER CLASS INTERFACE" Handler class (which name provided in \f(CW$class\fR parameter to \s-1FCGI::EV\-\s0>\fBnew()\fR) must implement this interface: .ie n .IP "new( $server, \e%env )" 4 .el .IP "new( \f(CW$server\fR, \e%env )" 4 .IX Item "new( $server, %env )" When \s-1FCGI::EV\s0 object receive initial part of \s-1CGI\s0 request (environment variables) it will call \f(CW$handler_class\fR\->\fBnew()\fR to create handler object which should process that \s-1CGI\s0 request. .Sp Parameter \f(CW$server\fR is \s-1FCGI::EV\s0 object itself. It's required to send \s-1CGI\s0 reply. \s-1WARNING\s0! Handler may keep only \fBweaken()\fR reference to \f(CW$server\fR! .Sp After calling \fBnew()\fR \s-1FCGI::EV\s0 object ($server) will continue receiving \&\s-1STDIN\s0 content from web server and will call \f(CW$handler\fR\->\fBstdin()\fR each time it get next part of \s-1STDIN.\s0 .ie n .IP "stdin( $data, $is_eof )" 4 .el .IP "stdin( \f(CW$data\fR, \f(CW$is_eof\fR )" 4 .IX Item "stdin( $data, $is_eof )" The \f(CW$data\fR is next chunk of \s-1STDIN\s0 received from web server. Flag \f(CW$is_eof\fR will be true if \f(CW$data\fR was last part of \s-1STDIN.\s0 .Sp Usually handler shouldn't begin processing \s-1CGI\s0 request until all content of \s-1STDIN\s0 will be received. .IP "\s-1DESTROY\s0" 4 .IX Item "DESTROY" This method is optional. It will be called when connection to web server is closed and \s-1FCGI::EV\s0 object going to die (but it's still exists when \s-1DESTROY\s0 is called \- except if \s-1DESTROY\s0 was called while global destruction stage). .Sp Handler object may use \s-1DESTROY\s0 to interrupt current \s-1CGI\s0 request if web server close connection before \s-1CGI\s0 send it reply. .SS "\s-1SENDING CGI REPLY\s0" .IX Subsection "SENDING CGI REPLY" After handler got \f(CW%env\fR (in \fBnew()\fR) and complete \s-1STDIN\s0 (in one or more calls of \fBstdin()\fR) it may start handling this \s-1CGI\s0 request and prepare reply to send to web server. To send this data it should use method \f(CW$server\fR\->\fBstdout()\fR, where \f(CW$server\fR is object given to \fBnew()\fR while creating handler object (it should keep weak reference to \f(CW$server\fR inside to be able to reply). .ie n .IP "stdout( $data, $is_eof )" 4 .el .IP "stdout( \f(CW$data\fR, \f(CW$is_eof\fR )" 4 .IX Item "stdout( $data, $is_eof )" \&\s-1CGI\s0 may send reply in one or more parts. Last part should have \f(CW$is_eof\fR set to true. \s-1DESTROY\s0 method of handler object will be called shortly after handler object will do \f(CW$server\fR\->stdout( \f(CW$data\fR, 1 ). .SS "\s-1HANDLER EXAMPLE\s0" .IX Subsection "HANDLER EXAMPLE" This handler will process \s-1CGI\s0 requests one-by-one (i.e. in blocking mode). On request function \fBmain::main()\fR will be executed. That function may use standard \s-1CGI\s0.pm module to get request parameters and send it reply using usual print to \s-1STDOUT.\s0 .PP There no error-handling code in this example, see FCGI::EV::Std for more details. .PP .Vb 1 \& package FCGI::EV::ExampleHandler; \& \& use Scalar::Util qw( weaken ); \& use CGI::Stateless; # needed to re\-init CGI.pm state between requests \& \& sub new { \& my ($class, $server, $env) = @_; \& my $self = bless { \& server => $server, \& env => $env, \& stdin => q{}, \& }, $class; \& weaken($self\->{server}); \& return $self; \& } \& \& sub stdin { \& my ($self, $stdin, $is_eof) = @_; \& $self\->{stdin} .= $stdin; \& if ($is_eof) { \& local *STDIN; \& open STDIN, \*(Aq<\*(Aq, \e$self\->{stdin}; \& local %ENV = %{ $self\->{env} }; \& local $CGI::Q = CGI::Stateless\->new(); \& local *STDOUT; \& my $reply = q{}; \& open STDOUT, \*(Aq>\*(Aq, \e$reply; \& main::main(); \& $self\->{server}\->stdout($reply, 1); \& } \& return; \& } .Ve .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" There no errors returned in any way by this module, but there few warning messages may be printed: .ie n .IP """FCGI::EV: IO: %s""" 4 .el .IP "\f(CWFCGI::EV: IO: %s\fR" 4 .IX Item "FCGI::EV: IO: %s" While doing I/O with web server error \f(CW%s\fR happened and connection was closed. .ie n .IP """FCGI::EV: %s""" 4 .el .IP "\f(CWFCGI::EV: %s\fR" 4 .IX Item "FCGI::EV: %s" While parsing data from web server error \f(CW%s\fR happened and connection was closed. (That error probably mean bug either in web server or this module.) .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests through the issue tracker at . You will be notified automatically of any progress on your issue. .SS "Source Code" .IX Subsection "Source Code" This is open source software. The code repository is available for public review and contribution under the terms of the license. Feel free to fork the repository and submit pull requests. .PP .PP .Vb 1 \& git clone https://github.com/powerman/perl\-FCGI\-EV.git .Ve .SS "Resources" .IX Subsection "Resources" .IP "\(bu" 4 MetaCPAN Search .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Testers Matrix .Sp .IP "\(bu" 4 \&\s-1CPANTS: A CPAN\s0 Testing Service (Kwalitee) .Sp .SH "AUTHOR" .IX Header "AUTHOR" Alex Efros .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2009\- by Alex Efros . .PP This is free software, licensed under: .PP .Vb 1 \& The MIT (X11) License .Ve