Improve spelling of lock names, and some other editing.

diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 69c73a67ff842611a7c97c0463d0ed9f6785f5c7..fddeb679c87a1732101e4fc41cf65c53cdaaaaac 100644 (file)
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.23 2002/02/18 16:13:10 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.24 2002/03/27 02:36:51 petere Exp $
 -->
 
  <chapter id="mvcc">
@@ -376,24 +376,28 @@ ERROR:  Can't serialize access due to concurrent update
    </indexterm>
 
    <para>
-    <productname>PostgreSQL</productname>
-    provides various lock modes to control concurrent
-    access to data in tables. Some of these lock modes are acquired by
-    <productname>PostgreSQL</productname>
-    automatically before statement execution, while others are
-    provided to be used by applications. All lock modes acquired in a
-    transaction are held for the duration 
-    of the transaction.
+    <productname>PostgreSQL</productname> provides various lock modes
+    to control concurrent access to data in tables.  Users normally
+    need not be concerned about the different lock modes because
+    <productname>PostgreSQL</productname> commands automatically
+    acquire locks of appropriate modes to ensure data integrity while
+    permitting an appropriate level of concurrent access.
+    Nevertheless, a user can manually lock a table in any of the
+    available modes using the <command>LOCK TABLE</command> command.
    </para>
 
-   <sect2>
-    <title>Table-level locks</title>
+   <para>
+    The list below shows the available lock modes and the contexts in
+    which they are used.  Remember that all of these lock modes are
+    table-level locks, even if the name contains the word
+    <quote>row</quote>.  The names of the lock modes are historical.
+   </para>
 
-    <para>
      <variablelist>
+      <title>Table-level lock modes</title>
       <varlistentry>
        <term>
-       AccessShareLock
+       <literal>ACCESS SHARE</literal>
        </term>
        <listitem>
        <para>
@@ -402,139 +406,141 @@ ERROR:  Can't serialize access due to concurrent update
        </para>
 
        <para>
-        Conflicts with AccessExclusiveLock only.
+        Conflicts with the <literal>ACCESS EXCLUSIVE</literal> lock
+        mode only.
        </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>
-       RowShareLock
+       <literal>ROW SHARE</literal>
        </term>
        <listitem>
        <para>
-        Acquired by <command>SELECT FOR UPDATE</command>
-        and <command>LOCK TABLE</command>
-        <option>IN ROW SHARE MODE</option> statements.
+        The <command>SELECT FOR UPDATE</command> command acquires a
+        lock of this mode.
        </para>
 
        <para>
-        Conflicts with ExclusiveLock and AccessExclusiveLock modes.
+        Conflicts with the <literal>EXCLUSIVE</literal> and
+        <literal>ACCESS EXCLUSIVE</literal> lock modes.
        </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>
-       RowExclusiveLock
+       <literal>ROW EXCLUSIVE</literal>
        </term>
        <listitem>
        <para>
-        Acquired by <command>UPDATE</command>, <command>DELETE</command>,
-        <command>INSERT</command> and <command>LOCK TABLE</command>
-        <option>IN ROW EXCLUSIVE MODE</option> statements.
+        The commands <command>UPDATE</command>,
+        <command>DELETE</command>, and <command>INSERT</command>
+        automatically acquire this lock mode.
        </para>
 
        <para>
-        Conflicts with ShareLock, ShareRowExclusiveLock, ExclusiveLock and
-        AccessExclusiveLock modes.
+        Conflicts with the <literal>SHARE</literal>, <literal>SHARE ROW
+        EXCLUSIVE</literal>, <literal>EXCLUSIVE</literal>, and
+        <literal>ACCESS EXCLUSIVE</literal> lock modes.
        </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>
-       ShareUpdateExclusiveLock
+       <literal>SHARE UPDATE EXCLUSIVE</literal>
        </term>
        <listitem>
        <para>
-        Acquired by <command>VACUUM</command> (without <option>FULL</option>)
-        and <command>LOCK TABLE</command>
-        <option>IN SHARE UPDATE EXCLUSIVE MODE</option>
-        statements.
+        Acquired by <command>VACUUM</command> (without <option>FULL</option>).
        </para>
 
        <para>
-        Conflicts with ShareUpdateExclusiveLock, ShareLock,
-        ShareRowExclusiveLock, ExclusiveLock and AccessExclusiveLock modes.
+        Conflicts with the <literal>SHARE UPDATE EXCLUSIVE</literal>,
+        <literal>SHARE</literal>, <literal>SHARE ROW
+        EXCLUSIVE</literal>, <literal>EXCLUSIVE</literal>, and
+        <literal>ACCESS EXCLUSIVE</literal> lock modes.
        </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>
-       ShareLock
+       <literal>SHARE</literal>
        </term>
        <listitem>
        <para>
-        Acquired by <command>CREATE INDEX</command>
-        and <command>LOCK TABLE</command>
-        <option>IN SHARE MODE</option>
-        statements.
+        Acquired by <command>CREATE INDEX</command>.
        </para>
 
        <para>
-        Conflicts with RowExclusiveLock, ShareUpdateExclusiveLock,
-        ShareRowExclusiveLock,
-        ExclusiveLock and AccessExclusiveLock modes.
+        Conflicts with the <literal>ROW EXCLUSIVE</literal>,
+        <literal>SHARE UPDATE EXCLUSIVE</literal>, <literal>SHARE ROW
+        EXCLUSIVE</literal>, <literal>EXCLUSIVE</literal>, and
+        <literal>ACCESS EXCLUSIVE</literal> lock modes.
        </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>
