Document age(xid) and mxid_age(xid).

These functions have been around for some time, but commits
48b5aa3143 and 15afb7d61c were only back-patched to v16.  Let's
back-patch them to all supported versions now.

Reported-by: David Rowley <dgrowleyml@gmail.com> (commit 48b5aa3143)
Author: Bruce Momjian <bruce@momjian.us> (commit 48b5aa3143)
Co-authored-by: Bertrand Drouvot <bertranddrouvot.pg@gmail.com> (commit 15afb7d61c)
Reviewed-by: Michael Paquier <michael@paquier.xyz> (commit 15afb7d61c)
Reviewed-by: Robert Haas <robertmhaas@gmail.com>
Reviewed-by: Álvaro Herrera <alvherre@kurilemu.de>
Discussion: https://postgr.es/m/aGMCxHxLfeMdQk8m%40nathan
Backpatch-through: 13-15

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 0bb80d784da69bed5e3658d4590aeb578e8dcf74..c36ee647355a8fe0ccb5d25835d108a4df04019b 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -24114,6 +24114,34 @@ SELECT collation for ('foo' COLLATE "de_DE");
      </thead>
 
      <tbody>
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>age</primary>
+        </indexterm>
+        <function>age</function>  ( <type>xid</type> )
+        <returnvalue>integer</returnvalue>
+       </para>
+       <para>
+        Returns the number of transactions between the supplied
+        transaction id and the current transaction counter.
+       </para></entry>
+      </row>
+
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>mxid_age</primary>
+        </indexterm>
+        <function>mxid_age</function>  ( <type>xid</type> )
+        <returnvalue>integer</returnvalue>
+       </para>
+       <para>
+        Returns the number of multixacts IDs between the supplied
+        multixact ID and the current multixacts counter.
+       </para></entry>
+      </row>
+
       <row>
        <entry role="func_table_entry"><para role="func_signature">
         <indexterm>
@@ -24249,7 +24277,8 @@ SELECT collation for ('foo' COLLATE "de_DE");
    <para>
     The internal transaction ID type <type>xid</type> is 32 bits wide and
     wraps around every 4 billion transactions.  However,
-    the functions shown in <xref linkend="functions-pg-snapshot"/> use a
+    the functions shown in <xref linkend="functions-pg-snapshot"/>, except
+    <function>age</function> and <function>mxid_age</function>, use a
     64-bit type <type>xid8</type> that does not wrap around during the life
     of an installation, and can be converted to <type>xid</type> by casting if
     required.  The data type <type>pg_snapshot</type> stores information about