commit 8c7a1630516749a7eaa6aa4fc8f117962858dcea
Author: David G. Johnston <david.g.johnston@gmail.com>
Date:   Wed Oct 21 20:07:35 2020 +0000

    Review of the Collaboration of Processes section

diff --git a/doc/src/sgml/architecture.sgml b/doc/src/sgml/architecture.sgml
index 2be9898d98..3fa896cefb 100644
--- a/doc/src/sgml/architecture.sgml
+++ b/doc/src/sgml/architecture.sgml
@@ -1,11 +1,11 @@
 <!-- doc/src/sgml/architecture.sgml -->
 
  <chapter id="tutorial-architecture">
-  <title>Architectural and implementational Cornerstones</title>
+  <title>Architecture and Implementation</title>
 
   <para>
-   Every DBMS implements basic strategies for a fast and
-   robust system. This chapter provides an overview of what
+   Every DBMS implements basic strategies to ensure a fast
+   and robust system. This chapter provides an overview of the
    techniques <productname>PostgreSQL</productname> uses to
    achieve this.
   </para>
@@ -14,26 +14,35 @@
    <title>Collaboration of Processes, RAM, and Files</title>
    <para>
     In a client/server architecture
-    clients do not have direct access to the database. Instead,
+    clients do not have direct access to stored data. Instead,
     they send requests to the server and receive
-    the requested information. In the case of
-    <productname>PostgreSQL</productname>, at the server-side
-    there is one process per client, the so-called
+    the requested data in response. In the case of
+    <productname>PostgreSQL</productname>, the server launches a
+    single process for each connected client, referred to as a
     <glossterm linkend="glossary-backend">Backend process</glossterm>.
+    <!-- DGJ: this whole next paragraph bothers me but I cannot justify
+         simply removing it nor have a possibly better suggestion.
+         In particular I disagree with categorizing this is a
+         "close" and "tightly-coupled" relationship -->
     It acts in close cooperation with the
     <glossterm linkend="glossary-instance">instance</glossterm> which
     is a group of tightly coupled server-side processes plus a
     <glossterm linkend="glossary-shared-memory">Shared Memory</glossterm>
-    area.
+    area located in RAM.
+    Notably, PostgreSQL does not utilize application threading within its
+    implementation.
    </para>
 
+     <!-- DGJ: I've gotten the impression firstterm 
+          is overused, probably as a result of copy-paste -->
+
    <para>
-    At startup time, an <firstterm>instance</firstterm> is initiated by the
-    <glossterm linkend="glossary-postmaster">Postmaster</glossterm>.
-    The <firstterm>Postmaster</firstterm> process loads the
+    During <firstterm>instance</firstterm> startup time, the
+    <glossterm linkend="glossary-postmaster">Postmaster</glossterm>
+    process loads the
     configuration files, allocates
     <firstterm>Shared Memory</firstterm>,
-    and starts a network of processes:
+    and starts supporting background processes:
     <glossterm linkend="glossary-background-writer">Background Writer</glossterm>,
     <glossterm linkend="glossary-checkpointer">Checkpointer</glossterm>,
     <glossterm linkend="glossary-wal-writer">WAL Writer</glossterm>,
@@ -62,9 +71,11 @@
    </figure>
 
    <para>
-    Whenever a client application tries to connect to a
+    <!-- DGJ: This is detailed, but wrong.  Either use less detail or correct detail.
+         See header of postmaster.c -->
+    When a client application tries to connect to a
     <glossterm linkend="glossary-database">database</glossterm>,
-    this request is handled in a first step by the
+    this request is handled initially by the
     <firstterm>Postmaster</firstterm> process. It checks authorization,
     starts a new <firstterm>Backend process</firstterm>,
     and instructs the client application to connect to it. All
@@ -75,123 +86,64 @@
    <para>
     Client requests like <command>SELECT</command> or
     <command>UPDATE</command> usually lead to the
