Subject: Incorrect description of xmax and xip in functions docs

From: Simon Riggs <[email-masked]>
Date: Fri, 05 Sep 2008 16:14:22 +0100

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.

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

---

From: Simon Riggs <[email-masked]>
Date: Fri, 05 Sep 2008 16:31:42 +0100

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

---

From: Bruce Momjian <[email-masked]>
Date: Sat, 6 Sep 2008 21:31:02 -0400 (EDT)

> or dead according to its commit status. The list does not include txids

Applied, and attached.

> 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  <[email-masked]>        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 &lt;= txid &lt; 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 &lt;= txid &lt;
!         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>

---

From: Simon Riggs <[email-masked]>
Date: Sun, 07 Sep 2008 12:14:23 +0100

> Applied, and attached.

Thanks.

> subtransaction xid is used, rather than adding documentation.

Or maybe check subtrans for it, as it really should be doing.

---

From: Bruce Momjian <[email-masked]>
Date: Sun, 7 Sep 2008 08:31:48 -0400 (EDT)

> Or maybe check subtrans for it, as it really should be doing.

Yea, that's what I meant.  You can't be sure everyone is going to read
the documentation but they are sure to see the function results or error
message.

---

From: Simon Riggs <[email-masked]>
Date: Mon, 08 Sep 2008 07:56:35 +0100

> the documentation but they are sure to see the function results or error

In fact, neither is possible. We cannot assume subtrans is available on
the system on which the check is made, neither can we identify which
xids are subtransactions and which are not.

The only way is to document it.

---

From: Bruce Momjian <[email-masked]>
Date: Wed, 7 Jan 2009 20:30:18 -0500 (EST)

> The only way is to document it.

Sorry, I am just getting back to this.  Why would we not know if
something is a subtransaction or if subtransactions are supported?  Are
you assuming txid_visible_in_snapshot() will be used on different
servers?  What are these txid_* functions for anyway?

---

From: Simon Riggs <[email-masked]>
Date: Thu, 08 Jan 2009 08:19:19 +0000

> servers?  What are these txid_* functions for anyway?

You can derive a snapshot and export it using txid_current_snapshot().
http://developer.postgresql.org/pgdocs/postgres/functions-info.html

You can then check whether an xid is in that snapshot by running
txid_visible_in_snapshot(). However, the check is done assuming that the
xid you are checking is a top-level xid and the answer you get is either
yes or no. 

There is no allowance made that the xid supplied as a parameter value
may have been a subtrans of one of the top-level xids listed. So the
answer *ought* to have been true, whereas the function will always
return false.

We cannot extend txid_visible_in_snapshot() to answer correctly because
that information is not held within the snapshot datatype, nor is it
held in regular snapshots currently. So the only way to handle this is
to document the limited scope of the answer this function provides.

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 8 Jan 2009 09:46:26 -0500 (EST)

> to document the limited scope of the answer this function provides.

Thank you for the clarification;  I know understand.  Patch attached and
applied.

  + 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.468
diff -c -c -r1.468 func.sgml
*** doc/src/sgml/func.sgml	8 Jan 2009 00:44:18 -0000	1.468
--- doc/src/sgml/func.sgml	8 Jan 2009 14:45:57 -0000
***************
*** 12473,12479 ****
        <row>
         <entry><literal><function>txid_visible_in_snapshot</function>(<parameter>bigint</parameter>, <parameter>txid_snapshot</parameter>)</literal></entry>
         <entry><type>boolean</type></entry>
!        <entry>is transaction ID visible in snapshot?</entry>
        </row>
       </tbody>
      </tgroup>
--- 12473,12479 ----
        <row>
         <entry><literal><function>txid_visible_in_snapshot</function>(<parameter>bigint</parameter>, <parameter>txid_snapshot</parameter>)</literal></entry>
         <entry><type>boolean</type></entry>
!        <entry>is transaction ID visible in snapshot? (do not use with subtransaction ids)</entry>
        </row>
       </tbody>
      </tgroup>