[master] 33135df Elaborate on the semantics of grace mode.

[Per Andreas Buer]

commit 33135dfd8237202d5c0d8c39e69d5c1c0c6a8192
Author: Per Buer <perbu at varnish-software.com>
Date:   Tue Mar 8 13:15:44 2011 +0100

    Elaborate on the semantics of grace mode.
    
    Also added Kristians workaround for dealing with errors

diff --git a/doc/sphinx/tutorial/handling_misbehaving_servers.rst b/doc/sphinx/tutorial/handling_misbehaving_servers.rst
index e0890de..cc8a636 100644
--- a/doc/sphinx/tutorial/handling_misbehaving_servers.rst
+++ b/doc/sphinx/tutorial/handling_misbehaving_servers.rst
@@ -13,13 +13,20 @@ Grace mode
 
 When several clients are requesting the same page Varnish will send
 one request to the backend and place the others on hold while fetching
-one copy from the back end. 
+one copy from the back end. In some products this is called request
+coalescing and Varnish does this automatically.
 
-If you are serving thousands of hits per second this queue can get
-huge. Nobody likes to wait so there is a possibility to serve stale
-content to waiting users. In order to do this we must instruct Varnish
-to keep the objects in cache beyond their TTL. So, to keep all objects
-for 30 minutes beyond their TTL use the following VCL:::
+If you are serving thousands of hits per second the queue of waiting
+requests can get huge. There are to potential problems - one is a
+thundering heard problem - suddenly releasing a thousand threads to
+serve content might send to load sky high. Secondly - nobody likes to
+wait. To deal with this Varnish can we can instruct Varnish to keep
+the objects in cache beyond their TTL and to serve the waiting
+requests somewhat stale content.
+
+So, in order to serve stale content we must first have some content to
+serve. So to make Varnish keep all objects for 30 minutes beyond their
+TTL use the following VCL:::
 
   sub vcl_fetch {
     set beresp.grace = 30m;
@@ -36,14 +43,19 @@ request. Lets us say that we accept serving 15s old object.::
 You might wonder why we should keep the objects in the cache for 30
 minutes if we are unable to serve them? Well, if you have enabled
 :ref:`tutorial-advanced_backend_servers-health` you can check if the
-backend is healthy and serve the content for as longer.::
+backend is sick and if it is we can serve the stale content for a bit
+longer.::
 
    if (! req.backend.healthy) {
       set req.grace = 5m;
    } else {
       set req.grace = 15s;
    }
-  
+
+So, to sum up, grace mode solves two problems:
+ * it serves stale content to avoid request pile-up.
+ * it serves stale content if the backend is not healthy.
+
 Saint mode
 ~~~~~~~~~~
 
@@ -70,6 +82,21 @@ Varnish will serve the content from its stale cache.
 
 This can really be a life saver.
 
+Known limitations on grace- and saint mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your request fails while it is being fetched you're thrown into
+vcl_error. vcl_error has access to a rather limited set of data so you
+can't enable saint mode or grace mode here. This will be addressed in a
+future release but a work-around is available.
+
+* Declare a backend that is always sick.
+* Set a magic marker in vcl_error
+* Restart the transaction
+* Note the magic marker in vcl_recv and set the backend to the one mentioned
+* Varnish will now serve stale data is any is available
+
+
 God mode
 ~~~~~~~~
 Not implemented yet. :-)