Subject: Re: Incorrect description of xmax and xip in functions docs
From: Simon Riggs <simon@2ndQuadrant.com>
To: pgsql-docs <pgsql-docs@postgresql.org>
In-Reply-To: <1220627662.4371.1203.camel@ebony.2ndQuadrant>
References: <1220627662.4371.1203.camel@ebony.2ndQuadrant>
Content-Type: text/plain
Date: Fri, 05 Sep 2008 16:31:42 +0100
Message-Id: <1220628702.4371.1214.camel@ebony.2ndQuadrant>
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit


On Fri, 2008-09-05 at 16:14 +0100, Simon Riggs wrote:
> http://developer.postgresql.org/pgdocs/postgres/functions-info.html
> 
> xip_list is described as
> 
> "Active txids at the time of the snapshot... "
> 
> 
> This is incorrect. The xip_list is the list of transactions that are in
> progress *and* less than xmax. There may be transactions in progress
> with an xid higher than xmax. This will happen frequently in fact. This
> is because xmax is defined as the highest/latest completed xid, not the
> highest running xid.
> 
> Note that there is no way to discover the list of running xids at the
> time of the snapshot, from the data we hold about snapshots. Nor can the
> snapshot data be used to monitor the number of transactions in progress.
> 
> Anyone disagree? If not, I'll patch.

My rewording would be:
"Active txids at the time of the snapshot. The list includes only those
active txids between xmin and xmax; there may be active txids higher
than xmax. A txid that is xmin <= txid < xmax and not in this list was
already completed at the time of the snapshot, and thus either visible
or dead according to its commit status. The list does not include txids
of subtransactions."

And for txid_visible_in_snapshot() comment added:
"Function should not be used with subtransaction xids. It is possible
that this function will return a true result for a subtransaction xid
that was actually still in progress at the time of the snapshot".

-- 
 Simon Riggs           www.2ndQuadrant.com
 PostgreSQL Training, Services and Support