Document new interface.

Release 0.49

diff --git a/perl/ChangeLog b/perl/ChangeLog
index a9e2a8b..dd868a7 100644 (file)
--- a/perl/ChangeLog
+++ b/perl/ChangeLog
@@ -1,4 +1,12 @@
-Version 0.47 -- 27 August 1999  <skimo@kotnet.org> Sven Verdoolaege
+Version 0.49 -- 9 April 2000  <skimo@kotnet.org> Sven Verdoolaege
+
+       o General clean-ups
+       o Allow attaching/detaching
+       o Changed DESTROY behaviour
+       o Fixed default warn/die handler of old interface
+       o Document new interface
+
+Version 0.48 -- 27 August 1999  <skimo@kotnet.org> Sven Verdoolaege
 
        o perl 5.005_60 compatibility
        o locking on platforms that need it

diff --git a/perl/FCGI.pm b/perl/FCGI.pm
index 6981b68..2b73af9 100644 (file)
--- a/perl/FCGI.pm
+++ b/perl/FCGI.pm
@@ -1,4 +1,4 @@
-# $Id: FCGI.pm,v 1.7 2000/01/31 21:34:24 skimo Exp $
+# $Id: FCGI.pm,v 1.8 2000/04/09 19:00:12 skimo Exp $
 
 package FCGI;
 
@@ -21,6 +21,8 @@ bootstrap FCGI;
 
 # Autoload methods go after __END__, and are processed by the autosplit program.
 
+*FAIL_ACCEPT_ON_INTR = sub() { 1 };
+
 sub Request(;***$$$) {
     my @defaults = (\*STDIN, \*STDOUT, \*STDERR, \%ENV, 0, 0);
     splice @defaults,0,@_,@_;
@@ -88,6 +90,8 @@ sub PRINTF {
 
 1;
 
+=pod
+
 =head1 NAME
 
 FCGI - Fast CGI module
@@ -96,8 +100,10 @@ FCGI - Fast CGI module
 
     use FCGI;
 
-    $count = 0;
-    while(FCGI::accept() >= 0) {
+    my $count = 0;
+    my $request = FCGI::Request();
+
+    while($request->accept() >= 0) {
        print("Content-type: text/html\r\n\r\n", ++$count);
     }
 
@@ -107,27 +113,90 @@ Functions:
 
 =over 4
 
-=item FCGI::accept()
+=item FCGI::Request
+
+Creates a request handle. It has the following optional parameters:
+
+=over 8
+
+=item input perl file handle (default: \*STDIN)
+
+=item output perl file handle (default: \*STDOUT)
+
+=item error perl file handle (default: \*STDERR)
+
+These filehandles will be setup to act as input/output/error
+on succesful Accept.
+
+=item environment hash reference (default: \%ENV)
+
+The hash will be populated with the environment.
+
+=item socket (default: 0)
+
+Socket to communicate with the server.
+Can be the result of the OpenSocket function.
+For the moment, it's the file descriptor of the socket
+that should be passed. This may change in the future.
+
+=item flags (default: 0)
+
+Possible values:
 
-Accepts a connection. Returns 0 on success.
+=over 12
+
+=item FCGI::FAIL_ACCEPT_ON_INTR
+
+If set, Accept will fail if interrupted.
+It not set, it will just keep on waiting.
+
+=back
+
+=back
+
+Example usage:
+    my $req = FCGI::Request;
+
+or:
+    my %env;
+    my $in = new IO::Handle;
+    my $out = new IO::Handle;
+    my $err = new IO::Handle;
+    my $req = FCGI::Request($in, $out, $err, \%env);
+
+=item FCGI::OpenSocket(path, backlog)
+
+=item FCGI::CloseSocket(socket)
+
+Close a socket opened with OpenSocket.
+
+=item $req->Accept()
+
+Accepts a connection on $req, attaching the filehandles and
+populating the environment hash.
+Returns 0 on success.
 If a connection has been accepted before, the old
 one will be finished first.
 
-=item FCGI::finish()
+Note that unlike with the old interface, no die and warn
+handlers are installed by default.
+
+=item $req->Finish()
 
 Finishes accepted connection.
+Also detaches filehandles.
 
-=item FCGI::flush()
+=item $req->Flush()
 
 Flushes accepted connection.
 
-=item FCGI::set_exit_status(status)
+=item $req->Detach()
 
-Sets the exit status that finish returns to the server.
+Temporarily detaches filehandles on an accepted connection.
 
-=item FCGI::start_filter_data()
+=item $req->Attach()
 
-Does anyone use this function ?
+Re-attaches filehandles on an accepted connection.
 
 =back
 

diff --git a/perl/README b/perl/README
index 7d15ed5..2b4f8eb 100644 (file)
--- a/perl/README
+++ b/perl/README
@@ -1,4 +1,4 @@
-$Id: README,v 1.2 1999/02/28 17:46:30 skimo Exp $
+$Id: README,v 1.3 2000/04/09 19:00:12 skimo Exp $
 
     Copyright (c) 1996 Open Market, Inc.
     See the file "LICENSE.TERMS" for information on usage and redistribution
@@ -43,10 +43,11 @@ The configure.readme file describes how to run ./configure (and only that).
 If you're on a solaris system and your installed fcgi library is 2.02b
 or earlier, you'll probably want to use the included files.
 
-The FCGI module installs die and warn handlers that merely print
-the error/warning to STDERR (the default handlers print directly
-to stderr, which isn't redirected in the non sfio case). I'm not
-very happy with the result. Suggestions welcome.
+The old interface of the FCGI module installs die and warn 
+handlers that merely print the error/warning to STDERR (the 
+default handlers print directly to stderr, which isn't redirected 
+in the non sfio case). I'm not very happy with the result. 
+Suggestions welcome.
 
 Sven Verdoolaege
 skimo@kotnet.org

diff --git a/perl/oldinterface.pod b/perl/oldinterface.pod
new file mode 100644 (file)
index 0000000..bb288a1
--- /dev/null
+++ b/perl/oldinterface.pod
@@ -0,0 +1,50 @@
+=head1 NAME
+
+FCGI - Fast CGI module
+
+=head1 SYNOPSIS
+
+    use FCGI;
+
+    $count = 0;
+    while(FCGI::accept() >= 0) {
+       print("Content-type: text/html\r\n\r\n", ++$count);
+    }
+
+=head1 DESCRIPTION
+
+Functions:
+
+=over 4
+
+=item FCGI::accept()
+
+Accepts a connection. Returns 0 on success.
+If a connection has been accepted before, the old
+one will be finished first.
+
+=item FCGI::finish()
+
+Finishes accepted connection.
+
+=item FCGI::flush()
+
+Flushes accepted connection.
+
+=item FCGI::set_exit_status(status)
+
+Sets the exit status that finish returns to the server.
+
+=item FCGI::start_filter_data()
+
+Does anyone use this function ?
+
+=back
+
+=head1 AUTHOR
+
+Sven Verdoolaege <skimo@kotnet.org>
+
+=cut
+
+__END__