From 939afd7dfef626e41d54a1cdb28d4308be25ada0 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 v4 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 corresponding 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 | 33 ++++++++++++++++++++-------------
 1 file changed, 20 insertions(+), 13 deletions(-)
 100.0% doc/src/sgml/

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 445fbc9232c..4da72c419c2 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -3144,24 +3144,31 @@ 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>vacuum</literal>: I/O operations performed using the
+          <literal>vacuum</literal>
+          <glossterm linkend="glossary-buffer-access-strategy">buffer access
+          strategy</glossterm>, for example, while vacuuming or analyzing
+          permanent relations or enabling data checksums. 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 FROM</command>.
          </para>
         </listitem>
        </itemizedlist>
@@ -3340,8 +3347,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 +3359,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