From 40a11f8958f0d908ec7eb258b6ae4cb5b8a12465 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathandbossart@gmail.com>
Date: Mon, 23 Jan 2023 10:35:52 -0800
Subject: [PATCH v10 2/4] create WAL modules chapter in docs in preparation for
 recovery modules

---
 doc/src/sgml/archive-modules.sgml | 136 ----------------------------
 doc/src/sgml/backup.sgml          |   2 +-
 doc/src/sgml/basic-archive.sgml   |   2 +-
 doc/src/sgml/config.sgml          |   2 +-
 doc/src/sgml/filelist.sgml        |   2 +-
 doc/src/sgml/postgres.sgml        |   2 +-
 doc/src/sgml/system-views.sgml    |   2 +-
 doc/src/sgml/wal-modules.sgml     | 144 ++++++++++++++++++++++++++++++
 8 files changed, 150 insertions(+), 142 deletions(-)
 delete mode 100644 doc/src/sgml/archive-modules.sgml
 create mode 100644 doc/src/sgml/wal-modules.sgml

diff --git a/doc/src/sgml/archive-modules.sgml b/doc/src/sgml/archive-modules.sgml
deleted file mode 100644
index ef02051f7f..0000000000
--- a/doc/src/sgml/archive-modules.sgml
+++ /dev/null
@@ -1,136 +0,0 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
-
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
-  <primary>Archive Modules</primary>
- </indexterm>
-
- <para>
-  PostgreSQL provides infrastructure to create custom modules for continuous
-  archiving (see <xref linkend="continuous-archiving"/>).  While archiving via
-  a shell command (i.e., <xref linkend="guc-archive-command"/>) is much
-  simpler, a custom archive module will often be considerably more robust and
-  performant.
- </para>
-
- <para>
-  When a custom <xref linkend="guc-archive-library"/> is configured, PostgreSQL
-  will submit completed WAL files to the module, and the server will avoid
-  recycling or removing these WAL files until the module indicates that the files
-  were successfully archived.  It is ultimately up to the module to decide what
-  to do with each WAL file, but many recommendations are listed at
-  <xref linkend="backup-archiving-wal"/>.
- </para>
-
- <para>
-  Archiving modules must at least consist of an initialization function (see
-  <xref linkend="archive-module-init"/>) and the required callbacks (see
-  <xref linkend="archive-module-callbacks"/>).  However, archive modules are
-  also permitted to do much more (e.g., declare GUCs and register background
-  workers).
- </para>
-
- <para>
-  The <filename>contrib/basic_archive</filename> module contains a working
-  example, which demonstrates some useful techniques.
- </para>
-
- <sect1 id="archive-module-init">
-  <title>Initialization Functions</title>
-  <indexterm zone="archive-module-init">
-   <primary>_PG_archive_module_init</primary>
-  </indexterm>
-  <para>
-   An archive library is loaded by dynamically loading a shared library with the
-   <xref linkend="guc-archive-library"/>'s name as the library base name.  The
-   normal library search path is used to locate the library.  To provide the
-   required archive module callbacks and to indicate that the library is
-   actually an archive module, it needs to provide a function named
-   <function>_PG_archive_module_init</function>.  This function is passed a
-   struct that needs to be filled with the callback function pointers for
-   individual actions.
-
-<programlisting>
-typedef struct ArchiveModuleCallbacks
-{
-    ArchiveCheckConfiguredCB check_configured_cb;
-    ArchiveFileCB archive_file_cb;
-    ArchiveShutdownCB shutdown_cb;
-} ArchiveModuleCallbacks;
-typedef void (*ArchiveModuleInit) (struct ArchiveModuleCallbacks *cb);
-</programlisting>
-
-   Only the <function>archive_file_cb</function> callback is required.  The
-   others are optional.
-  </para>
- </sect1>
-
- <sect1 id="archive-module-callbacks">
-  <title>Archive Module Callbacks</title>
-  <para>
-   The archive callbacks define the actual archiving behavior of the module.
-   The server will call them as required to process each individual WAL file.
-  </para>
-
-  <sect2 id="archive-module-check">
-   <title>Check Callback</title>
-   <para>
-    The <function>check_configured_cb</function> callback is called to determine
-    whether the module is fully configured and ready to accept WAL files (e.g.,
-    its configuration parameters are set to valid values).  If no
-    <function>check_configured_cb</function> is defined, the server always
-    assumes the module is configured.
-
-<programlisting>
-typedef bool (*ArchiveCheckConfiguredCB) (void);
-</programlisting>
-
-    If <literal>true</literal> is returned, the server will proceed with
-    archiving the file by calling the <function>archive_file_cb</function>
-    callback.  If <literal>false</literal> is returned, archiving will not
-    proceed, and the archiver will emit the following message to the server log:
-<screen>
-WARNING:  archive_mode enabled, yet archiving is not configured
-</screen>
-    In the latter case, the server will periodically call this function, and
-    archiving will proceed only when it returns <literal>true</literal>.
-   </para>
-  </sect2>
-
-  <sect2 id="archive-module-archive">
-   <title>Archive Callback</title>
-   <para>
-    The <function>archive_file_cb</function> callback is called to archive a
-    single WAL file.
-
-<programlisting>
-typedef bool (*ArchiveFileCB) (const char *file, const char *path);
-</programlisting>
-
-    If <literal>true</literal> is returned, the server proceeds as if the file
-    was successfully archived, which may include recycling or removing the
-    original WAL file.  If <literal>false</literal> is returned, the server will
-    keep the original WAL file and retry archiving later.
-    <replaceable>file</replaceable> will contain just the file name of the WAL
-    file to archive, while <replaceable>path</replaceable> contains the full
-    path of the WAL file (including the file name).
-   </para>
-  </sect2>
-
-  <sect2 id="archive-module-shutdown">
-   <title>Shutdown Callback</title>
-   <para>
-    The <function>shutdown_cb</function> callback is called when the archiver
-    process exits (e.g., after an error) or the value of
-    <xref linkend="guc-archive-library"/> changes.  If no
-    <function>shutdown_cb</function> is defined, no special action is taken in
-    these situations.
-
-<programlisting>
-typedef void (*ArchiveShutdownCB) (void);
-</programlisting>
-   </para>
-  </sect2>
- </sect1>
-</chapter>
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index be05a33205..12d9bb3f81 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -660,7 +660,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/0
     than writing a shell command.  However, archive modules can be more
     performant than archiving via shell, and they will have access to many
     useful server resources.  For more information about archive modules, see
