From 752e82edbdf03ace7297aca300bee5a3a193dbc0 Mon Sep 17 00:00:00 2001
From: Bertrand Drouvot <bertranddrouvot.pg@gmail.com>
Date: Wed, 28 Oct 2026 09:42:48 +0000
Subject: [PATCH v2 3/8] Clarify buffer access strategies in pg_stat_io
 documentation

The pg_stat_io descriptions for vacuum, bulkread, and bulkwrite say that
I/O is performed outside shared buffers, and the evictions and reuses
descriptions refer to a separate ring buffer.  Strategy rings instead
contain references to a limited set of shared buffers.

Identify each context with its same named buffer access strategy and remove
the incorrect references to strategy rings as separate from shared buffers.

Suggested-by: Sami Imseih <samimseih.pg@gmail.com>
Author: Bertrand Drouvot <bertranddrouvot.pg@gmail.com>
Reviewed-by: Sami Imseih <samimseih.pg@gmail.com>
Discussion: https://postgr.es/m/auCYYbDyrQEwIsQq@bdtpg
---
 doc/src/sgml/monitoring.sgml | 34 ++++++++++++++++++++--------------
 1 file changed, 20 insertions(+), 14 deletions(-)
 100.0% doc/src/sgml/

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 31ff4a9d99f..c62c7caa66a 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -3144,24 +3144,30 @@ description | Waiting for a newly initialized WAL file to reach durable storage
         </listitem>
         <listitem>
          <para>
-          <literal>vacuum</literal>: I/O operations performed outside of shared
-          buffers while vacuuming and analyzing permanent relations. Temporary
-          table vacuums use the same local buffer pool as other temporary table
-          I/O operations and are tracked in <varname>context</varname>
-          <literal>normal</literal>.
+          <literal>vacuum</literal>: I/O operations performed using the
+          <literal>vacuum</literal>
+          <glossterm linkend="glossary-buffer-access-strategy">buffer access
+          strategy</glossterm> while vacuuming and analyzing permanent
+          relations. Temporary table vacuums use the same local buffer pool as
+          other temporary table I/O operations and are tracked in
+          <varname>context</varname> <literal>normal</literal>.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>bulkread</literal>: Certain large read I/O operations
-          done outside of shared buffers, for example, a sequential scan of a
-          large table.
+          performed using the <literal>bulkread</literal>
+          <glossterm linkend="glossary-buffer-access-strategy">buffer access
+          strategy</glossterm>, for example, a sequential scan of a large
+          table.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>bulkwrite</literal>: Certain large write I/O operations
-          done outside of shared buffers, such as <command>COPY</command>.
+          performed using the <literal>bulkwrite</literal>
+          <glossterm linkend="glossary-buffer-access-strategy">buffer access
+          strategy</glossterm>, such as <command>COPY</command>.
          </para>
         </listitem>
        </itemizedlist>
@@ -3340,8 +3346,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage
         another block. In <varname>context</varname>s
         <literal>bulkwrite</literal>, <literal>bulkread</literal>, and
         <literal>vacuum</literal>, this counts the number of times a block was
-        evicted from shared buffers in order to add the shared buffer to a
-        separate, size-limited ring buffer for use in a bulk I/O operation.
+        evicted from a shared buffer in order to add that buffer to a strategy
+        ring for use in a bulk I/O operation.
         </para>
       </entry>
      </row>
@@ -3352,10 +3358,10 @@ description | Waiting for a newly initialized WAL file to reach durable storage
         <structfield>reuses</structfield> <type>bigint</type>
        </para>
        <para>
-        The number of times an existing buffer in a size-limited ring buffer
-        outside of shared buffers was reused as part of an I/O operation in the
-        <literal>bulkread</literal>, <literal>bulkwrite</literal>, or
-        <literal>vacuum</literal> <varname>context</varname>s.
+        The number of times a shared buffer in a strategy ring was reused as
+        part of an I/O operation in the <literal>bulkread</literal>,
+        <literal>bulkwrite</literal>, or <literal>vacuum</literal>
+        <varname>context</varname>s.
        </para>
       </entry>
      </row>
-- 
2.34.1