Re: [RFC] extended txid docs - Mailing list pgsql-patches

Marko Kreen wrote:
> On 10/16/07, Chris Browne <cbbrowne@acm.org> wrote:
> > markokr@gmail.com ("Marko Kreen") writes:
> > > Even the realistic code may be too much for general docs,
> > > but considering this is not a functionality covered
> > > by general SQL textbooks, I think it is worth having.
> > >
> > > I also put rendered pages up here:
> > > http://skytools.projects.postgresql.org/txid/datatype-txid-snapshot.html
> >
> > >  http://skytools.projects.postgresql.org/txid/functions-txid.html
> >
> > I believe that those suggested texts describe what you intended, and
> > they should represent better English text for this.
>
> Thanks.  Here is a version with your changes applied, plus
> minor code cleanup and example output.
>
> I uploaded full docs to above urls, should be easier to browse.

I have applied part of your patch that documents the txid components in
the datatype section.  I didn't apply any of your example usage.  I just
added the mention that:

    The main use of these functions is to determine which transactions
    were committed between two snapshots.

If you want to put those examples on a web site or pgfoundry, we can
link to it from the documentation.

Applied patch attached.

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

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/datatype.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v
retrieving revision 1.211
diff -c -c -r1.211 datatype.sgml
*** doc/src/sgml/datatype.sgml    21 Oct 2007 20:04:37 -0000    1.211
--- doc/src/sgml/datatype.sgml    5 Nov 2007 14:35:49 -0000
***************
*** 3437,3442 ****
--- 3437,3513 ----

    </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 <= txid <
+         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>

Index: doc/src/sgml/func.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/func.sgml,v
retrieving revision 1.406
diff -c -c -r1.406 func.sgml
*** doc/src/sgml/func.sgml    30 Oct 2007 19:06:56 -0000    1.406
--- doc/src/sgml/func.sgml    5 Nov 2007 14:35:50 -0000
***************
*** 11490,11495 ****
--- 11490,11500 ----
      as well.
     </para>

+   </sect1>
+
+   <sect1 id="functions-txid">
+    <title>Transaction ID and Snapshot Functions</title>
+
     <indexterm>
      <primary>txid_current</primary>
     </indexterm>
***************
*** 11562,11581 ****
     </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.
     </para>
    </sect1>

!  <sect1 id="functions-admin">
!   <title>System Administration Functions</title>

!   <para>
!    <xref linkend="functions-admin-set-table"> shows the functions
!    available to query and alter run-time configuration parameters.
!   </para>

     <table id="functions-admin-set-table">
      <title>Configuration Settings Functions</title>
--- 11567,11589 ----
     </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 main use of these functions is to determine
!     which transactions were committed between two snapshots.
     </para>
+
    </sect1>

!   <sect1 id="functions-admin">
!    <title>System Administration Functions</title>

!    <para>
!     <xref linkend="functions-admin-set-table"> shows the functions
!     available to query and alter run-time configuration parameters.
!    </para>

     <table id="functions-admin-set-table">
      <title>Configuration Settings Functions</title>