commit_delay_doc.2013_01_28.patch

diff contrib/pg_test_fsync/pg_test_fsync.c
index ec4b90c..5ee0398
*** a/contrib/pg_test_fsync/pg_test_fsync.c
--- b/contrib/pg_test_fsync/pg_test_fsync.c
*************** do { \
*** 60,66 ****
  
  static const char *progname;
  
! static int	secs_per_test = 2;
  static int	needs_unlink = 0;
  static char full_buf[XLOG_SEG_SIZE],
  		   *buf,
--- 60,66 ----
  
  static const char *progname;
  
! static int	secs_per_test = 5;
  static int	needs_unlink = 0;
  static char full_buf[XLOG_SEG_SIZE],
  		   *buf,
diff doc/src/sgml/pgtestfsync.sgml
index 00ef209..ef4cd3d
*** a/doc/src/sgml/pgtestfsync.sgml
--- b/doc/src/sgml/pgtestfsync.sgml
***************
*** 72,79 ****
         <para>
          Specifies the number of seconds for each test.  The more time
          per test, the greater the test's accuracy, but the longer it takes
!         to run.  The default is 2 seconds, which allows the program to
!         complete in about 30 seconds.
         </para>
        </listitem>
       </varlistentry>
--- 72,79 ----
         <para>
          Specifies the number of seconds for each test.  The more time
          per test, the greater the test's accuracy, but the longer it takes
!         to run.  The default is 5 seconds, which allows the program to
!         complete in under 1 minute 30 seconds.
         </para>
        </listitem>
       </varlistentry>
diff doc/src/sgml/wal.sgml
index fc5c3b2..a3e5a4c
*** a/doc/src/sgml/wal.sgml
--- b/doc/src/sgml/wal.sgml
***************
*** 372,382 ****
     asynchronous commit, but it is actually a synchronous commit method
     (in fact, <varname>commit_delay</varname> is ignored during an
     asynchronous commit).  <varname>commit_delay</varname> causes a delay
!    just before a synchronous commit attempts to flush
!    <acronym>WAL</acronym> to disk, in the hope that a single flush
!    executed by one such transaction can also serve other transactions
!    committing at about the same time.  Setting <varname>commit_delay</varname>
!    can only help when there are many concurrently committing transactions.
    </para>
  
   </sect1>
--- 372,384 ----
     asynchronous commit, but it is actually a synchronous commit method
     (in fact, <varname>commit_delay</varname> is ignored during an
     asynchronous commit).  <varname>commit_delay</varname> causes a delay
!    just before a <acronym>WAL</acronym> flush to disk, in the hope
!    that a single flush executed by one such transaction can also serve
!    other transactions committing at about the same time.  The setting
!    can be thought of as a way of increasing the time window in which
!    other transactions can join a backlog about to participate in a
!    single flush, to amortize the cost of the flush among multiple
!    transactions.
    </para>
  
   </sect1>
***************
*** 550,570 ****
    </para>
  
    <para>
!    The <xref linkend="guc-commit-delay"> parameter defines for how many
!    microseconds the server process will sleep after writing a commit
!    record to the log with <function>LogInsert</function> but before
!    performing a <function>LogFlush</function>. This delay allows other
!    server processes to add their commit records to the log so as to have all
!    of them flushed with a single log sync. No sleep will occur if
!    <xref linkend="guc-fsync">
!    is not enabled, or if fewer than <xref linkend="guc-commit-siblings">
!    other sessions are currently in active transactions; this avoids
!    sleeping when it's unlikely that any other session will commit soon.
!    Note that on most platforms, the resolution of a sleep request is
!    ten milliseconds, so that any nonzero <varname>commit_delay</varname>
!    setting between 1 and 10000 microseconds would have the same effect.
!    Good values for these parameters are not yet clear; experimentation
!    is encouraged.
    </para>
  
    <para>
--- 552,618 ----
    </para>
  
    <para>
!    The <xref linkend="guc-commit-delay"> parameter defines for how
!    many microseconds the group commit leader server process will sleep
!    after acquiring a lock within <function>LogFlush</function>, as
!    group commit followers queue up behind the leader.  This delay
!    allows other server processes to join the backlog and add their
!    commit records to the log so as to have all of them flushed with a
!    single log sync. No sleep will occur if <xref linkend="guc-fsync">
!    is not enabled, or if fewer than
!    <xref linkend="guc-commit-siblings"> other sessions are currently
!    in active transactions; this avoids sleeping when it's unlikely
!    that any other session will commit soon.  Note that on some
!    platforms, the resolution of a sleep request is ten milliseconds,
!    so that any nonzero <varname>commit_delay</varname> setting between
!    1 and 10000 microseconds would have the same effect.  Note also
!    that on some platforms, sleep operations may take slightly longer
!    than requested by the implementation.
!   </para>
! 
!   <para>
!    Since the purpose of <varname>commit_delay</varname> is to allow
!    the cost of each flush operation to be more effectively amortized
!    across concurrently committing transactions (potentially at the
!    expense of transaction latency), it is necessary to quantify that
!    cost when altering the setting.  The higher that cost is, the more
!    effective <varname>commit_delay</varname> is expected to be in
!    increasing transaction throughput, up to a point.  The
!    <xref linkend="pgtestfsync"> module can be used to measure the
!    average time in microseconds that a single WAL flush operation
!    takes.  A value of half of the average time the module reports it
!    takes to flush after a single 8kB write operation is often the most
!    effective setting for <varname>commit_delay</varname>, particularly
!    for high latency rotating disks, and this should be used as a
!    starting point when optimizing for a particular workload.  The
!    benefit of tuning <varname>commit_delay</varname> can even be
!    pronounced on storage media with very fast sync times, such as
!    solid-state drives or RAID arrays with a battery-backed write
!    cache, but this should definitely be tested against a
!    representative workload.  Higher values of
!    <varname>commit_siblings</varname> should be used in such cases,
!    whereas smaller <varname>commit_siblings</varname> values are often
!    helpful on higher latency media.  Note that it is quite possible
!    that a setting of <varname>commit_delay</varname> that is too high
!    can increase transaction latency by so much that total transaction
!    throughput suffers.
!   </para>
! 
!   <para>
!    When <varname>commit_delay</varname> is set to zero (microseconds),
!    the default, the number of sessions that join this group commit
!    backlog is dictated entirely by the number of sessions that happen
!    to reach the stage where they need to flush, during the window in
!    which the previous, currently executing flush operation (if any)
!    takes to complete.  At higher client counts where the window is
!    naturally wider, a "gangway effect" tends to occur, and
!    <varname>commit_delay</varname> tends to help less.  Setting
!    <varname>commit_delay</varname> can only help when there are some
!    concurrently committing transactions, and throughput is limited to
!    some degree by commit rate, but with high rotational latency the
!    setting can be effective in increasing transaction throughput with
!    as few as two clients (that is, a single committing client with one
!    sibling transaction).
    </para>
  
    <para>