Date: Mon, 30 Jun 2025 16:33:56 -0500
From: Nathan Bossart <nathandbossart@gmail.com>
To: pgsql-hackers@postgresql.org
Subject: back-patch documentation for age() and mxid_age()
Message-ID: <aGMCxHxLfeMdQk8m@nathan>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="NIKakGvuI9thMFLF"
Content-Disposition: inline
Archived-At: <https://www.postgresql.org/message-id/aGMCxHxLfeMdQk8m%40nathan>
Precedence: bulk


--NIKakGvuI9thMFLF
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

These functions have been around for a while, but commits 48b5aa3 and
15afb7d were only back-patched to v16.  Any objections if I apply them down
to v13 now?

-- 
nathan

--NIKakGvuI9thMFLF
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment;
	filename=v1-0001-Document-age-xid-and-mxid_age-xid.patch

From 5c2fafe16a95bea32fd0808d596afb18446f69a6 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Mon, 30 Jun 2025 16:21:34 -0500
Subject: [PATCH v1 1/1] Document age(xid) and mxid_age(xid).

---
 doc/src/sgml/func.sgml | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 372cb036fde..f11c4f711d4 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -24638,6 +24638,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>
@@ -24773,7 +24801,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
-- 
2.39.5 (Apple Git-154)


--NIKakGvuI9thMFLF--