-    necessity to read or write some data. In a first attempt
-    the client's <firstterm>Backend process</firstterm> tries
-    to get the information out of <firstterm>Shared
-    Memory</firstterm>. This <firstterm>Shared
-    Memory</firstterm> is a mirror of parts of the
-    <glossterm linkend="glossary-heap">heap</glossterm> and
-    <glossterm linkend="glossary-index">index</glossterm> files.
-    Because files are often larger than memory, it's likely that
-    the desired information is not (completely) available
-    in RAM. In this case the <firstterm>Backend process</firstterm>
-    must transfer additional file pages to
-    <firstterm>Shared Memory</firstterm>. Files are physically
-    organized in pages. Every transfer between files and
-    RAM is performed in units of complete pages; such transfers
-    do not change the size or layout of pages.
-   </para>
-
-   <para>
-    Reading file pages is much slower than reading
-    RAM. This is the primary motivation for the usage of
-    <firstterm>Shared Memory</firstterm>. As soon as one
-    of the <firstterm>Backend processes</firstterm> has
-    read pages into memory, those pages become available for all
-    other <firstterm>Backend processes</firstterm> for direct
-    access in RAM.
+    necessity to read or write some data. 
+    Reads involve a page-level cache housed in Shared Memory
+    for the benefit of all processes in the instance.
+    <!-- DGJ: provide internals documentation link -->
+    Writes also involve this cache, in additional to a journal,
+    called a write-ahead-log or WAL, in PostgreSQL.
    </para>
 
    <para>
     <firstterm>Shared Memory</firstterm> is limited in size.
-    Sooner or later, it becomes necessary to overwrite old RAM
-    pages. As long as the content of such pages hasn't
+    thus it becomes necessary to evict pages.
+    As long as the content of such pages hasn't
     changed, this is not a problem. But in
     <firstterm>Shared Memory</firstterm> also write
