Manual Entries of commit_delay and commit_siblings are not complete.

Hi, pgsql-docs,

I was confused by the system behavior of PG's write ahead log, specifically
the relation between commit_delay, commit_siblings, and fsync.

Basically according to the manual (
http://www.postgresql.org/docs/9.1/static/runtime-config-wal.html), I know:

"commit_delay" specifies the delay before a transaction attempts to flush
the WAL buffer out to disk.
"commit_siblings" specifies minimum number of concurrent open transactions
to require before performing the commit_delay delay.

However, after looking at the code, I figured out these configuration
parameters are also controlled by fsync.

The only usage of the two parameter I can find is:

/* src/backend/access/transam/xact.c */

static TransactionId
RecordTransactionCommit(void)
...
if (CommitDelay > 0 &&
enableFsync &&
MinimumActiveBackends(CommitSiblings))
pg_usleep(CommitDelay);

...
}

where, CommitDelay stores the parameter of "commit_delay", CommitSiblings
stores the parameter of "commit_siblings", and enableFsync stores the
parameter of "fsync".

It seems the two parameters (commit_delay and commit_siblings) only have
effect when fsync is set to be *on*.

But, unfortunately, such behavior is not covered in the manual. The mistake
I made is only set the two values but disabling fsync so the expected PG
does not behave as I expected. I think it's definitely helpful to specify
the relations between these configuration parameters either in the manual,
or in the source code by giving warnings logs.

Thanks a lot!
Tianyin

On Tue, Oct 2, 2012 at 05:36:28PM -0700, Tianyin Xu wrote:

Hi, pgsql-docs,

I was confused by the system behavior of PG's write ahead log, specifically the
relation between commit_delay, commit_siblings, and fsync.

Basically according to the manual (http://www.postgresql.org/docs/9.1/static/
runtime-config-wal.html), I know:

"commit_delay" specifies the delay before a transaction attempts to flush the
WAL buffer out to disk.
"commit_siblings" specifies minimum number of concurrent open transactions to
require before performing the commit_delay delay.

However, after looking at the code, I figured out these configuration
parameters are also controlled by fsync.

The only usage of the two parameter I can find is:

/* src/backend/access/transam/xact.c */

static TransactionId
RecordTransactionCommit(void)
...
if (CommitDelay > 0 &&
enableFsync &&
MinimumActiveBackends(CommitSiblings))
pg_usleep(CommitDelay);

...
}

where, CommitDelay stores the parameter of "commit_delay", CommitSiblings
stores the parameter of "commit_siblings", and enableFsync stores the parameter
of "fsync".

It seems the two parameters (commit_delay and commit_siblings) only have effect
when fsync is set to be *on*.

But, unfortunately, such behavior is not covered in the manual. The mistake I
made is only set the two values but disabling fsync so the expected PG does not
behave as I expected. I think it's definitely helpful to specify the relations
between these configuration parameters either in the manual, or in the source
code by giving warnings logs.

Docs updated for PG 9.3 with the attached patch.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +