Significant improvements to the documentation for the new cost-based

vacuum delay feature, including updating the docs for Tom's recent
improvements. There is still more work to be done here: for example,
adding some more information on the practical use of cost-based
vacuum delay to the "maintenance" section would probably be a good
idea.

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 93b5687373f7d2065edf88d493c599d87e396f1f..1f2e547f860c6b62a00dcbe89e52e3002124cf16 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 
 
 
@@ -992,83 +992,107 @@ SET ENABLE_SEQSCAN TO OFF;
     
 
     
-     Cost<span class="marked"> </span>Based Vacuum Delay
+     Cost<span class="marked">-</span>Based Vacuum Delay
 
-     
-     
-      vacuum_cost_page_hit (integer)
-      
-       
-       During a default VACUUM (not
-       FULL) the system maintains and internal counter
-       accumulating the cost of various operations performed. When the
-       accumulated cost reaches a limit, the backend performing the
-       VACUUM will sleep for a while, reset the
-       accumulator and continue. The intention is to lower the IO impact
-       of VACUUM.
-      
+     
+      During the execution of VACUUM,
+      VACUUM FULL and ANALYZE,
+      the system mantains an internal counter that keeps track of the
+      cost of the various I/O operations that are performed. When the
+      accumulated cost reaches a limit
+      (specified by vacuum_cost_limit), the backend performing
+      the operation will sleep for a while (specified by
+      vacuum_cost_naptime). Then it will reset the
+      counter and continue execution.
+     
 
-      
-       The variable vacuum_cost_page_hit is the cost
-       for vacuuming a buffer found inside the shared buffer cache. 
-       It represents the cost to lock the buffer pool, lookup the 
-       shared hash table and to actually scan the block content.
-       
-      
-     
+     
+      The intent of this feature is to allow administrators the reduce
+      the I/O impact of these commands on concurrent database
+      activity. There are some situations in which it is not very
+      important that maintainence commands like
+      VACUUM and ANALYZE finish
+      quickly; however, it is usually very important these these
+      commands do not significantly interfere with the ability of the
+      system to perform other database operations. Cost-based vacuum
+      delay provides a way for administrators to achieve this.
+     
 
-     
-      vacuum_cost_page_miss (integer)
-      
-       
-       The cost for vacuuming a buffer that has to be read from disk.
-       This represents the effort to lock the buffer pool, lookup the
-       cache directory, reading the block from disk and scanning the
-       content.
-       
-      
-     
+     
+      This feature is disabled by default. To enable it, set the
+      vacuum_cost_naptime variable to a reasonable
+      value.
+     
 
-     
-      vacuum_cost_page_dirty (integer)
-      
-       
-       This extra cost is added when vacuum modifies a block that was
-       clean before. It represents the extra IO required to flush the
-       dirty block out to disk again.
-       
-      
-     
+     
+      
+       vacuum_cost_page_hit (integer)
+       
+        
+         The cost for vacuuming a buffer found in the shared buffer
+         cache. It represents the cost to lock the buffer pool, lookup
+         the shared hash table and scan the content of the page. The
+         default value is 1.
+        
+       
+      
 
-     
-      vacuum_cost_limit (integer)
-      
-       
-       This is the cost limit that must be reached or exceeded before
-       the VACUUM will nap.
-       
-      
-     
+      
+       vacuum_cost_page_miss (integer)
+       
+        
+         The cost for vacuuming a buffer that has to be read from
+         disk.  This represents the effort to lock the buffer pool,
+         lookup the shared hash table, read the desired block in from
+         the disk and scan its content. The default value is 10.
+        
+       
+      
 
-     
-      vacuum_cost_naptime (integer)
-      
-       
-       The time im milliseconds the VACUUM will
-       nap when the cost limit has been reached or exceeded.
-       There are certain bulk operations that hold critical
-       locks and should therefore perform
-       as quickly as possible. Because of that it is possible that the
-       cost actually accumulates far higher than this limit. To compensate
-       for this, the final naptime is calculated as
-       vacuum_cost_naptime * 
-       accumulated_balance /
-       vacuum_cost_limit with a maximum of
-       vacuum_cost_naptime * 4.
-       
-      
-     
+      
+       vacuum_cost_page_dirty (integer)
+       
+        
+         The extra cost added when vacuum modifies a block that was
+         previously clean. It represents the extra I/O required to
+         flush the dirty block out to disk again. The default value is
+         20.
+        
+       
+      
+
+      
+       vacuum_cost_limit (integer)
+       
+        
+         The accumulated cost that will cause the backend to briefly
+         nap. The default value is 200.
+        
+       
+      
 
+      
+       vacuum_cost_naptime (integer)
+       
+        
+         The length of time in milliseconds that a backend will nap
+         when the cost limit has been exceeded. There are certain bulk
+         operations that hold critical locks and should therefore
+         complete as quickly as possible. Because of that it is
+         possible that the cost actually accumulates far higher than
+         this limit. To compensate for this, the final naptime is
+         calculated as vacuum_cost_naptime *
+         accumulated_balance /
+         vacuum_cost_limit with a maximum of
+         vacuum_cost_naptime * 4.
+        
+
+        
+         The default value is 0, which disables the cost-based vacuum
+         delay feature.
+        
+       
+