FastCGI is a webserver independant API that allows for the creation of persistant web applications as simply and easily as creating CGIs. A persistant application like this will be an order of magnitude faster than a CGI, since it avoids the overhead of constantly creating new processes and then initializing your application, and allows you to maintain objects across multiple requests. FastCGI applications have performance similar to webserver API's such as PHP and mod_perl, but because they run as a seperate process, a fastCGI application can never disrupt the operation of your webserver, it can run as a different user from your webserver, or it can even run on a different server.
The module source code can be downloaded here as a gzipped tarball. A PGP signature is also available, and can be verified using my public key (amontague@siriushosting.com).
The following basic documentation should allow you to compile and install the pike fastCGI module on any modern unix system with a C compiler. It assumes that you already have pike installed, and are familiar with basic unix commands.
First, download and install the fastcgi development kit from fastcgi.com, or install it using your
operating system's package management system. Next, download the pike fastCGI
module, and untar it. Now simply cd into the
Public_Web_FCGI-1.8 directory and run pike -x module to
configure and compile the module. Finally, to install the module simply run
pike -x module install as root.
The fastCGI documentation provides an excellent overview of how fastCGI applications work and what the various roles they can perform are. The documentation and examples here assume that you've already read that documentation, and only covers information specific to using pike to write fastCGI applications.
This module only allows the creation of real fastCGI applications, no backwards compatability is provided for using fastCGI apps as CGI scripts on webservers that lack fastCGI support. FCGI.open_socket() is used to create a socket to communicate with the webserver. Multiple threads or proccesses can use the same socket. Simply create a new FCGI object by calling FCGI.FCGI() with the file descriptor returned by open_socket(). Finally, call the accept() method of the FCGI object you created to accept a connection, and call its write() method to send data to the user's web browser.
Your FCGI object will have mappings for get, post, cookies, and files containing the data sent from the client to the server. It also has a status variable and a headers mapping, used to control what data is sent from the server to the client. The status and headers are automatically formatted and sent to the client the first time write() is called, or when finish() is called. For complete documentation see the module reference. Or for practical examples, see the code below.
The module is thread safe, and if you are doing any blocking operations like database queries, connecting to remote hosts, etc, then you should use threads. Be sure to lock the accept() with a mutex as shown in the threaded example. The get, post and cookies mappings can contain string, array(string), mapping(string:string), or mapping(string:array(string)). The html form syntax for each is as follows.
| HTML Source | Submission Results |
|---|---|
| <input name="username" value="bob" /> | post["username"] == "bob" |
| <input name="password" value="seekrit" /> <input name="password" value="seekrit" /> | post["password"] == ({ "seekrit", "seekrit" }) |
| <input name="user[firstname]" value="bob" /> <input name="user[lastname]" value="jones" /> | post["user"] == ([ "firstname":"bob", "lastname":"jones" ]) |
| <input name="user[name]" value="bob" /> <input name="user[password]" value="seekrit" /> <input name="user[password]" value="seekrit" /> | post["user"] == ([ "name":"bob", "password":({ "seekrit", "seekrit" }) ]) |