From 6150103c1e2f8ceafda43d4d7d0beec62368e72e Mon Sep 17 00:00:00 2001
From: Nazir Bilal Yavuz <byavuz81@gmail.com>
Date: Wed, 9 Sep 2026 14:16:40 +0300
Subject: [PATCH v2 8/8] aio: doc: Document AIO fsync

Describe the fsync operation and sync and sync_filetag targets exposed
by pg_aios, including the NULL offset and length for synchronization
operations.

Explain that crash-recovery file synchronization can overlap with
io_uring but runs synchronously with the worker method because workers
cannot reopen these path-only targets. Distinguish this fallback from
relation and SLRU synchronization during checkpoints.

Discussion: https://postgr.es/m/CAN55FZ0vLWJQNB%3DHuHXG2wabFjXJd6OWTa3%3DkRzwObdZD9poHQ%40mail.gmail.com
---
 doc/src/sgml/config.sgml       | 10 ++++++++++
 doc/src/sgml/system-views.sgml | 22 ++++++++++++++++++++--
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 0165eb9ec02..984be7c7167 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -12292,6 +12292,16 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir'
         starting a database cluster that did not shut down cleanly, including
         copies created with <application>pg_basebackup</application>.
        </para>
+       <para>
+        When this parameter is set to <literal>fsync</literal> and
+        <xref linkend="guc-io-method"/> is set to <literal>io_uring</literal>,
+        multiple file synchronization operations can run concurrently.
+        With <literal>worker</literal> or <literal>sync</literal>, these
+        operations run synchronously in the startup process.  Unlike relation
+        and SLRU synchronization during checkpoints, data-directory
+        synchronization does not provide the information needed for I/O
+        workers to reopen the files.
+       </para>
        <para>
         On Linux, <literal>syncfs</literal> may be used instead, to ask the
         operating system to synchronize the file systems that contain the
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 77202e2c765..9ed5e1b7d49 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -387,6 +387,12 @@
           <literal>writev</literal>, a vectored write
          </para>
         </listitem>
+        <listitem>
+         <para>
+          <literal>fsync</literal>, file synchronization using
+          <function>fsync()</function> or <function>fdatasync()</function>
+         </para>
+        </listitem>
        </itemizedlist>
       </para></entry>
      </row>
@@ -396,7 +402,7 @@
        <structfield>off</structfield> <type>int8</type>
       </para>
       <para>
-       Offset of the I/O operation.
+       Offset of the I/O operation, or NULL for <literal>fsync</literal>.
       </para></entry>
      </row>
 
@@ -405,7 +411,7 @@
        <structfield>length</structfield> <type>int8</type>
       </para>
       <para>
-       Length of the I/O operation.
+       Length of the I/O operation, or NULL for <literal>fsync</literal>.
       </para></entry>
      </row>
 
@@ -421,6 +427,18 @@
           <literal>smgr</literal>, I/O on relations
          </para>
         </listitem>
+        <listitem>
+         <para>
+          <literal>sync</literal>, file synchronization using a process-local
+          file descriptor
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          <literal>sync_filetag</literal>, file synchronization identified by
+          a file tag, currently used for SLRU segments
+         </para>
+        </listitem>
        </itemizedlist>
       </para></entry>
      </row>
-- 
2.47.3