-       ShareRowExclusiveLock
+       <literal>SHARE ROW EXCLUSIVE</literal>
        </term>
        <listitem>
        <para>
-        Acquired by <command>LOCK TABLE</command>
-        <option>IN SHARE ROW EXCLUSIVE MODE</option> statements.
+         This lock mode is not automatically acquired by any command.
        </para>
 
        <para>
-        Conflicts with RowExclusiveLock, ShareUpdateExclusiveLock,
-        ShareLock, ShareRowExclusiveLock,
-        ExclusiveLock and AccessExclusiveLock modes.
+        Conflicts with the <literal>ROW EXCLUSIVE</literal>,
+        <literal>SHARE UPDATE EXCLUSIVE</literal>,
+        <literal>SHARE</literal>, <literal>SHARE ROW
+        EXCLUSIVE</literal>, <literal>EXCLUSIVE</literal>, and
+        <literal>ACCESS EXCLUSIVE</literal> lock modes.
        </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>
-       ExclusiveLock
+       <literal>EXCLUSIVE LOCK</literal>
        </term>
        <listitem>
        <para>
-        Acquired by <command>LOCK TABLE</command>
-        <option>IN EXCLUSIVE MODE</option> statements.
+         This lock mode is not automatically acquired by any command.
        </para>
 
        <para>
-        Conflicts with RowShareLock, RowExclusiveLock,
-        ShareUpdateExclusiveLock, ShareLock,
-        ShareRowExclusiveLock, ExclusiveLock and AccessExclusiveLock
-        modes.
+        Conflicts with the <literal>ROW SHARE</literal>, <literal>ROW
+        EXCLUSIVE</literal>, <literal>SHARE UPDATE
+        EXCLUSIVE</literal>, <literal>SHARE</literal>, <literal>SHARE
+        ROW EXCLUSIVE</literal>, <literal>EXCLUSIVE</literal>, and
+        <literal>ACCESS EXCLUSIVE</literal> lock modes.
        </para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
        <term>
-       AccessExclusiveLock
+       <literal>ACCESS EXCLUSIVE</literal>
        </term>
        <listitem>
        <para>
-        Acquired by <command>ALTER TABLE</command>,
-        <command>DROP TABLE</command>,
-        <command>VACUUM FULL</command> and <command>LOCK TABLE</command>
-        <option>IN ACCESS EXCLUSIVE MODE</option> (or plain
-        <command>LOCK TABLE</command>) statements.
+        Acquired by the <command>ALTER TABLE</command>, <command>DROP
+        TABLE</command>, and <command>VACUUM FULL</command> commands.
+        This is also the default lock mode for <command>LOCK TABLE</command>
+         statements that do not specify a mode explicitly.
        </para>
 
        <para>
-        Conflicts with all modes (AccessShareLock, RowShareLock,
-        RowExclusiveLock, ShareUpdateExclusiveLock, ShareLock,
-        ShareRowExclusiveLock, ExclusiveLock and AccessExclusiveLock).
+        Conflicts with locks of all modes ( <literal>ACCESS
+        SHARE</literal>, <literal>ROW SHARE</literal>, <literal>ROW
+        EXCLUSIVE</literal>, <literal>SHARE UPDATE
+        EXCLUSIVE</literal>, <literal>SHARE</literal>, <literal>SHARE
+        ROW EXCLUSIVE</literal>, <literal>EXCLUSIVE</literal>, and
+        <literal>ACCESS EXCLUSIVE</literal>).
        </para>
        </listitem>
       </varlistentry>
@@ -542,30 +548,27 @@ ERROR:  Can't serialize access due to concurrent update
 
      <note>
       <para>
-       Only AccessExclusiveLock blocks <command>SELECT</command> (without
-       <option>FOR UPDATE</option>) statement.
+       Only an <literal>ACCESS EXCLUSIVE</literal> lock blocks a
+       <command>SELECT</command> (without <option>FOR UPDATE</option>)
+       statement.
       </para>
      </note>
-    </para>
-   </sect2>
-
-   <sect2>
-    <title>Row-level locks</title>
 
     <para>
-     Row-level locks are acquired when rows are being updated (or deleted or
-     marked for update).
-     Row-level locks don't affect data querying. They block
-     writers to <emphasis>the same row</emphasis> only.
+     In addition to table-level locks, there are row-level locks.
+     Row-level locks are acquired when rows are being updated (or
+     deleted or marked for update).  Row-level locks don't affect data
+     querying; they block writers to <emphasis>the same row</emphasis>
+     only.  Row-level locks cannot be acquired explicitly by the user.
     </para>
 
     <para>
-     <productname>PostgreSQL</productname>
-     doesn't remember any information about modified rows in memory and
-     so has no limit to the number of rows locked at one time.  However,
-     locking a row may cause a disk write; thus, for example,
-     <command>SELECT FOR UPDATE</command> will modify
-     selected rows to mark them and so will result in disk writes.
+     <productname>PostgreSQL</productname> doesn't remember any
+     information about modified rows in memory, so is has no limit to
+     the number of rows locked at one time.  However, locking a row
+     may cause a disk write; thus, for example, <command>SELECT FOR
+     UPDATE</command> will modify selected rows to mark them and so
+     will result in disk writes.
     </para>
 
     <para>
@@ -575,7 +578,6 @@ ERROR:  Can't serialize access due to concurrent update
     updated.  Application writers normally need not be concerned with
     page-level locks, but we mention them for completeness.
    </para>
-   </sect2>
   </sect1>
 
   <sect1 id="locking-indexes">