From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 17 Feb 2014 17:21:01 +0000 (-0500)
Subject: Improve documentation about multixact IDs.
X-Git-Tag: REL9_3_3~2
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=81f4c2867f37f1a2a1c5a4ce337d4f5cd3013bc1;p=postgresql

Improve documentation about multixact IDs.

Per gripe from Josh Berkus.
---

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 291f48a472..f57c281815 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -618,13 +618,16 @@ HINT:  Stop the postmaster and use a standalone backend to VACUUM in "mydb".
     </indexterm>
 
     <para>
-     <firstterm>Multixacts</> are used to implement row locking by
-     multiple transactions: since there is limited space in the tuple
-     header to store lock information, that information is stored as a
-     multixact separately in the <filename>pg_multixact</> subdirectory,
-     and only its ID is in the <structfield>xmax</> field
-     in the tuple header.
-     Similar to transaction IDs, multixact IDs are implemented as a
+     <firstterm>Multixact IDs</> are used to support row locking by
+     multiple transactions.  Since there is only limited space in a tuple
+     header to store lock information, that information is encoded as
+     a <quote>multiple transaction ID</>, or multixact ID for short,
+     whenever there is more than one transaction concurrently locking a
+     row.  Information about which transaction IDs are included in any
+     particular multixact ID is stored separately in
+     the <filename>pg_multixact</> subdirectory, and only the multixact ID
+     appears in the <structfield>xmax</> field in the tuple header.
+     Like transaction IDs, multixact IDs are implemented as a
      32-bit counter and corresponding storage, all of which requires
      careful aging management, storage cleanup, and wraparound handling.
     </para>
@@ -636,8 +639,8 @@ HINT:  Stop the postmaster and use a standalone backend to VACUUM in "mydb".
      is replaced by a different value, which can be the zero value, a single
      transaction ID, or a newer multixact ID.  For each table,
      <structname>pg_class</>.<structfield>relminmxid</> stores the oldest
-     possible value still stored in any tuple of that table.  Every time this
-     value is older than
+     possible multixact ID still appearing in any tuple of that table.
+     If this value is older than
      <xref linkend="guc-vacuum-multixact-freeze-table-age">, a whole-table
      scan is forced.  Whole-table <command>VACUUM</> scans, regardless of
      what causes them, enable advancing the value for that table.
diff --git a/doc/src/sgml/release-9.3.sgml b/doc/src/sgml/release-9.3.sgml
index acc0b9d202..11e429bb65 100644
--- a/doc/src/sgml/release-9.3.sgml
+++ b/doc/src/sgml/release-9.3.sgml
@@ -64,9 +64,11 @@ Branch: REL9_3_STABLE [8e9a16ab8] 2013-12-16 11:29:51 -0300
      </para>
 
      <para>
-      The method for tuple freezing was unable to handle some cases
-      involving freezing of <quote>multixact</> IDs, with the practical
-      effect that shared row-level locks might be forgotten once old enough.
+      The logic for tuple freezing was unable to handle some cases involving
+      freezing of
+      <link linkend="vacuum-for-multixact-wraparound"><firstterm>multixact</>
+      IDs</link>, with the practical effect that shared row-level locks
+      might be forgotten once old enough.
      </para>
 
      <para>