Document txid functions.

Marko Kreen

doc/src/sgml/datatype.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.212 2007/11/05 12:02:20 darcy Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.213 2007/11/05 14:51:08 momjian Exp $ -->
 
  <chapter id="datatype">
   <title id="datatype-title">Data Types</title>
@@ -3437,6 +3437,77 @@ SELECT to_tsquery('Fat:ab & Cats');
 
   </sect1>
 
+  <sect1 id="datatype-txid-snapshot">
+   <title>Transaction Snapshot Type</title>
+
+   <indexterm zone="datatype-txid-snapshot">
+    <primary>txid_snapshot</primary>
+   </indexterm>
+
+   <para>
+    The data type <type>txid_snapshot</type> stores info about transaction ID
+    visibility at a particular moment in time. The components are
+    described in <xref linkend="datatype-txid-snapshot-parts">.
+   </para>
+
+   <table id="datatype-txid-snapshot-parts">
+    <title>Snapshot components</title>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>Name</entry>
+       <entry>Query Function</entry>
+       <entry>Description</entry>
+      </row>
+     </thead>
+
+     <tbody>
+
+      <row>
+       <entry><type>xmin</type></entry>
+       <entry>txid_snapshot_xmin()</entry>
+       <entry>
+         Earliest transaction ID that is still active.  All earlier
+         transactions will either be committed and visible, or rolled
+         back and dead.
+       </entry>
+      </row>
+
+      <row>
+       <entry><type>xmax</type></entry>
+       <entry>txid_snapshot_xmax()</entry>
+       <entry>
+        Next unassigned txid.  All txids later than this one are
+        unassigned, and thus invisible.
+       </entry>
+      </row>
+
+      <row>
+       <entry><type>xip_list</type></entry>
+       <entry>txid_snapshot_xip()</entry>
+       <entry>
+        Active txids at the time of snapshot.  All of them are between
+        xmin and xmax.  A txid that is <literal>xmin &lt;= txid &lt;
+        xmax</literal> and not in this list is visible.
+       </entry>
+      </row>
+
+     </tbody>
+    </tgroup>
+   </table>
+
+   <para>
+    Snapshot's textual representation is <literal>[xmin]:[xmax]:[xip_list]</literal>
+    for example <literal>10:20:10,14,15</literal> means
+    <literal>xmin=10 xmax=20 xip_list=10,14,15</literal>.
+   </para>
+
+   <para>
+    Functions for getting and querying transaction ids and snapshots are
+    described in <xref linkend="functions-txid">.
+   </para>
+  </sect1>
+
   <sect1 id="datatype-uuid">
    <title><acronym>UUID</acronym> Type</title>
 

doc/src/sgml/func.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.406 2007/10/30 19:06:56 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.407 2007/11/05 14:51:08 momjian Exp $ -->
 
  <chapter id="functions">
   <title>Functions and Operators</title>
@@ -11490,6 +11490,11 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
     as well.
    </para>
 
+  </sect1>
+
+  <sect1 id="functions-txid">
+   <title>Transaction ID and Snapshot Functions</title>
+
    <indexterm>
     <primary>txid_current</primary>
    </indexterm>
@@ -11562,11 +11567,14 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
    </table>
 
    <para>
-    The internal transaction ID type (<type>xid</>) is 32 bits wide and so
-    it wraps around every 4 billion transactions.  However, these functions
-    export a 64-bit format that is extended with an <quote>epoch</> counter
-    so that it will not wrap around for the life of an installation.
+    The internal transaction ID type (<type>xid</>) is 32 bits wide and
+    so it wraps around every 4 billion transactions.  However, these
+    functions export a 64-bit format that is extended with an
+    <quote>epoch</> counter so that it will not wrap around for the life
+    of an installation.  The main use of these functions is to determine
+    which transactions were committed between two snapshots.
    </para>
+
   </sect1>
 
   <sect1 id="functions-admin">