Introduction

#include <boost/cgi.hpp>
using namespace boost::cgi;

int main()
{
  request req;
  response resp;

  resp<< "Hello there, Universe. "
      << "-- " << req[get]["name"];

  return_(req, resp, 0); // write the response and 'return 0;' to the OS
}

An example request:

GET example.com/program_name?name=Mr.+Allison HTTP/1.0

Output (as viewed in a web browser):

Hello there, Universe. -- Mr. Allison

This CGI library is a reasonably high-level library for creating CGI, FastCGI or SCGI programs. Its scope is intentionally limited to the ''controller'' portion of the Model-View-Controller idiom. In other words, XML/HTML templates are not addressed, even if their use is highly recommended.

	Tip
	The Amortization example uses Google cTemplate for dealing with HTML templates. Consider having a look at it, or at the upcoming ''Karma'' part of Boost.Spirit.

Concepts

The library provides abstractions which hide details of the varying specifications of CGI, FastCGI and SCGI. The main abstractions are, briefly:

Concept	Purpose
`Request`	Access to all request data is done through a `Request` object.
`ProtocolService`	For those of you familiar with Boost.Asio, this is very similar to the `io_service` class (it actually uses one or more of these for its functionality). Its purpose is to provide certain guarantees when you are using asynchronous functions and/or multiple threads, so it essentially underpins the whole library.
`RequestAcceptor`	CGI applications handle one request per process, a limitation which doesn't apply to SCGI and FastCGI applications. Using a `RequestAcceptor` allows you to ignore protocol-specific details, without losing track of how fast each process takes on new requests.
`Response`	Using the `Response` class is only recommended, not required. It is a generally useful class for writing responses to requests. The class is lightweight and responses are protocol agnostic, allowing a response for a CGI request to be used to reply to a FastCGI request.
`Client` ^[a] .	Each request has an associated Client, which may represent a connection to the HTTP server associated with the current request. It is used when writing replies to requests. Note: it is possible to avoid exposure to it entirely if you use the `response` class and the `return_` macro.
^[a] Taken from simultaneous suggestions by Phil Endecott and Chris Kohlhoff

Protcols

See __protocoldetails_ for more.

In a nutshell, CGI is the simple and 'original' way of communicating with web servers. I'll assume you know what it is: one request per process and communication using standard input/output. A nice and simple way of making dynamic web pages.

	Tip
	If you're new to CGI, have a look at this: http://hoohoo.ncsa.uiuc.edu/cgi/

FastCGI was then developed as a means of allowing much more scalable CGI-like programs to be written. In fact, the FastCGI specification implies scalability was the main motivation for the protocol. Communication with the server works over sockets or pipes (only TCP sockets are supported for now). Each process and each connection can be used for handling multiple requests. In theory this means you could have a single monolithic process behind your HTTP server handling all incoming requests concurrently.

	Note
	Some initial benchmarks show that simple FastCGI programs are 3-5x faster than their CGI counterparts. When using database connections and/or HTML templates, the gap should get even bigger.

SCGI is essentially a simpler version of FastCGI - hence SimpleCGI - but is still a significant step up from vanilla CGI, mainly because each process can handle multiple requests. Use of FastCGI is recommended over SCGI, but unfortunately support for FastCGI is unreliable and buggy with some servers andor you may not have that option. [ *FIXME*] SCGI support isn't included yet.

Multiple Requests per Process

Having persistent processes is very handy. It removes so many of the limitations of traditional CGI programming; suddenly CGI programs aren't so different to desktop applications. CGI 'scripts' become FastCGI servers, capable of handling an arbitrary number of requests with each invocation (assuming they don't crash, or leak memory!). This gives you the freedom to keep database connections open between requests or cache ready-parsed responses, for example. Processing of a client request can even be continued in the case of the client crashing - the response can then be stored and given to them when they return - saving precious CPU cycles.

The downside is added complexity: managing multiple requests and having to keep a tight reign on memory/resource consumption.

You might think dealing with request queues could be a handful but, fortunately, management of the queue (or queues, if you'd prefer) can be largely isolated from everything else. Accepting requests and handling them are your two key responsibilities. That means that after you have set up a 'server' (ie. something that gathers requests), requests can be handled in an essentially protocol-agnostic way.

Now on to some demonstrations...