commit_delay_doc.2012_11_14.patch

diff doc/src/sgml/wal.sgml
index fc5c3b2..92619dd
*** a/doc/src/sgml/wal.sgml
--- b/doc/src/sgml/wal.sgml
***************
*** 375,382 ****
     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>
--- 375,397 ----
     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.  The setting can be thought of
!    as a way of increasing the time window in which other transactions
!    can join a backlog participating in a single flush, to amortize the
!    cost of the flush among multiple transactions.  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, which tends to only be effective at higher client counts
!    where the window is naturally wider.  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 in the event of a 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>
  
   </sect1>
***************
*** 560,570 ****
     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>
--- 575,607 ----
     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.
!   </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.  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>.  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.  However, higher
!    values of <varname>commit_siblings</varname> should be used is such
!    cases, whereas smaller <varname>commit_siblings</varname> values
!    can be 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>