-    <xref linkend="archive-modules"/>.
+    <xref linkend="wal-modules"/>.
    </para>
 
    <para>
diff --git a/doc/src/sgml/basic-archive.sgml b/doc/src/sgml/basic-archive.sgml
index b4d43ced20..a877564af2 100644
--- a/doc/src/sgml/basic-archive.sgml
+++ b/doc/src/sgml/basic-archive.sgml
@@ -12,7 +12,7 @@
   module copies completed WAL segment files to the specified directory.  This
   may not be especially useful, but it can serve as a starting point for
   developing your own archive module.  For more information about archive
-  modules, see <xref linkend="archive-modules"/>.
+  modules, see <xref linkend="wal-modules"/>.
  </para>
 
  <para>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index f985afc009..bba24bdcb8 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -3666,7 +3666,7 @@ include_dir 'conf.d'
         shared library is used for archiving. The WAL archiver process is
         restarted by the postmaster when this parameter changes. For more
         information, see <xref linkend="backup-archiving-wal"/> and
-        <xref linkend="archive-modules"/>.
+        <xref linkend="wal-modules"/>.
        </para>
        <para>
         This parameter can only be set in the
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 0d6be9a2fa..f7b6d8b1be 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -100,7 +100,7 @@
 <!ENTITY custom-scan SYSTEM "custom-scan.sgml">
 <!ENTITY logicaldecoding SYSTEM "logicaldecoding.sgml">
 <!ENTITY replication-origins SYSTEM "replication-origins.sgml">
-<!ENTITY archive-modules SYSTEM "archive-modules.sgml">
+<!ENTITY wal-modules SYSTEM "wal-modules.sgml">
 <!ENTITY protocol   SYSTEM "protocol.sgml">
 <!ENTITY sources    SYSTEM "sources.sgml">
 <!ENTITY storage    SYSTEM "storage.sgml">
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 2e271862fc..817e774155 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -233,7 +233,7 @@ break is not needed in a wider output rendering.
   &bgworker;
   &logicaldecoding;
   &replication-origins;
-  &archive-modules;
+  &wal-modules;
 
  </part>
 
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 7c8fc3f654..e93e733051 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -3351,7 +3351,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
    <xref linkend="guc-shared-preload-libraries"/>,
    a call to a C function in the extension, or the
    <link linkend="sql-load"><command>LOAD</command></link> command).
-   For example, since <link linkend="archive-modules">archive modules</link>
+   For example, since <link linkend="wal-modules">archive modules</link>
    are normally loaded only by the archiver process not regular sessions,
    this view will not display any customized options defined by such modules
    unless special action is taken to load them into the backend process
