|
|
Boost-Commit : |
From: lists.drrngrvy_at_[hidden]
Date: 2008-03-21 20:08:08
Author: drrngrvy
Date: 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
New Revision: 43793
URL: http://svn.boost.org/trac/boost/changeset/43793
Log:
Updated documentation. Commit only done to reflect large *code* changes compared to the last revision of documentation. This documentation set is crude, incomplete and annoyingly poor.
Added:
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/status.qbk (contents, props changed)
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/examples.qbk (contents, props changed)
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/scaling.qbk (contents, props changed)
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/step_one.qbk (contents, props changed)
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/tutorial.qbk (contents, props changed)
Removed:
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/program_flow.txt
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/building.qbk
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/meta_data.qbk
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/meta_variables.qbk
Text files modified:
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/Jamfile.v2 | 64 ++++++++++++++++++++++-----------------
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/acknowledgements.qbk | 10 +++++
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/cgi.qbk | 42 ++++++++++++++++---------
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/future_development.qbk | 18 +++++-----
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/introduction.qbk | 58 +++++++++++++++++++++++------------
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/library_organisation.qbk | 2
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/preface.qbk | 8 ++++
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/responses.qbk | 6 +-
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide.qbk | 3 +
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/building.qbk | 10 +++---
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/handling_requests.qbk | 2
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/headers.qbk | 39 -----------------------
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial.qbk | 1
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk | 2
sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/variables.qbk | 60 ++++++++++++++++++------------------
15 files changed, 171 insertions(+), 154 deletions(-)
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/Jamfile.v2
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/Jamfile.v2 (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/Jamfile.v2 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -3,57 +3,65 @@
# subject to the Boost Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-project cgi.docs
- #: build-dir ../../../bin.v2
- ;
+#project boost.cgi.docs
+# ;
-import boostbook : boostbook ;
+#import boostbook : boostbook ;
import quickbook ;
import doxygen ;
# compile the doxygen sources here
-doxygen cgi_dox
- :
+#doxygen cgi_dox
+# :
# [ glob-tree ../../../boost/cgi/*.hpp : .svn ]
# [ glob-tree ../../../boost/libs/cgi/src/*.cpp : .svn ]
- [ glob ../../../boost/cgi/*.hpp ]
- [ glob ../../../boost/cgi/gateway_impl/*.hpp ]
- [ glob ../../../boost/cgi/gateway_service/*.hpp ]
- [ glob ../../../boost/cgi/http/*.hpp ]
- [ glob ../../../boost/cgi/connections/*.hpp ]
- [ glob ../../../boost/cgi/request_impl/*.hpp ]
- [ glob ../../../boost/cgi/request_service/*.hpp ]
- :
- <doxygen:param>HIDE_UNDOC_MEMBERS=NO
- <doxygen:param>EXTRACT_PRIVATE=NO
- #<doxygen:param>EXTRACT_ALL=YES
- <doxygen:param>SEARCH_INCLUDES=YES
- <doxygen:param>INCLUDE_PATH=$(BOOST_ROOT)
- ;
+# [ glob ../../../boost/cgi/*.hpp ]
+# [ glob ../../../boost/cgi/gateway_impl/*.hpp ]
+# [ glob ../../../boost/cgi/gateway_service/*.hpp ]
+# [ glob ../../../boost/cgi/http/*.hpp ]
+# [ glob ../../../boost/cgi/connections/*.hpp ]
+# [ glob ../../../boost/cgi/request_impl/*.hpp ]
+# [ glob ../../../boost/cgi/request_service/*.hpp ]
+# :
+# <doxygen:param>HIDE_UNDOC_MEMBERS=NO
+# <doxygen:param>EXTRACT_PRIVATE=NO
+# #<doxygen:param>EXTRACT_ALL=YES
+# <doxygen:param>SEARCH_INCLUDES=YES
+# <doxygen:param>INCLUDE_PATH=$(BOOST_ROOT)
+# ;
xml cgi_xml : src/cgi.qbk ;
boostbook standalone
:
cgi_xml
- cgi_dox
+# cgi_dox
:
- <xsl:param>boost.root=/usr/local/src/cgi/svn.boost.org/
- <xsl:param>boost.libraries=/usr/local/src/boost/libs/libraries.htm
-# <xsl:param>boost.images=http://beta.boost.org/images
+ <doxygen.processor>doxproc
+ <doxygen.doxproc.index>no
+ <doxygen.doxproc.title>"Developer Reference"
+ <doxygen.doxproc.id>"developer_reference"
+
+ <xsl:param>project.root=../../../..
+ <xsl:param>boost.libraries=/usr/local/src/boost/trunk/libs/libraries.htm
+ <xsl:param>boost.images=http://beta.boost.org/images
# the depth (of sub-pages) the TOC shows
<xsl:param>toc.max.depth=1
-
+ # Path to the stylesheet
+ <xsl:param>html.stylesheet=../../../../../../../../boost/trunk/doc/html/boostbook.css
+
#
<xsl:param>toc.section.depth=2
- # how many sections are on the first page
+ # How far down we go with TOC's
+ <xsl:param>generate.section.toc.level=10
+ # how many sections are on the first page
<xsl:param>chunk.first.sections=1
# To chunk (together) or not to chunk (divide)
- <xsl:param>chunk.section.depth=1 # chunk
- ;
+ <xsl:param>chunk.section.depth=2 # chunk
+ ;
#install html
# :
Deleted: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/program_flow.txt
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/program_flow.txt 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
+++ (empty file)
@@ -1,47 +0,0 @@
-service
--> makes:
- an io_service object, or takes a reference from the user
- a gateway
- a request queue (std::queue, empty)
- a container for request_parsers (std::set, empty)
- a dispatcher
-
-gateway
--> constructed with the max number of connections allowed
--> makes:
- an acceptor
- a container for connections (std::set, empty)
--> asynchronously accepts a connection
--> verifies the connection is good: if not, then try another allowed type
--> notifies the service when a connection is created
-
-service
--> makes:
- a request_parser
-
-request_parser
--> constructed with the connection and the service
--> makes:
- a pointer to the request currently being served
- a relevant header object (uninitialized)
- a note of the current state of the parser
--> requests the connection read into a supplied buffer supplied by the
- request_parser
-
-connection
--> constructed with the request_parser
--> does an async_read into the buffer supplied by the parser_
--> notify the parser_ when the read is complete: call parser_.parse()
-
-request_parser
--> parse the supplied data
--> if it's a header, interpret it, handle it if necessary and then continue
--> the return value of parse():
- true => all ok, stop reading for now
- false => error: stop reading, close connection
- indeterminite => all ok, read some more
--> eventually, the request will be ready for being handled
- it's added to the request queue
--> read the next header only, in case it relates to another request
-
-
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/acknowledgements.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/acknowledgements.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/acknowledgements.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -7,6 +7,14 @@
[section Acknowledgements]
-Provided courtesy of the Google Summer of Code!
+Provided courtesy of the Google Summer of Code (GSoC '08)!
+
+Christopher Kohlhoff: for crafting Boost.Asio, which does most of the hard stuff. Chris mentored me through the GSoC (no mean feat!), without which this library would not be in your hands.
+
+Phil Endecott: for offering use-cases and encouragement at the start of the GSoC and for coming up with many further suggestions (such as the Client concept) in the months since.
+
+The Boost mailing lists: for so many deeply critical and objective comments about the library. :) That, is a relentless and ['Good Thing].
+
+[-forgetting everyone's names:] Jeff Dunlap
[endsect]
Deleted: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/building.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/building.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
+++ (empty file)
@@ -1,67 +0,0 @@
-[/
- / Copyright (c) 2007 Darren Garvey
- /
- / Distributed under the Boost Software License, Version 1.0. (See accompanying
- / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- /]
-
-[section Building]
-
-Boost.CGI is a header-only library (for now), but it relies on [link __boost_system__ Boost.System], which for now must be built.
-
-[/h5 What you need:]
-
-[note
-* Boost-related elements can be downloaded from the Boost download site at sourceforge, here: http://sf.net/project/showfiles.php?group_id=7586
-
-* "invoking `bjam`" implies calling "`bjam --toolset=`[link __toolsets__ one_of_these]". More information can be found [link __boost_getting_started__ here] (these are general instructions for building Boost [*and] configuring `bjam`. Following these instructions will also 'tick' the first two requirements below.
-]
-
-[table What you need
- [
- [Element]
- [Optional?]
- [Instructions]
- ]
- [
- [Boost.Jam - `bjam`]
- [No]
- [
-Download 'boost-jam' (precompiled versions are highly recommended) and make it accessible by putting it somewhere pointed to by your system's PATH.
- ]
- ]
- [
- [Boost.System]
- [No]
- [
-* Download the latest Boost distro, 'boost'.
-
-* Set the environment variable BOOST_ROOT on your system to the download location.
-
-* Go to the directory BOOST_ROOT and invoke `bjam --with-system install` (see above). This should finish without any fails.
- ]
- ]
- [
- [Documentation]
- [Yes]
- [
-These are built by going to the libs/cgi/doc directory and invoking `bjam` (see above). You can then read the docs by directing your browser to libs/cgi/index.html
- ]
- ]
- [
- [Unit tests]
- [Yes]
- [
-Tests can be run by going to the libs/cgi/test directory and invoking `bjam` (see above). Boost.CGI aims to be cross-platform, but not all platforms are available for testing. If any tests fail, problems can be reported to [link __reporting_problems__ here], please.
- ]
- ]
- [
- [Examples]
- [Yes]
- [
-The examples are a useful guide to uses of the library. They are also useful for testing your server configuration. They can all be found in the lib/cgi/example directory. Invoking `bjam` in the example directory should build all examples whereas invoking `bjam` in each sub-directory will build only the example contained therein.
- ]
- ]
-]
-
-[endsect]
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/cgi.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/cgi.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/cgi.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -10,7 +10,7 @@
[version 0.01]
[id boost.cgi]
[dirname the_document_dir]
- [copyright 2007 Darren Garvey]
+ [copyright 2007 2008 Darren Garvey]
[purpose Thoughts about CGI implementation]
[authors [Garvey, Darren]]
[license
@@ -31,6 +31,8 @@
[def __boost__ [@http://boost.org/ Boost]]
[def __asio__ [@http://asio.sourceforge.net Boost.Asio]]
+[def __get_boost__ [@http://beta.boost.org/users/download get Boost]]
+[def __boost_jam__ [@http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=72941 Boost.Jam]]
[def __reading_the_docs__ [link boost.cgi.intro.reading_the_docs reading the docs]]
[def __naming_conventions__ [link boost.cgi.intro.naming_conventions naming conventions]]
@@ -38,6 +40,12 @@
[def __tutorial__ [link boost.cgi.tutorial tutorial]]
[def __reference__ [link /doc/html/cgi/reference.html reference]]
+[def __current_branch__ http://svn.boost.org/trac/boost/browser/sandbox/SOC/2007/cgi/branches/acceptor_work]
+
+[def __examples__ [@http://svn.boost.org/trac/boost/browser/sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/example examples]]
+[def __amort_example__ [@http://svn.boost.org/trac/boost/browser/sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/example/acgi/amortization Amortization]]
+
+
[def __GET__ `GET` ]
[def __POST__ `POST`]
[def __HEAD__ `HEAD`]
@@ -79,27 +87,31 @@
[include:intro introduction.qbk]
-[section:gs Getting Started]
-
-This section of the documentation is probably best read before the [link __tutorial__ tutorial]. In a nutshell, this is a quick and dirty run-through of how to get and install the library [-and configure your server].
-
-[include:building user_guide/building.qbk]
-
-[include:server_config user_guide/server_configuration.qbk]
-
-[include:headers user_guide/headers.qbk]
+[/
+/[section:gs Getting Started]
+/
+/This section of the documentation is probably best read before the [link __tutorial__ tutorial]. In a nutshell, this is a quick and dirty run-through of how to get and install the library [-and configure your server].
+/
+/[include:building user_guide/building.qbk]
+/
+/[include:server_config user_guide/server_configuration.qbk]
+/
+/[include:headers user_guide/headers.qbk]
+/
+/[endsect]
+/]
-[endsect]
+[include user_guide.qbk]
-[include:tutorial user_guide/tutorial.qbk]
+[/include:tutorial user_guide/tutorial.qbk]
-[include:protocols user_guide/protocols.qbk]
+[/include:protocols user_guide/protocols.qbk]
-[include:examples user_guide/examples.qbk]
+[/include:examples user_guide/examples.qbk]
[/include:ug user_guide.qbk]
-[xinclude ../cgi_dox.boostbook]
+[xinclude ../cgi_dox.xml]
[include:future future_development.qbk]
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/future_development.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/future_development.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/future_development.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -19,7 +19,7 @@
FastCGI support is essential to any modern CGI library. There is currently ['no] known FastCGI library for C or C++ that aims to implement the complete [@http://www.fastcgi.com/devkit/doc/fcgi-spec.html FastCGI 1.0] specification. Providing support for multiplexing FastCGI daemons is one of this library's major goals.
-There are a couple of issues that have yet to be worked out, but in general the new framework is known to 'fit' with all the details of FastCGI and should lend itself to an efficient implementation.
+There are a couple of issues that have yet to be worked out, but in general the new framework is known to 'fit' with all the details of FastCGI and should lend itself to an efficient implementation. It's only partially working at the moment.
[h4 Access to error output streams]
@@ -53,8 +53,8 @@
cgi::request req;
cgi::response resp;
-cgi::map::iterator iter = req.form_().find("number");
-if (iter != cgi::map::iterator::end())
+cgi::map::const_iterator iter = req.form().find("number");
+if (iter != cgi::map::const_iterator())
{
rep<< "You picked no numbers...";
}
@@ -62,7 +62,7 @@
{
int sum(0);
resp<< "Your numbers are: ";
- for(; iter != cgi::map::iterator::end(); ++iter)
+ for(; iter != cgi::map::const_iterator(); ++iter)
{
resp<< iter->second << " ";
sum += boost::lexical_cast<int>(iter->second);
@@ -79,18 +79,18 @@
cgi::request req;
cgi::response resp;
-cgi::param parm = req.form_("number");
-if (parm.empty())
+cgi::param p = req.form("number");
+if (p.empty())
{
resp<< "You picked no numbers...";
}
else
{
int sum(0);
- for(; parm != parm.end(); ++parm)
+ for(; p != p.end(); ++p)
{
- resp<< parm << " ";
- sum += parm.as<int>());
+ resp<< p << " ";
+ sum += p.as<int>());
}
resp<< std::endl
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/introduction.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/introduction.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/introduction.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -8,8 +8,8 @@
[section:intro Introduction]
``
-#include <boost/cgi/cgi.hpp>
-using namespace cgi;
+#include <boost/cgi.hpp>
+using namespace boost::cgi;
int main()
{
@@ -17,40 +17,56 @@
response resp;
resp<< "Hello there, Universe. "
- << "Oh wait, it's just you, " << req.form("name")
- << ", isn't it.";
+ << "-- " << req.GET("name")
+ << content_type("text/plain");
return_(req, resp, 0); // write the response and 'return 0;'
}
+
+Example request:
+example.com/program_name?name=Mr.+Allison
+
+Output:
+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 (consider having a look at google's cTemplate, or the upcoming ''Karma'' part of Boost.Spirit).
+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 __amort_example__ example uses Google cTemplate for dealing with HTML templates. Consider having a look at it, or at the upcoming ''Karma'' part of Boost.Spirit.
+]
[h4 Concepts]
-The library provides abstractions which hide details of the widely varying specifications of CGI, FastCGI and SCGI. These abstractions are briefly:
+The library provides abstractions which hide details of the vastly different specifications of CGI, FastCGI and SCGI. The main abstractions are, briefly:
[table
[
[Concept] [Purpose]
]
[
- [RequestAcceptor]
- [CGI applications handle one request per process, while both SCGI and FastCGI allow each process to handle many requests, potentially at the same time. A RequestAcceptor makes it easy to ignore these differences and it also allows you to control how fast your process takes on new requests.
- ]
+ [`Request`]
+ [Access to all request data is done through a `Request` object.]
]
[
- [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.]
]
[
- [Client]
- [Each request has an associated Client, which will usually represent a connection to the HTTP server associated with the current request.
+ [`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.
]
]
[
- [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. The asynchronous stuff is what underpins this whole library.]
+ [`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`[footnote Taken from simultaneous suggestions by Phil Endecott and Chris Kohlhoff].]
+ [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.
+ ]
]
]
@@ -60,16 +76,18 @@
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 ['web pages that can change].
-FastCGI was then developed as a means of allowing much more scalable CGI-like programs to be written. In fact, the FastCGI specification implies maximal efficiency was the main goal of the protocol. Communication with the server now 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 thousands of concurrent requests.
+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.
-SCGI is essentially a simpler version - hence [*S]imple[*CGI] - of FastCGI but is still a significant step up from vanilla CGI: as with FastCGI, 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 so it may not be a matter of choice.
+SCGI is essentially a simpler version - hence [*S]imple[*CGI] - of FastCGI 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 and/or you may not have that option.
[h4 Multiple Requests per Process]
-So I keep harping on about this, that's because it removes so many limitations of traditional CGI programming. In return for the added complexity, your programs become complete servers, capable of handling arbitrary numbers of requests during 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.
+So I keep harping on about this, that's because it removes so many limitations of traditional CGI programming. Your programs can become 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 the handling of each request. That means that after you have set up a 'server' (ie. something that gathers requests), requests can be handled in much the same way as they would be with a standard CGI program that uses this library.
+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 demonstrations...
+Now on to some demonstrations...
[endsect]
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/library_organisation.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/library_organisation.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/library_organisation.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -20,5 +20,5 @@
Shared components and types live in the namespace `boost::cgi::common`, but are brought into the three namespaces above, where necessary and/or relevant. You should never have to use `boost::cgi::common::*` in your code; if you find you do, kindly [link __bugs__ report it] as a bug.
]
-[endsect][/ library_organisation]
+[endsect] [/ library_organisation]
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/preface.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/preface.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/preface.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -13,7 +13,13 @@
[h3 Overview]
-Boost.CGI is an open-source library for writing CGI programs in Standard C++. The library supports vanilla CGI, SCGI and FastCGI (SCGI/FastCGI don't really work yet) so it can be used to write anything from simple 'admin scripts' to full-fledged, scalable applications. This library rests on top of and should appear familiar to users of Boost.Asio, a cross-platform asynchronous networking library in boost-style C++. One of the main aims of the library is to allow programs to be written for any of the supported protocols without any real modification.
+[* THIS LIBRARY IS NOT A PART OF BOOST.]
+
+Boost.CGI is an open-source library for writing CGI programs in Standard C++. The library supports vanilla CGI, SCGI and FastCGI (SCGI doesn't really work yet) so it can be used to write anything from simple 'CGI scripts' to full-fledged, scalable applications. This library rests on top of and should appear familiar to users of Boost.Asio, a cross-platform asynchronous (and ['fast]) networking library. One of the main aims of the library is to allow programs to be written for any of the supported protocols without any real modification.
+
+[tip
+ The [*Deep End] is located in the examples directory. Try looking for the __examples__.
+]
[h3 Motivation]
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/responses.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/responses.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/responses.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -39,7 +39,7 @@
And that's most of what you need to know to get using the `response`. Check out the [classref cgi::response] for the rest.
-[endsect][/ example]
+[endsect] [/ example]
[section:api `cgi::response` Interface]
@@ -51,7 +51,7 @@
]
-[endsect][/ api]
+[endsect] [/ api]
-[endsect][/ responses]
+[endsect] [/ responses]
Added: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/status.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/status.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -0,0 +1,10 @@
+
+[section Status]
+
+This is a grid of what is and isn't implemented yet. It's probably not complete and will quite possibly be out of date as you read this.
+
+[table
+ [
+ [[Protocol]
+
+[endsect] [/ status]
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -21,7 +21,8 @@
[/include:tutorial user_guide/tutorial.qbk]
-[/include:examples user_guide/examples.qbk]
+[include:examples user_guide/examples.qbk]
+[include user_guide/tutorial/tutorial.qbk]
[/endsect]
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/building.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/building.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/building.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -7,14 +7,14 @@
[section Building]
-__this__ is a header-only library, but it relies on [link __boost_system__ Boost.System], which must be built.
+__this__ is a header-only library, but it relies on [link __boost_system__ Boost.System], which for now should be built.
[/h5 What you need:]
Boost-related elements can be downloaded from the Boost download site at sourceforge, [@http://sf.net/project/showfiles.php?group_id=7586 located here].
[note
-"invoking `bjam`" implies calling "`bjam --toolset=<your_toolset>`", where "`<your_toolset>`" is one of [@http://www.boost.org/doc/html/bbv2/reference.html#bbv2.reference.tools.compilers these]. More information can be found [link __boost_getting_started__ here] (these are general instructions for building Boost [*and] configuring `bjam`. Following these instructions will also 'tick' the first two requirements below.
+"invoking `bjam`" implies calling "`bjam --toolset=<your_toolset>`", where "`<your_toolset>`" is one of [@http://www.boost.org/doc/html/bbv2/reference.html#bbv2.reference.tools.compilers these]. More information can be found [@http://boost.org/more/getting_started/index.html here] (these are general instructions for building Boost [*and] configuring `bjam`. Following these instructions will also 'tick' the first two requirements below.
]
[table What you need
@@ -22,7 +22,7 @@
[
[Boost.Jam - `bjam`]
[No]
- [Download 'boost-jam' (precomiled versions are highly recommended) and make it accessible to your system's PATH.]
+ [Download '__boost_jam__' (precompiled versions are highly recommended) and make it accessible to your system's PATH.]
]
[
[Boost.System]
@@ -31,7 +31,7 @@
2. Set the environment variable BOOST_ROOT on your system to the download location.
- 3. Go to the directory BOOST_ROOT and invoke `bjam` (see above), passing it `--with-system --layout=system install` on the command line. This should finish without any fails.]
+ 3. Go to the directory BOOST_ROOT and invoke `bjam` (see above), passing it `--with-system --layout=system install` on the command line. This should finish without any failures.]
]
[
[Documentation]
@@ -46,7 +46,7 @@
[
[Examples]
[Yes]
- [There are some examples provided with the library in the `libs/cgi/example` directory. They are useful for testing your server configuration, which can be notoriously tricky. They can all be found in the lib/cgi/example directory. Invoking `bjam` in the example directory should build all examples whereas invoking `bjam` in each sub-directory will build only the example contained therein.]
+ [There are some examples provided with the library in the `libs/cgi/example` directory. They are useful for learning the library or testing your server configuration, something that can be tricky. They can all be found in the lib/cgi/example directory. Invoking `bjam` in the example directory should build all examples whereas invoking `bjam` in each sub-directory will build only the example contained therein.]
]
]
Added: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/examples.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/examples.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -0,0 +1,76 @@
+
+[section Examples]
+
+[template example_link[protocol example_name link_text] [@../../example/\ [protocol]/[example_name]/main.cpp [link_text]]]
+
+The examples can be built by going into their directory and typing `bjam`. If you have a server set up and wish to test the applications behind them, you can automatically copy them to your server's cgi-bin (or fcgi-bin or scgi-bin) one of two ways:
+
+* `bjam install --cgi-bin=/usr/lib/cgi-bin` - installs the program (or set of programs) into `/usr/lib/cgi-bin` [*iff] they are a CGI program. If you want to install examples in the `/libs/cgi/example/fcgi/` directory, for instance, type the above but replace `--cgi-bin` to `--fcgi-bin`.
+
+* set the environment variable `BOOST_CGI_BIN_PATH` (or `BOOST_FCGI_BIN_PATH`/`BOOST_SCGI_BIN_PATH`) and just type `bjam install`. The example(s) will be installed into the relevant directory.
+
+[note
+ The command line option will override the environment variable, so you can use the environment variables for default installation.
+]
+
+[section aCGI]
+
+[import ../../../example/cgi/echo/main.cpp]
+
+Linky: [example_link acgi..echo..aCGI Echo example]
+
+[@../../../example/cgi/echo/main.cpp]
+
+[file]
+
+[endsect] [/ acgi]
+
+[section CGI]
+
+[endsect] [/ cgi]
+
+[section FastCGI]
+
+[def __fcgi_hello_world__ ../../../example/fcgi/hello_world/main.cpp]
+[def __fcgi_echo__ ../../../example/fcgi/echo/main.cpp]
+
+[section "Hello, world."]
+
+[import ../../../example/fcgi/hello_world/main.cpp]
+
+Click to see the [link __fcgi_hello_world__ source file]
+
+[file]
+
+[endsect] [/ hello_world]
+
+[section Echo]
+
+[/import __fcgi_echo__]
+
+[template call_import[protocol_t example_name]
+[import ../../example/\ [protocol_t]/[name]/main.cpp]
+]
+
+[call_import fcgi..amortization]
+
+[template import_example[protocol name]
+
+[import ../../example/[protocol]/[name]/main.cpp]
+
+Click to see the [@../../../example/[protocol]/[name]/main.cpp source file].
+
+]
+
+[import_example fcgi..echo]
+
+Click to see the [/example_link[fcgi..echo..source file]].
+
+[fcgi_echo]
+
+[endsect] [/ echo]
+
+[endsect] [/ fastcgi]
+
+[endsect]
+
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/handling_requests.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/handling_requests.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/handling_requests.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -26,6 +26,6 @@
[include meta_data.qbk]
-[include wrapping_up.qbk]
+[/include wrapping_up.qbk]
[endsect]
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/headers.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/headers.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/headers.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -8,7 +8,7 @@
[section:headers Choosing the correct headers]
-Depending on what protocol you plan on using, you should include [*one] of the following headers:
+Depending on what protocol you plan on using, you should include one of the following headers:
``
#include <boost/cgi.hpp> // include header files for any protocol
@@ -22,41 +22,4 @@
#include <boost/cgi/scgi.hpp> // include all headers required for SCGI usage
``
-Including <boost/cgi.hpp> [*and] defining one of the `BOOST_CGI_IMPLICIT_*` macros is equivalent to including one of the protocol-specific headers. As such, the shortcuts `cgi::request`, `cgi::acceptor` and `cgi::service` become `typedef`s for that protocol's more explicit types.
-
-For example:
-``
-#define BOOST_CGI_IMPLICIT_SCGI 1
-#include <boost/cgi.hpp>
-cgi::service service; // implicit SCGI service
-cgi::request req(service); // implicit SCGI request
-``
-Is equivalent to:
-``
-#include <boost/cgi/scgi.hpp>
-cgi::service service; // implicit SCGI service
-cgi::request req(service); // implicit SCGI request
-``
-Which is equivalent to:
-``
-#include <boost/cgi.hpp>
-cgi::scgi_service service; // SCGI service
-cgi::scgi_request req(service); // SCGI request
-``
-and:
-``
-#include <boost/cgi/scgi.hpp>
-cgi::scgi_service service; // SCGI service
-cgi::scgi_request req(service); // SCGI request
-``
-But:
-``
-#include <boost/cgi.hpp>
-cgi::service service; // error: cgi::service does not name a type
-cgi::request req(service); // error: cgi::request does not name a type
-``
-will not work.
-
-Note that the explicit form - `scgi_request`/`scgi_service` - is always valid, assuming you have (implicitly or otherwise) included, for example, `<boost/cgi/scgi/request.hpp>`.
-
[endsect] [/ headers]
Deleted: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/meta_data.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/meta_data.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
+++ (empty file)
@@ -1,44 +0,0 @@
-[/
- / Copyright (c) 2007 Darren Garvey
- /
- / Distributed under the Boost Software License, Version 1.0. (See accompanying
- / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- /]
-
-[section:meta_data Request Meta-data]
-
-[note
-A request [*must] be [link __loading__ loaded] before the meta-data can be accessed. The ['only] exception to this rule is calling `meta_env()` on CGI and aCGI request objects. These are (essentially) equivalent to a call to `::getenv()` and will always work. However, exploit this 'feature' cautiously as it will render a program unsuitable for use with the more scalable protocols on offer.
-]
-
-There are five member functions of `basic_request<>` that provide access to the meta-data associated to that request. These are:
-
-[/
-[table Meta-data accessor functions
-[[Function name] [Arguement(s)] [Return value]]
-]
-]
-
-* `std::string meta_env(const std::string& name)`
- Takes the name of the environment variable wanted and returns the value associated with it.
-
-* `std::string meta_get(const std::string& name)`
- Takes the name of the CGI GET variable and returns the value associated with it (if any).
-
-* `std::string meta_post(const std::string& name, bool greedy = true)`
- Takes the name of the CGI POST variable and returns the value associated with it (if any). If `greedy == true` - which it is by default - then more data is read from the request if required until all of the POST data (ie. stdin) has been read.
-
-* `std::string meta_cookie(const std::string& name)`
- Takes the name of the cookie variable and returns the value associated with it (if any).
-
-* `std::string meta_var(const std::String& name, bool greedy = true)`
-
-[note should this return a `std::pair<std::string, cgi::meta_type>` instead, where a `cgi::meta_type` is one of `get`, `post`, `env`, or `cookie`?]
-
- Takes the name of [*any] meta-variable and returns the value associated with it (if any). If `greedy == true` - which it is by default - then more data is read from the request if required until either the requested variable is found or all of the POST data has been read, which ever comes first.
-
-[warning
-It is generally accepted that a CGI program should pay attention to where meta-data has come from.[footnote citations w.r.t. XSS and GET/POST/COOKIE ambiguities] In other words, since `meta_var` removes such distinctions, its use should be limited to places where origin of the variable doesn't matter. For example, a language setting (like `"hl=en"`, as Google uses) could come from anywhere and doing so is not an issue.
-]
-
-[endsect]
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -39,5 +39,6 @@
[include:wrapping_up wrapping_up.qbk]
+[/endsect]
[endsect]
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/accepting.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -73,4 +73,4 @@
}
``
-[endsect]
+[endsect] [/ accepting]
Deleted: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/meta_data.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
+++ (empty file)
@@ -1,55 +0,0 @@
-[/
- / Copyright (c) 2007 Darren Garvey
- /
- / Distributed under the Boost Software License, Version 1.0. (See accompanying
- / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- /]
-
-[def __xss_footnote__ It is generally accepted that a CGI program should pay attention to where meta-data has come from.[footnote citations w.r.t. XSS and GET/POST/HTTP_COOKIE ambiguities] In other words, since `meta_var` removes such distinctions, its use should be limited to places where the source of the variable doesn't matter. For example, a language toggle (like `"hl=en"`, as Google uses) could come from anywhere and doing so is not an issue.]
-
-
-[section:variables Using Request Variables]
-
-[warning
-A request [*must] be [link __loading__ loaded] before the meta-data can be accessed. The ['only] exception to this rule is calling `meta_env()` on CGI and aCGI request objects. These are (essentially) equivalent to a call to `::getenv()` and will always work. However, exploit this 'feature' cautiously as it won't work with FastCGI or SCGI requests.
-]
-
-There are six member functions of `basic_request<>` that provide access to the meta-variables associated to that request.
-
-[table Meta-variable accessor functions
- [[Function signature] [Purpose]]
- [
- [`std::string meta_env(const std::string&)`]
- [Takes the name of the environment variable wanted and returns the value associated with it.]
- ]
- [
- [`std::string meta_get(const std::string&)`]
- [Takes the name of the __GET__ variable and returns the value associated with it (if any).]
- ]
- [
- [`std::string meta_post(const std::string&, bool greedy = true)`]
- [Takes the name of a __POST__ variable and returns the value associated with it (if any).
-
- If `greedy == true` - which it is by default - then more data is read from the request if required until all of the POST data has been read.]
- ]
- [
- [`std::string meta_form(const std::string&, bool greedy = true)`]
- [Takes the name of either a __GET__ or __POST__ variable and returns the value associated with it (if any). Note that this will only search the type referred to by the environment variable `"REQUEST_METHOD"`, so it is generally safe to use.
-
- If `greedy == true` - which it is by default - then more data is read from the request as required until all of the POST data has been read.]
- ]
- [
- [`std::string meta_cookie(const std::string& name)`]
- [Takes the name of the cookie variable and returns the value associated with it (if any).]
- ]
- [
- [`std::string meta_var(const std::string& name, bool greedy = true)`]
- [Takes the name of [*any] meta-variable and returns the value associated with it (if any).[footnote __xss_footnote__]
-
- If `greedy == true` - which it is by default - then more data is read from the request if required until either the requested variable is found or all of the POST data has been read, which ever comes first.]
- ]
-]
-
-[/ should this return a `std::pair<std::string, cgi::meta_type>` instead, where a `cgi::meta_type` is one of `get`, `post`, `env`, or `cookie`?]
-
-[endsect]
Deleted: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/meta_variables.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/meta_variables.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
+++ (empty file)
@@ -1,55 +0,0 @@
-[/
- / Copyright (c) 2007 Darren Garvey
- /
- / Distributed under the Boost Software License, Version 1.0. (See accompanying
- / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- /]
-
-[def __xss_footnote__ It is generally accepted that a CGI program should pay attention to where meta-data has come from (eg. [@http://www.google.com/search?q=XSS XSS]). In other words, since `meta_var` removes such distinctions, its use should be limited to places where the source of the variable doesn't matter. For example, a language toggle (like `"hl=en"`, as Google uses) could come from anywhere and doing so is not an issue.]
-
-
-[section:variables Using Request Variables]
-
-[warning
-A request [*must] be [link __loading__ loaded] before the meta-data can be accessed. The ['only] exception to this rule is calling `meta_env()` on CGI and aCGI request objects. These are (essentially) equivalent to a call to [@http://tinyurl.com/3cqrd5 `::getenv()`] and will always work. However, exploit this 'feature' cautiously as it won't work with FastCGI or SCGI requests.
-]
-
-In all, there are twelve member functions of [classref cgi::basic_request `basic_request<>`] that provide access to the meta-variables associated to that request. Six of those return a `cgi::map` which you may use like a `std::map` to search through the complete list of variables.
-
-[table Meta-variable accessor functions
- [[Function signature] [Purpose]]
- [
- [`std::string meta_env(const std::string&)`]
- [Takes the name of the environment variable wanted and returns the value associated with it.]
- ]
- [
- [`std::string meta_get(const std::string&)`]
- [Takes the name of the __GET__ variable and returns the value associated with it (if any).]
- ]
- [
- [`std::string meta_post(const std::string&, bool greedy = true)`]
- [Takes the name of a __POST__ variable and returns the value associated with it (if any).
-
- If `greedy == true` - which it is by default - then more data is read from the request if required until all of the POST data has been read.]
- ]
- [
- [`std::string meta_form(const std::string&, bool greedy = true)`]
- [Takes the name of either a __GET__ or __POST__ variable and returns the value associated with it (if any). Note that this will only search the type referred to by the environment variable `"REQUEST_METHOD"`, so it is generally safe to use.
-
- If `greedy == true` - which it is by default - then more data is read from the request as required until all of the POST data has been read.]
- ]
- [
- [`std::string meta_cookie(const std::string& name)`]
- [Takes the name of the cookie variable and returns the value associated with it (if any).]
- ]
- [
- [`std::string meta_var(const std::string& name, bool greedy = true)`]
- [Takes the name of [*any] meta-variable and returns the value associated with it (if any).[footnote __xss_footnote__]
-
- If `greedy == true` - which it is by default - then more data is read from the request if required until either the requested variable is found or all of the POST data has been read, which ever comes first.]
- ]
-]
-
-[/ should this return a `std::pair<std::string, cgi::meta_type>` instead, where a `cgi::meta_type` is one of `get`, `post`, `env`, or `cookie`?]
-
-[endsect]
Added: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/scaling.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/scaling.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -0,0 +1,107 @@
+
+[section:scaling Turning a CGI program into a FastCGI daemon]
+
+So you want more flexibility and power than CGI can provide? This section shows you how to turn the CGI "Hello world" program into a FastCGI daemon that can handle more than one request at a time. We'll start off simple by handling one requests after another, before moving on to handling multiple requests simultaneously.
+
+[note
+ The examples in this section assume you have prepended:
+ ``
+ #include <boost/cgi/fcgi.hpp>
+ using namespace boost::fcgi;
+ ``
+]
+
+[section:sync_fcgi Synchronous FastCGI]
+
+``
+int main()
+{
+ try
+ {
+ service s;
+ acceptor a(s);
+
+ for(;;)
+ {
+ request req(s);
+ a.accept(req);
+
+ req.load();
+
+ response resp;
+
+ resp<< content_type("text/plain")
+ << "Hello, world.";
+
+ resp.send(req.client());
+ req.close(http::ok, 0);
+ }
+
+ return 0;
+
+ }catch(boost::system::system_error& err){
+ return 1;
+ }
+}
+``
+
+If should be reasonably obvious what's going on above. Let's go through the differences to the original CGI example.
+
+``
+acceptor a(s);
+``
+
+This is what you use to accept requests.
+
+``
+for(;;)
+{
+ // ...
+}
+``
+
+This is a simple example, so the program handles an arbitrary number of requests. You may choose to limit the number of requests you handle.
+
+``
+a.accept(req);
+
+req.load();
+``
+
+This accepts one request. An accepted request is in a protocol-dependent state and generally isn't very useful. You must either `load()` or `async_load()` the request to put in a useful state. The arguments to these functions determine what is parsed (**FIXME** these will have to be named, so you can do `req.load(parse_params|parse_post|parse_cookies|etc...)`).
+
+Beyond this the request is basically the same as a CGI request. As mentioned previously, you must explicitly close the request when you're finished with it:
+
+``
+req.close(http::ok);
+``
+
+More information on the available HTTP status codes can be found [link __http_status_codes__ here].
+
+One final thing to note is the type of error thrown by this library:
+
+``
+try {
+ // ...
+}catch(boost::system::system_error& err){
+ // err.message() <- string representing the error
+ // err.id() <- the error code (a number)
+ // if(err) {} <- only true when err represents an error
+}
+``
+
+[tip
+ There are non-`throw`ing alternatives to most of the `throw`ing functions in the library that take an additional `boost::cgi::error_code` argument. Due to the nature of FastCGI, exceptions may be undesireable - you won't usually want all the requests a process is handling to abort just because of a problem with one of them. In this case you can use the non-throwing versions of functions and gracefully close individual requests when something goes wrong.
+]
+
+The next example is very similar to the above but shows you how you might want to organise your program. As a demonstration it also uses the non-throwing alternatives to some functions.
+
+[endsect] [/ sync_fcgi]
+
+[section:async_fcgi Asynchronous FastCGI]
+
+[endsect] [/ async_fcgi]
+
+
+[endsect] [/ scaling]
+
Added: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/step_one.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/step_one.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -0,0 +1,79 @@
+
+[section "Hello, World."]
+
+Let's start at the beginning, with the eponymous "Hello world" example:
+
+``
+#include <boost/cgi.hpp>
+using namespace boost::cgi;
+
+int main()
+{
+ service s;
+ request req(s);
+ response resp;
+
+ resp<< content_type("text/plain")
+ << "Hello, world.";
+
+ resp.send(req.client());
+
+ return 0;
+}
+``
+
+That should be mostly self-explanatory, here is what is happening:
+
+``
+#include <boost/cgi.hpp>
+using namespace boost::cgi;
+``
+
+The boost/cgi.hpp header includes the headers for CGI, SCGI and FastCGI. If you only want the CGI stuff you can `#include <boost/cgi/cgi.hpp>`, or similarly for the other protocols (scgi.hpp or fcgi.hpp).
+
+``
+service s;
+request req(s);
+``
+
+The use of the `service` class here might seem cumbersome, but its value should become more apparent later on when we try and scale our program.
+
+[note
+ Still think it's ugly; I'm trying to think of the best way to remove the need for it without losing the protocol-independence of parts of the library.
+]
+
+``
+response resp;
+``
+
+You aren't required to use the `response` class with this library, but it's highly recommended. [-There is a rationale for the `response` class in the design notes] [/**FIXME**/]. A `response` is independent of protocol and any request you choose to use it with - that makes it easy to reuse.
+
+``
+resp<< content_type("text/plain")
+ << "Hello, world.";
+``
+
+You can stream data to a `response` just like you can with `std::cout`. In addition, you can stream things like `content_type("text/html")` and `cookie("whatever", "value")` (more on this later).
+
+`content_type` is one of the ['header factories] provided by the library. In other words it is a function which returns a `header` object, so instead of streaming `content_type("text/plain")` to a `response` you can stream `header("Content-type", "text/plain")`. Both are equivalent, but the former is cleaner and less error prone.
+
+The `response` class understands `header`s and keeps them separate from the rest of the response. This allows you to add headers at any point, so long as you haven't flushed/sent the response already. For instance, you could add a custom header "Running-time", stating the time it took to handle the request, just before you send the response.
+
+``
+resp.send(req.client());
+
+return 0;
+``
+
+As already mentioned, the `response` class buffers your data, so you must send it when it is ready. It is sent to the `client` associated with a request - ie. req.client() - but you don't need to know anything else about the Client concept for now. The library also provides a convenient macro to clean up the above:
+
+``
+return_(resp, req, 0); // 'returns 0' from main.
+``
+
+[tip
+ A CGI request is effectively closed when the application exits, but since FastCGI and SCGI can handle multiple requests per process you must explicitly close each one. The `return_()` macro does this properly.
+]
+
+[endsect] [/ hello_world]
+
Added: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/tutorial.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/tutorial.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -0,0 +1,31 @@
+
+[section Tutorial]
+
+[include step_one.qbk]
+
+[section:what_next The next step]
+
+Now we have a "Hello world" example compiling and working with our server we can choose to do two things:
+
+* Make a CGI program that handles user-supplied data to provide dynamic content, or
+
+* Turn the CGI "Hello world" into a FastCGI "Hello world", allowing better scalability.
+
+The first option is of course what CGI is all about: you take form data or a query string or a user's cookies and serve a custom response. The second option isn't mutually exclusive to the first, it is essentially an 'extra step' that you should be able to do at any point in the life-cycle of your application - although the sooner you do it the easier it might be!
+
+[important
+ Once you have set up an `fcgi::request`, you use it in almost exactly the same way as a `cgi::request`.
+]
+
+[link __branching__ branching?]
+
+[endsect] [/ what_next]
+
+[include scaling.qbk]
+
+[/include step_two.qbk]
+
+[/include step_three.qbk]
+
+[endsect] [/ tutorial]
+
Modified: sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/variables.qbk
==============================================================================
--- sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/variables.qbk (original)
+++ sandbox/SOC/2007/cgi/branches/acceptor_work/libs/cgi/doc/src/user_guide/tutorial/variables.qbk 2008-03-21 20:08:06 EDT (Fri, 21 Mar 2008)
@@ -19,51 +19,51 @@
[table Request variable accessor functions
[[Function signature] [Purpose]]
[
- [`cgi::map& env_()`]
+ [`cgi::map& env()`]
[Return a complete map of the meta-variables associated with the request.]
]
[
- [`std::string env_(const std::string&)`]
+ [`std::string env(const std::string&)`]
[Takes the name of the environment variable wanted and returns the value associated with it.]
]
[
- [`cgi::map& get_()`]
+ [`cgi::map& GET()`]
[Return a complete map of the GET variables associated with the request.]
]
[
- [`std::string get_(const std::string&)`]
+ [`std::string GET(const std::string&)`]
[Takes the name of the __GET__ variable and returns the value associated with it (if any).]
]
[
- [`cgi::map& post_()`]
+ [`cgi::map& POST()`]
[Return a complete map of the POST variables associated with the request.]
]
[
- [`std::string post_(const std::string&, bool greedy = true)`]
+ [`std::string POST(const std::string&, bool greedy = true)`]
[Takes the name of a __POST__ variable and returns the value associated with it (if any).
If `greedy == true` - which it is by default - then more data is read from the request if required until all of the POST data has been read.]
]
[
- [`cgi::map& form_()`]
+ [`cgi::map& form()`]
[Return a complete map of the from variables associated with the request. These will either be the GET or POST variables, depending on whether the `request_method()` is `"GET"` or `"POST"` respectively.]
]
[
- [`std::string form_(const std::string&, bool greedy = true)`]
+ [`std::string form(const std::string&, bool greedy = true)`]
[Takes the name of either a __GET__ or __POST__ variable and returns the value associated with it (if any). Note that this will only search the type referred to by the environment variable `"REQUEST_METHOD"`, so it is generally safe to use.
If `greedy == true` - which it is by default - then more data is read from the request as required until all of the POST data has been read.]
]
[
- [`cgi::map& cookie_()`]
+ [`cgi::map& cookie()`]
[Return a complete map of the cookie variables associated with a request.]
]
[
- [`std::string cookie_(const std::string& name)`]
+ [`std::string cookie(const std::string& name)`]
[Takes the name of the cookie variable and returns the value associated with it (if any).]
]
[
- [`std::string var_(const std::string& name, bool greedy = true)`]
+ [`std::string var(const std::string& name, bool greedy = true)`]
[Takes the name of [*any] meta-variable and returns the value associated with it (if any).[footnote __xss_footnote__]
If `greedy == true` - which it is by default - then more data is read from the request if required until either the requested variable is found or all of the POST data has been read, which ever comes first.]
@@ -77,7 +77,7 @@
// ...
cgi::request req;
- cgi::map& get_vars = req.get_();
+ cgi::map& get_vars = req.GET();
std::string user_id( get_vars["user_id"] );
if (!user_id.empty()) {
@@ -103,76 +103,76 @@
[table Standard CGI Meta-variables
[[Function signature] [Purpose]]
[
- [`std::string auth_type()`]
+ [`auth_type()`]
[If the server supports user authentication, and the script is protected, this is the protocol-specific authentication method used to validate the user.]
]
[
- [`std::string content_length()`]
+ [`content_length()`]
[The size of the message-body attached to the request.]
]
[
- [`std::string content_type()`]
+ [`content_type()`]
[The content type of data attached to the query, if any (ev. POST, PUT)]
]
[
- [`std::string gateway_interface()`]
+ [`gateway_interface()`]
[The revision of the CGI specification to which this server complies. Format: CGI/revision, eg. `"CGI/1.1"`]
]
[
- [`std::string path_info()`]
+ [`path_info()`]
[The extra path information, as given by the client. In other words, scripts can be accessed by their virtual pathname, followed by extra information at the end of this path. The extra information is sent as PATH_INFO.]
]
[
- [`std::string path_translated()`]
+ [`path_translated()`]
[The server provides a translated version of PATH_INFO, which takes the path and does any virtual-to-physical mapping to it.]
]
[
- [`std::string query_string()`]
+ [`query_string()`]
[The information following the '?' in the URL. This is where the GET data is extracted from. Format: `"name1=value1&name2=value2..."` Any reserved characters are URL-encoded.]
]
[
- [`std::string remote_addr()`]
+ [`remote_addr()`]
[The IP address of the remote host making the request. You should [*never] rely on the accuracy of this value, as it is easily forged.]
]
[
- [`std::string remote_host()`]
+ [`remote_host()`]
[The hostname making the request.]
]
[
- [`std::string remote_ident()`]
+ [`remote_ident()`]
[If the HTTP server supports [rfc 931] identification, then this variable will be set to the remote user name retrieved from the server. Usage of this variable should be limited to logging only.]
]
[
- [`std::string remote_user()`]
+ [`remote_user()`]
[If the server supports user authentication, and the script is protected, this is the username they have authenticated as.]
]
[
- [`std::string request_method()`]
+ [`request_method()`]
[The method with which the request was made. For HTTP, this is "GET", "HEAD", "POST", etc.]
]
[
- [`std::string script_name()`]
+ [`script_name()`]
[A virtual path to the script being executed, used for self-referencing URLs.]
]
[
- [`std::string server_name()`]
+ [`server_name()`]
[The server's hostname, DNS alias, or IP address as it would appear in self-referencing URLs.]
]
[
- [`std::string server_port()`]
+ [`server_port()`]
[The port number to which the request was sent.]
]
[
- [`std::string server_protocol()`]
+ [`server_protocol()`]
[The name and revision of the information protcol this request came in with. Format: protocol/revision.]
]
[
- [`std::string server_software()`]
+ [`server_software()`]
[The name and version of the information server software answering the request (and running the gateway). Format: name/version.]
]
]
-[/ should this return a `std::pair<std::string, cgi::meta_type>` instead, where a `cgi::meta_type` is one of `get`, `post`, `env`, or `cookie`?]
+[/ should this return a `std::pair<std::string, cgi::var_type>` instead, where a `cgi::var_type` is one of `get`, `post`, `env`, or `cookie`?]
[endsect]
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk