Fix some misstatements in WAL parameter discussion.

diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index 45c41ea0b54f2d5ed790e95f9b041fab7be99796..7f603221accee480bbf03989caadc875688bdb93 100644 (file)
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/wal.sgml,v 1.20 2002/09/06 20:26:00 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/wal.sgml,v 1.21 2002/11/02 22:23:01 tgl Exp $ -->
 
 <chapter id="wal">
  <title>Write-Ahead Logging (<acronym>WAL</acronym>)</title>
@@ -222,33 +222,6 @@
    configuration parameters.
   </para>
 
-  <para>
-   There are two commonly used <acronym>WAL</acronym> functions:
-   <function>LogInsert</function> and <function>LogFlush</function>.
-   <function>LogInsert</function> is used to place a new record into
-   the <acronym>WAL</acronym> buffers in shared memory. If there is no
-   space for the new record, <function>LogInsert</function> will have
-   to write (move to kernel cache) a few filled <acronym>WAL</acronym>
-   buffers. This is undesirable because <function>LogInsert</function>
-   is used on every database low level modification (for example,
-   tuple insertion) at a time when an exclusive lock is held on
-   affected data pages, so the operation needs to be as fast as
-   possible.  What is worse, writing <acronym>WAL</acronym> buffers may
-   also force the creation of a new log segment, which takes even more
-   time. Normally, <acronym>WAL</acronym> buffers should be written
-   and flushed by a <function>LogFlush</function> request, which is
-   made, for the most part, at transaction commit time to ensure that
-   transaction records are flushed to permanent storage. On systems
-   with high log output, <function>LogFlush</function> requests may
-   not occur often enough to prevent <acronym>WAL</acronym> buffers
-   being written by <function>LogInsert</function>. On such systems
-   one should increase the number of <acronym>WAL</acronym> buffers by
-   modifying the <filename>postgresql.conf</filename> <varname>
-   WAL_BUFFERS</varname> parameter. The default number of <acronym>
-   WAL</acronym> buffers is 8.  Increasing this value will 
-   correspondingly increase shared memory usage.
-  </para>
-
   <para>
    <firstterm>Checkpoints</firstterm> are points in the sequence of
    transactions at which it is guaranteed that the data files have
@@ -265,19 +238,6 @@
    or removed.)
   </para>
 
-  <para>
-   The checkpoint maker is also able to create a few log segments for
-   future use, so as to avoid the need for
-   <function>LogInsert</function> or <function>LogFlush</function> to
-   spend time in creating them.  (If that happens, the entire database
-   system will be delayed by the creation operation, so it's better if
-   the files can be created in the checkpoint maker, which is not on
-   anyone's critical path.)
-   By default a new 16MB segment file is created only if more than 75% of
-   the current segment has been used.  This is inadequate if the system
-   generates more than 4MB of log output between checkpoints.
-  </para>
-
   <para>
    The postmaster spawns a special backend process every so often
    to create the next checkpoint.  A checkpoint is created every
@@ -303,16 +263,43 @@
 
   <para>
    There will be at least one 16MB segment file, and will normally 
-   not be more than <varname>CHECKPOINT_SEGMENTS</varname>
+   not be more than 2 * <varname>CHECKPOINT_SEGMENTS</varname>
    + 1 files.  You can use this to estimate space requirements for 
    WAL.  Ordinarily, when old log segment files are no longer needed, 
    they are recycled (renamed to become the next sequential future 
    segments). If, due to a short-term peak of log output rate, there 
-   are more than <varname>CHECKPOINT_SEGMENTS</varname> + 1 segment files, 
+   are more than 2 * <varname>CHECKPOINT_SEGMENTS</varname> + 1 segment files, 
    the unneeded segment files will be deleted instead of recycled until the
    system gets back under this limit.
   </para>
 
+  <para>
+   There are two commonly used <acronym>WAL</acronym> functions:
+   <function>LogInsert</function> and <function>LogFlush</function>.
+   <function>LogInsert</function> is used to place a new record into
+   the <acronym>WAL</acronym> buffers in shared memory. If there is no
+   space for the new record, <function>LogInsert</function> will have
+   to write (move to kernel cache) a few filled <acronym>WAL</acronym>
+   buffers. This is undesirable because <function>LogInsert</function>
+   is used on every database low level modification (for example,
+   tuple insertion) at a time when an exclusive lock is held on
+   affected data pages, so the operation needs to be as fast as
+   possible.  What is worse, writing <acronym>WAL</acronym> buffers may
+   also force the creation of a new log segment, which takes even more
+   time. Normally, <acronym>WAL</acronym> buffers should be written
+   and flushed by a <function>LogFlush</function> request, which is
+   made, for the most part, at transaction commit time to ensure that
+   transaction records are flushed to permanent storage. On systems
+   with high log output, <function>LogFlush</function> requests may
+   not occur often enough to prevent <acronym>WAL</acronym> buffers
+   being written by <function>LogInsert</function>. On such systems
+   one should increase the number of <acronym>WAL</acronym> buffers by
+   modifying the <filename>postgresql.conf</filename> <varname>
+   WAL_BUFFERS</varname> parameter. The default number of <acronym>
+   WAL</acronym> buffers is 8.  Increasing this value will 
+   correspondingly increase shared memory usage.
+  </para>
+
   <para>
    The <varname>COMMIT_DELAY</varname> parameter defines for how many
    microseconds the backend will sleep after writing a commit