Fix and improve SnapshotType comments.

The comment for SNAPSHOT_SELF was unfortunately explaining
SNAPSHOT_DIRTY, as reported by Sergei. Also expand a few comments, and
include a few more comments from heapam_visibility.c, so they're in an
AM independent place.

Reported-By: Sergei Kornilov
Author: Andres Freund
Discussion: https://postgr.es/m/9152241558192351@sas1-d856b3d759c7.qloud-c.yandex.net

diff --git a/src/include/utils/snapshot.h b/src/include/utils/snapshot.h
index 7bf7cad5727423f4edcd4b7e77fb4709dbff5385..9f92ce011db959cf4c73f3adc94160b9dc33a635 100644 (file)
--- a/src/include/utils/snapshot.h
+++ b/src/include/utils/snapshot.h
@@ -50,13 +50,15 @@ typedef enum SnapshotType
    SNAPSHOT_MVCC = 0,
 
    /*-------------------------------------------------------------------------
-    * A tuple is visible iff the tuple is valid including effects of open
-    * transactions.
+    * A tuple is visible iff the tuple is valid "for itself".
     *
     * Here, we consider the effects of:
-    * - all committed and in-progress transactions (as of the current instant)
+    * - all committed transactions (as of the current instant)
     * - previous commands of this transaction
     * - changes made by the current command
+    *
+    * Does _not_ include:
+    * - in-progress transactions (as of the current instant)
     * -------------------------------------------------------------------------
     */
    SNAPSHOT_SELF,
@@ -79,6 +81,22 @@ typedef enum SnapshotType
     * - all committed and in-progress transactions (as of the current instant)
     * - previous commands of this transaction
     * - changes made by the current command
+    *
+    * This is essentially like SNAPSHOT_SELF as far as effects of the current
+    * transaction and committed/aborted xacts are concerned.  However, it
+    * also includes the effects of other xacts still in progress.
+    *
+    * A special hack is that when a snapshot of this type is used to
+    * determine tuple visibility, the passed-in snapshot struct is used as an
+    * output argument to return the xids of concurrent xacts that affected
+    * the tuple.  snapshot->xmin is set to the tuple's xmin if that is
+    * another transaction that's still in progress; or to
+    * InvalidTransactionId if the tuple's xmin is committed good, committed
+    * dead, or my own xact.  Similarly for snapshot->xmax and the tuple's
+    * xmax.  If the tuple was inserted speculatively, meaning that the
+    * inserter might still back down on the insertion without aborting the
+    * whole transaction, the associated token is also returned in
+    * snapshot->speculativeToken.  See also InitDirtySnapshot().
     * -------------------------------------------------------------------------
     */
    SNAPSHOT_DIRTY,
@@ -92,9 +110,10 @@ typedef enum SnapshotType
 
    /*
     * A tuple is visible iff the tuple might be visible to some transaction;
-    * false if it's surely dead to everyone, ie, vacuumable.
+    * false if it's surely dead to everyone, i.e., vacuumable.
     *
-    * Snapshot.xmin must have been set up with the xmin horizon to use.
+    * For visibility checks snapshot->min must have been set up with the xmin
+    * horizon to use.
     */
    SNAPSHOT_NON_VACUUMABLE
 } SnapshotType;