Re: Incorrect description of xmax and xip in functions docs - Mailing list pgsql-docs

Simon Riggs wrote:
>
> 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."

Applied, and attached.

> 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".

I think the cleaner solution is to throw an appropriate error if a
subtransaction xid is used, rather than adding documentation.

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

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/func.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/func.sgml,v
retrieving revision 1.444
diff -c -c -r1.444 func.sgml
*** doc/src/sgml/func.sgml    6 Sep 2008 00:01:21 -0000    1.444
--- doc/src/sgml/func.sgml    7 Sep 2008 01:27:44 -0000
***************
*** 12006,12016 ****
        <row>
         <entry><type>xip_list</type></entry>
         <entry>
!         Active txids at the time of the snapshot.  All of them are between
!         <literal>xmin</> and <literal>xmax</>.  A txid that is
!         <literal>xmin <= txid < xmax</literal> 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.
         </entry>
        </row>

--- 12006,12019 ----
        <row>
         <entry><type>xip_list</type></entry>
         <entry>
!         Active txids at the time of the snapshot.  The list
!         includes only those active txids between <literal>xmin</>
!         and <literal>xmax</>; there might be active txids higher
!         than xmax.  A txid that is <literal>xmin <= txid <
!         xmax</literal> 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.
         </entry>
        </row>