diff --git a/doc/src/sgml/wal-modules.sgml b/doc/src/sgml/wal-modules.sgml
new file mode 100644
index 0000000000..6fd2763e41
--- /dev/null
+++ b/doc/src/sgml/wal-modules.sgml
@@ -0,0 +1,144 @@
+<!-- doc/src/sgml/wal-modules.sgml -->
+
+<chapter id="wal-modules">
+ <title>Write-Ahead Log Modules</title>
+ <indexterm zone="wal-modules">
+  <primary>Write-Ahead Log Modules</primary>
+ </indexterm>
+
+ <para>
+  PostgreSQL provides infrastructure to create custom modules for continuous
+  archiving (see <xref linkend="continuous-archiving"/>).  While archiving via
+  a shell command (i.e., <xref linkend="guc-archive-command"/>) is much
+  simpler, a custom WAL module will often be considerably more robust and
+  performant.
+ </para>
+
+ <para>
+  When a custom <xref linkend="guc-archive-library"/> is configured, PostgreSQL
+  will submit completed WAL files to the module, and the server will avoid
+  recycling or removing these WAL files until the module indicates that the
+  files were successfully archived.  It is ultimately up to the module to
+  decide what to do with each WAL file, but many recommendations are listed at
+  <xref linkend="backup-archiving-wal"/>.
+ </para>
+
+ <para>
+  Archiving modules must at least consist of an initialization function (see
+  <xref linkend="archive-module-init"/>) and the required callbacks (see
+  <xref linkend="archive-module-callbacks"/>).  However, archive modules are
+  also permitted to do much more (e.g., declare GUCs and register background
+  workers).
+ </para>
+
+ <para>
+  The <filename>contrib/basic_archive</filename> module contains a working
+  example, which demonstrates some useful techniques.
+ </para>
+
+ <sect1 id="archive-modules">
+  <title>Archive Modules</title>
+  <indexterm zone="archive-modules">
+   <primary>Archive Modules</primary>
+  </indexterm>
+
+  <sect2 id="archive-module-init">
+   <title>Initialization Functions</title>
+   <indexterm zone="archive-module-init">
+    <primary>_PG_archive_module_init</primary>
+   </indexterm>
+   <para>
+    An archive library is loaded by dynamically loading a shared library with
+    the <xref linkend="guc-archive-library"/>'s name as the library base name.
+    The normal library search path is used to locate the library.  To provide
+    the required archive module callbacks and to indicate that the library is
+    actually an archive module, it needs to provide a function named
+    <function>_PG_archive_module_init</function>.  This function is passed a
+    struct that needs to be filled with the callback function pointers for
+    individual actions.
+
+<programlisting>
+typedef struct ArchiveModuleCallbacks
+{
+    ArchiveCheckConfiguredCB check_configured_cb;
+    ArchiveFileCB archive_file_cb;
+    ArchiveShutdownCB shutdown_cb;
+} ArchiveModuleCallbacks;
+typedef void (*ArchiveModuleInit) (struct ArchiveModuleCallbacks *cb);
+</programlisting>
+
+    Only the <function>archive_file_cb</function> callback is required.  The
+    others are optional.
+   </para>
+  </sect2>
+
+  <sect2 id="archive-module-callbacks">
+   <title>Archive Module Callbacks</title>
+   <para>
+    The archive callbacks define the actual archiving behavior of the module.
+    The server will call them as required to process each individual WAL file.
+   </para>
+
+   <sect3 id="archive-module-check">
+    <title>Check Callback</title>
+    <para>
+     The <function>check_configured_cb</function> callback is called to
+     determine whether the module is fully configured and ready to accept WAL
+     files (e.g., its configuration parameters are set to valid values).  If no
+     <function>check_configured_cb</function> is defined, the server always
+     assumes the module is configured.
+
+<programlisting>
+typedef bool (*ArchiveCheckConfiguredCB) (void);
+</programlisting>
+
+     If <literal>true</literal> is returned, the server will proceed with
+     archiving the file by calling the <function>archive_file_cb</function>
+     callback.  If <literal>false</literal> is returned, archiving will not
+     proceed, and the archiver will emit the following message to the server
+     log:
+<screen>
+WARNING:  archive_mode enabled, yet archiving is not configured
+</screen>
+     In the latter case, the server will periodically call this function, and
+     archiving will proceed only when it returns <literal>true</literal>.
+    </para>
+   </sect3>
+
+   <sect3 id="archive-module-archive">
+    <title>Archive Callback</title>
+    <para>
+     The <function>archive_file_cb</function> callback is called to archive a
+     single WAL file.
+
+<programlisting>
+typedef bool (*ArchiveFileCB) (const char *file, const char *path);
+</programlisting>
+
+     If <literal>true</literal> is returned, the server proceeds as if the file
+     was successfully archived, which may include recycling or removing the
+     original WAL file.  If <literal>false</literal> is returned, the server
+     will keep the original WAL file and retry archiving later.
+     <replaceable>file</replaceable> will contain just the file name of the WAL
+     file to archive, while <replaceable>path</replaceable> contains the full
+     path of the WAL file (including the file name).
+    </para>
+   </sect3>
+
+   <sect3 id="archive-module-shutdown">
+    <title>Shutdown Callback</title>
+    <para>
+     The <function>shutdown_cb</function> callback is called when the archiver
+     process exits (e.g., after an error) or the value of
+     <xref linkend="guc-archive-library"/> changes.  If no
+     <function>shutdown_cb</function> is defined, no special action is taken in
+     these situations.
+
+<programlisting>
+typedef void (*ArchiveShutdownCB) (void);
+</programlisting>
+    </para>
+   </sect3>
+  </sect2>
+ </sect1>
+</chapter>
-- 
2.25.1

