first round of edits.

did a whole bunch, and added some content. didn't want to split it into 20
commits, sorry :(

README

@@ -31,7 +31,7 @@ DESCRIPTION
 Perlbal is a Perl-based reverse proxy load balancer and web server.
 
 It processes hundreds of millions of requests a day just for LiveJournal,
-Vox and TypePad and dozens of other high-traffic websites.
+TypePad and dozens of other high-traffic websites.
 
 Perlbal is a single-threaded event-based server supporting HTTP load
 balancing, web serving, and a mix of the two (see below).
@@ -96,8 +96,8 @@ Role: Reverse Proxy
           o Can actually give Perlbal a list of URLs to try. Perlbal will find
             one that's alive. Again, the end user sees no redirects happening
 
-          o Can also redirect to a file, which Perlbal will serve
-            non-blocking. See webserver mode above
+          o Can also redirect to a local file, which Perlbal will serve
+            non-blocking. See webserver mode below
 
     * Persistent client connections (configurable)
 

lib/Perlbal/FAQ.pod

@@ -50,7 +50,7 @@ Currently, Perlbal supports only one balancing method: C<random>.
 
     SET pool balance_method = 'random'
 
-With this mode, Perlbal selects one of the nodes within the pool randomly for each request received.
+With this mode, Perlbal selects one of the nodes within the pool randomly for each request received. It prefers reusing existing idle backend connections if backend_persist is enabled, which is faster than waiting for a new connection to open each time.
 
 
 =head2 Plugins

lib/Perlbal/Manual.pod

@@ -95,11 +95,6 @@ Brief description of existing roles.
 Setting up a Perlbal C<selector> service.
 
 
-=item L<Perlbal::Manual::ToDo>
-
-Perlbal's To-Do list.
-
-
 =item L<Perlbal::Manual::WebServer>
 
 Setting up a Perlbal C<web_server> service.

lib/Perlbal/Manual/Configuration.pod

@@ -78,6 +78,8 @@ Note that:
 
 ...unsets the nodefile, but does not remove current members.
 
+Also note: If you set a nodefile, then modify the pool via POOL ADD or POOL REMOVE, Perlbal will stop checking the nodefile for updates!
+
 Check F<conf/load-balancer.conf> and F<conf/nodelist.dat> for an example.
 
 

lib/Perlbal/Manual/Contributing.pod

@@ -17,7 +17,7 @@ This document aims at providing useful pointers for people wanting to contribute
 
 There's a description of Perlbal's internals in L<Perlbal::Manual::Internals>.
 
-There's a list of to-do items at L<Perlbal::Manual::ToDo>.
+There's a list of to-do items at http://code.google.com/p/perlbal/issues/list
 
 Also, join the mailing list at http://groups.google.com/group/perlbal.
 
@@ -52,7 +52,7 @@ Be sure to follow local style conventions.
 
     http://groups.google.com/group/perlbal
 
-=item Bug Tracker
+=item Bug Tracker and ToDo
 
     http://code.google.com/p/perlbal/issues/list
 
@@ -63,4 +63,3 @@ Be sure to follow local style conventions.
 
 L<Perlbal::Manual::Credits>,
 L<Perlbal::Manual::Internals>,
-L<Perlbal::Manual::ToDo>.

lib/Perlbal/Manual/Credits.pod

@@ -14,12 +14,11 @@ Lots of incredible people have contributed to make Perlbal the amazing tool that
 
 We are all very grateful for their help.
 
-Please let us know if you think someone is missing from this list.
+Please let us know if you think someone is missing from this list. The primary git repo may also be more up to date.
 
 
 =head2 CONTRIBUTORS
 
-Alan Kasindorf,
 Andreas J Koenig,
 Andrew McClain,
 Andy Armstrong,
@@ -31,6 +30,7 @@ Brad Fitzpatrick,
 Chuck Remes,
 Chris Hondl,
 Dan Conlon,
+dormando,
 Eamon Daly,
 Fred Moyer,
 Giao Phan,

lib/Perlbal/Manual/Debugging.pod

@@ -19,7 +19,7 @@ One of them is through a management console; the other is through debugging mess
 
 You'll need to set up a management service and use it to dump all the information you require.
 
-The comprehensive documentation on this process can be found at L<Perlbal::Manual::Management.
+The comprehensive documentation on this process can be found at L<Perlbal::Manual::Management>.
 
 
 =head2 Debugging messages

lib/Perlbal/Manual/Install.pod

@@ -19,6 +19,11 @@ How to install Perlbal.
 
     cpan> install Perlbal
 
+L<App::cpanminus> is also good at quickly installing Perlbal and all of its dependencies
+
+    $ cpanm Perlbal IO::AIO Perlbal::XS::HTTPHeaders
+
+... will give you an ideal Perlbal environment.
 
 =head2 Installing Perlbal (with a little more detail)
 
@@ -77,6 +82,16 @@ You can clone Perlbal's repository from github and install it by hand by followi
 
 =head2 Optional Dependencies and Asynchronous IO
 
+It is very highly recommended that L<Perlbal::XS::HTTPHeaders> is installed and enabled. If you have poor performance, the first thing to do is install L<Perlbal::XS::HTTPHeaders>.
+
+    $ perl -MCPAN -e shell
+
+    cpan> install Perlbal::XS::HTTPHeaders
+
+Enable it in your configuration:
+
+    XS enable headers
+
 Perlbal checks for L<IO::AIO> availability and uses it to perform asynchronous IO operations. If you're performing disk operations (e.g., using Perlbal as a web server), having L<IO::AIO> will improve your response times.
 
 The only thing required in order to benefit from this feature is to install L<IO::AIO>:

lib/Perlbal/Manual/Internals.pod

@@ -10,7 +10,7 @@ Perlbal 1.76.
 
 =head2 DESCRIPTION
 
-Perlbal listens for UDP broadcasts from the web nodes describing how many available children they have. This information is then used to pick an endpoint for a backend connection to be made to in order to handle a user's incoming request.
+Connections come in from wherever and get to the TCPListener. It uses Service objects to determine what kind of Client* to spawn. The Client classes then handle crafting the response for the user.
 
                             {{ INTERNET }}
                                   |
@@ -24,8 +24,9 @@ Perlbal listens for UDP broadcasts from the web nodes describing how many availa
                                                 v
                                           [BackendHTTP]
 
-So connections come in from wherever and get to the TCPListener. It uses Service objects to determine what kind of Client* to spawn. The Client classes then handle crafting the response for the user.
+Perlbal decides what backend to send a request to randomly (only presently supported method). If that service has idle backend connections available, configured by C<backend_persist> and C<connect_ahead>, it will reuse those connections and greatly reduce latency. See more detail in L<Perlbal::Manual::LoadBalancer>.
 
+Perlbal also specializes in "spoonfeeding" data to slow clients. This allows backends to continue serving requests while Perlbal transfers responses back as fast as the client can read.
 
 =head2 Classes
 

lib/Perlbal/Manual/LoadBalancer.pod

@@ -65,6 +65,28 @@ After that you define a service called C<service_mywebsite> with the role C<reve
 The last line is what allows you have several services configured in a file even if they are not currently active (a common scenario is to configure everything on the file and then enable/disable services on-the-fly as required; see L<Perlbal::Manual::Management> for more information on this process).
 
 
+=head3 The Load Balancing algorithm
+
+Perlbal uses a highly efficient load balancing algorithm. It is very effective for distributing dynamic web requests among potentially heterogeneous hardware.
+
+First, backend servers must have their MaxClients (for apache, or equivalent) setting tuned to a reasonable limit. If your hardware can run 20 requests in parallel before running out of CPU, set MaxClients to 20.
+
+Next, by default Perlbal will distribute requests randomly. Opening a new connection to any available backend, and issuing the request.
+
+The proper algorithm is able to be used if C<verify_backend>, C<backend_persist>, C<backend_persist_cache>, and C<connect_ahead> are enabled.
+
+    SET persist_backend       = on
+    SET verify_backend        = on
+    SET backend_persist_cache = 5
+    SET connect_ahead         = 2
+
+In this configuration, Perlbal will only route client requests to backends that it knows are real processes, instead of the OS listen queue. It will attempt to reuse pre-verified backends, and will attempt to create slightly more idle connections than it needs in preparation of future requests.
+
+When you put all this together, it becomes less likely that a client will wait for Perlbal to find an available backend. By setting your MaxClients properly, backends are able to serve traffic without getting overwhelmed. If no backends are available, Perlbal will queue them internally, rather than overload backends.
+
+You would want to disable C<verify_backend> if you are balancing across image servers, or other extremely lightweight requests.
+
+
 =head2 SEE ALSO
 
 L<Perlbal::Manual::Configuration>,

lib/Perlbal/Manual/Management.pod

@@ -200,6 +200,8 @@ Unsetting the file to autoload nodes from (note that this does not remove curren
 
 C<undef>, C<null>, "" and '' are interpreted just like C<none>.
 
+Note that manually modifying the pool (via POOL ADD or POOL REMOVE) will disable the periodic checking of the nodefile.
+
 Setting the load balancing method:
 
     SET pool balance_method = 'random'

lib/Perlbal/Manual/Plugins.pod

@@ -62,6 +62,7 @@ A Perlbal plugin consists in a package under the C<Perlbal::Plugin> namespace th
 
 These steps and functions (plus some helper functions you can define or use) are described below.
 
+PLEASE KEEP IN MIND: Perlbal is a single-process, asynchronous web server. You must not do things in plugins which will cause it to block, or no other requests can be served at the same time.
 
 =head3 Creating a package
 
@@ -238,7 +239,7 @@ C<check_type> can also contain a code reference that will be used to validate th
         ...
     },
 
-This code reference should return a true of false value. If returning false, the contents of C<$emesg> (which is passed as a reference to the function) will be used as the error message.
+This code reference should return a true or false value. If returning false, the contents of C<$emesg> (which is passed as a reference to the function) will be used as the error message.
 
 Here's a better explanation of the acceptable values for C<check_type>:
 

lib/Perlbal/Manual/ReverseProxy.pod

@@ -65,7 +65,7 @@ Default is 100k.
 
 =item B<buffer_size> = size
 
-How much ahead of a client we'll get while copying from a backend to a client. If a client gets behind this much, we stop reading from the backend for a bit.
+How much ahead of a client we'll get while copying from a backend to a client. If a client gets behind this much, we stop reading from the backend for a bit. Once all remaining data fits in the buffer, the backend is released and may be reused.
 
 Default is 256k.
 
@@ -170,7 +170,7 @@ See L<Perlbal::Manual::HighPriority> for more information.
 
 =item B<idle_timeout> = int
 
-Timeout in seconds for idle connections to the end user.
+Timeout in seconds for idle connections to the end user. It's also the limit for how long a backend may take to respond or transfer data.
 
 Default is 30.
 
@@ -330,7 +330,7 @@ Let's assume, for simplification purposes, that your service only has one server
 
 =item * Perlbal starts
 
-1 connection is opened (because of C<connect_ahead>'s value).
+No connections open until the very first request comes in (this may change in the future).
 
 =item * one requests arrives