From 55d201782396d051f580eea81a73d7cb412fc67b Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathandbossart@gmail.com>
Date: Wed, 15 Feb 2023 14:48:36 -0800
Subject: [PATCH v23 4/5] restructure archive modules docs in preparation for
 restore modules

---
 doc/src/sgml/archive-and-restore-modules.sgml | 242 +++++++++---------
 1 file changed, 128 insertions(+), 114 deletions(-)

diff --git a/doc/src/sgml/archive-and-restore-modules.sgml b/doc/src/sgml/archive-and-restore-modules.sgml
index 10ec96eae9..6e368290b9 100644
--- a/doc/src/sgml/archive-and-restore-modules.sgml
+++ b/doc/src/sgml/archive-and-restore-modules.sgml
@@ -1,9 +1,9 @@
-<!-- doc/src/sgml/archive-modules.sgml -->
+<!-- doc/src/sgml/archive-and-restore-modules.sgml -->
 
-<chapter id="archive-modules">
- <title>Archive Modules</title>
- <indexterm zone="archive-modules">
-  <primary>Archive Modules</primary>
+<chapter id="archive-and-restore-modules">
+ <title>Archive and Restore Modules</title>
+ <indexterm zone="archive-and-restore-modules">
+  <primary>Archive and Restore Modules</primary>
  </indexterm>
 
  <para>
@@ -14,45 +14,52 @@
   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>
+ <sect1 id="archive-modules">
+  <title>Archive Modules</title>
+  <indexterm zone="archive-modules">
+   <primary>Archive Modules</primary>
   </indexterm>
+
+  <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>
-   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>.  The result of the function
-   must be a pointer to a struct of type
-   <structname>ArchiveModuleCallbacks</structname>, which contains everything
-   that the core code needs to know to make use of the archive module.  The
-   return value needs to be of server lifetime, which is typically achieved by
-   defining it as a <literal>static const</literal> variable in global scope.
+   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>
+
+  <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>.  The result of the function
+    must be a pointer to a struct of type
+    <structname>ArchiveModuleCallbacks</structname>, which contains everything
+    that the core code needs to know to make use of the archive module.  The
+    return value needs to be of server lifetime, which is typically achieved by
+    defining it as a <literal>static const</literal> variable in global scope.
 
 <programlisting>
 typedef struct ArchiveModuleCallbacks
@@ -65,112 +72,119 @@ typedef struct ArchiveModuleCallbacks
 typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);
 </programlisting>
 
-   Only the <function>archive_file_cb</function> callback is required.  The
-   others are optional.
-  </para>
- </sect1>
+    Only the <function>archive_file_cb</function> callback is required.  The
+    others are optional.
+   </para>
+  </sect2>
 
- <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-callbacks">
+   <title>Archive Module Callbacks</title>
 
-  <sect2 id="archive-module-startup">
-   <title>Startup Callback</title>
    <para>
-    The <function>startup_cb</function> callback is called shortly after the
-    module is loaded.  This callback can be used to perform any additional
-    initialization required.  If the archive module has any state, it can use
-    <structfield>state->private_data</structfield> to store it.
+    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-startup">
+    <title>Startup Callback</title>
+
+    <para>
+     The <function>startup_cb</function> callback is called shortly after the
+     module is loaded.  This callback can be used to perform any additional
+     initialization required.  If the archive module has any state, it can use
+     <structfield>state->private_data</structfield> to store it.
 
 <programlisting>
 typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);
 </programlisting>
-   </para>
-  </sect2>
+    </para>
+   </sect3>
 
-  <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.
+   <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) (ArchiveModuleState *state);
 </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:
+     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>
-
-   <note>
-    <para>
-     When returning <literal>false</literal>, it may be useful to append some
-     additional information to the generic warning message.  To do that, provide
-     a message to the <function>arch_module_check_errdetail</function> macro
-     before returning <literal>false</literal>.  Like
-     <function>errdetail()</function>, this macro accepts a format string
-     followed by an optional list of arguments.  The resulting string will be
-     emitted as the <literal>DETAIL</literal> line of the warning message.
+     In the latter case, the server will periodically call this function, and
+     archiving will proceed only when it returns <literal>true</literal>.
     </para>
-   </note>
-  </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.
+    <note>
+     <para>
+      When returning <literal>false</literal>, it may be useful to append some
+      additional information to the generic warning message.  To do that,
+      provide a message to the <function>arch_module_check_errdetail</function>
+      macro before returning <literal>false</literal>.  Like
+      <function>errdetail()</function>, this macro accepts a format string
+      followed by an optional list of arguments.  The resulting string will be
+      emitted as the <literal>DETAIL</literal> line of the warning message.
+     </para>
+    </note>
+   </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) (ArchiveModuleState *state, 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 or an error is thrown, 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>
-
-   <note>
-    <para>
-     The <function>archive_file_cb</function> callback is called in a
-     short-lived memory context that will be reset between invocations.  If you
-     need longer-lived storage, create a memory context in the module's
-     <function>startup_cb</function> callback.
+     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 or an error is
+     thrown, 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>
-   </note>
-  </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.  If the archive module has any state, this callback should
-    free it to avoid leaks.
+    <note>
+     <para>
+      The <function>archive_file_cb</function> callback is called in a
+      short-lived memory context that will be reset between invocations.  If you
+      need longer-lived storage, create a memory context in the module's
+      <function>startup_cb</function> callback.
+     </para>
+    </note>
+   </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.  If the archive module has any state, this callback
+     should free it to avoid leaks.
 
 <programlisting>
 typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);
 </programlisting>
-   </para>
+    </para>
+   </sect3>
   </sect2>
  </sect1>
 </chapter>
-- 
2.39.3 (Apple Git-146)

