From e7f409756dac9fedc12d5aece0f8df5efb8d9e01 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 17 Feb 2014 12:20:57 -0500
Subject: [PATCH] Improve documentation about multixact IDs.

Per gripe from Josh Berkus.
---
 doc/src/sgml/maintenance.sgml | 21 ++++++++++++---------
 doc/src/sgml/release-9.3.sgml |  8 +++++---
 2 files changed, 17 insertions(+), 12 deletions(-)

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 8ff309b78f..d3fcb82ef7 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -616,13 +616,16 @@ HINT:  Stop the postmaster and vacuum that database in single-user mode.
     </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>
@@ -634,8 +637,8 @@ HINT:  Stop the postmaster and vacuum that database in single-user mode.
      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>
-- 
2.40.0