-    actions take place
-    &mdash; performed by any of the <firstterm>Backend
-    processes</firstterm> (or an
-    <firstterm>autovacuum</firstterm> process,
-    or other processes). Such modified pages are called
-    <firstterm>dirty pages</firstterm>.
-    Before <firstterm>dirty pages</firstterm> can be overwritten,
-    they must be written back to disk. This is a two-step process.
-   </para>
-
-   <para>
-    First, whenever the content of a page changes, a
-    <glossterm linkend="glossary-wal-record">WAL record</glossterm>
-    is created out
-    of the delta-information (difference between the old and
-    the new content) and stored in another area of
-    <firstterm>Shared Memory</firstterm>. These
-    <firstterm>WAL records</firstterm> are read by the
-    <firstterm>WAL Writer</firstterm> process,
-    which runs in parallel to the <firstterm>Backend
-    processes</firstterm> and other processes of
-    the <firstterm>Instance</firstterm>. It writes
-    the continuously arising <firstterm>WAL records</firstterm> to
-    the end of the current
-    <glossterm linkend="glossary-wal-record">WAL file</glossterm>.
-    Because this writing is sequential, it is much
-    faster than the more or less random access
-    to data files with <firstterm>heap</firstterm>
-    and <firstterm>index</firstterm> information.
-    As mentioned, this WAL-writing happens
-    in an independent process. All
-    <firstterm>WAL records</firstterm> created out of one
-    <firstterm>dirty page</firstterm> must be transferred
-    to disk before the <firstterm>dirty page</firstterm>
-    itself can be transferred to disk.
-   </para>
-
-   <para>
-    Second, the transfer of <firstterm>dirty buffers</firstterm>
-    from <firstterm>Shared Memory</firstterm> to file must
-    take place. This is the primary task of the
-    <firstterm>Background Writer</firstterm> process. Because
-    I/O activities can block other processes significantly,
-    it starts periodically and acts only for a short period.
-    Doing so, its expensive I/O activities are spread over
-    time, avoiding debilitating I/O peaks. Also, the <firstterm>
-    Checkpointer</firstterm> process transfers
-    <firstterm>dirty buffers</firstterm> to file &mdash;
-    see next paragraph.
-   </para>
-
-   <para>
-    The <firstterm>Checkpointer</firstterm> creates
-    <glossterm linkend="glossary-checkpoint">Checkpoints</glossterm>.
-    A <firstterm>Checkpoint</firstterm>
-    is a point in time when all older <firstterm>dirty buffers</firstterm>,
-    all older <firstterm>WAL records</firstterm>, and
-    finally a special <firstterm>Checkpoint record</firstterm>
-    have been written and flushed to disk.
-    After a <firstterm>Checkpoint</firstterm>, we say
-    data files and <firstterm>WAL files</firstterm> are in sync.
-    In case of a recovery (after a crash of the instance)
-    it can be relied upon that the information of all
-    <firstterm>WAL records</firstterm> preceding
-    the last <firstterm>Checkpoint record</firstterm>
-    were already integrated into the data files. This
-    speeds up the recovery.
-   </para>
-
-   <para>
-    As a result of data changes,
-    <firstterm>WAL records</firstterm> arise and get written
-    to <firstterm>WAL files</firstterm>.
-    Those <firstterm>WAL files</firstterm> &mdash; in combination with
-    a previously taken <firstterm>Base Backup</firstterm> &mdash;
-    are necessary to restore a database after a crash of the
-    disk on which data files have been stored. Therefore it is
-    recommended to transfer a copy of the
-    <firstterm> WAL files</firstterm>
-    to a second, independent place. The purpose of the
-    <firstterm>WAL Archiver</firstterm> process is to perform
-    this copy action.
+    actions take place.
+    Modified pages are called
+    <firstterm>dirty pages</firstterm> or
+    <firstterm>dirty buffers</firstterm> and
+    before <firstterm>dirty pages</firstterm> can be evicted
+    they must be written back to disk. This also happens regularly
+    by the <firstterm>Background Writer</firstterm>
+    process to ensure that the disk version of
+    the page is kept up-to-date. Writes are only performed against
+    the pages in Shared Memory.
+   </para>
+
+    <!-- DGJ: WAL should already be done well before page eviction/overwriting
+         comes into play.  This is good material but seems misplaced. -->
+
+
+   <para>
+    The <firstterm>Background Writer</firstterm> process spreads
+    its expensive I/O activity over time while coordinating with
+    the overall system through the Checkpointer process - which
+    places checkpoint records into the WAL noting instances in
+    time when all dirty pages in Shared Memory corresponding to
+    previously written WAL have been written to file.  At these
+    checkpoints previous WAL is no longer required so long as
+    the data files on hand are current.  In other words, recovery
+    happens by replaying WAL from the last recorded checkpoint
+    on top of the current data files.
+   </para>
+
+   <para>
+    While the Checkpointer ensures that a running system can crash
+    and restart itself in a valid state the administration needs to
+    handle the case where the data files themselves become corrupted
+    (and possibly the locally written WAL, though that is less common.)
+    The options and details are covered extensively in the backup
+    and restore section of the documentation.
+    <!-- DGJ: link -->
+    For our purposes here note just that the
+    <firstterm>WAL Archiver</firstterm> process can be enabled and configured
+    to run a script on a filled WAL file - usually to copy it to a remote location.
    </para>
 
+   <!-- DGJ: after the heavy focus on client processes and data these two
+        seem to come out of left field.  Skipping over for now. -->
    <para>
     The <firstterm>Statistics Collector</firstterm> collects
     counters about accesses to <firstterm>SQL objects</firstterm>
@@ -202,7 +154,7 @@
    <para>
     The <firstterm>Logger</firstterm> writes
     text lines about serious and less serious events which can happen
-    during database access, e.g. wrong password, no permission,
+    during database access, e.g., wrong password, no permission,
     long-running queries, etc.
    </para>
 
