Adjust the description of locking to clarify that locks held by a

subtransaction are released if the subtransaction aborts --- in user-level
terminology, this means either rolling back to a savepoint or escaping from
a plpgsql exception block.  Per recent suggestion from Simon.

diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 21865d36d4be58f1d6ba2db3e15584711593d9d3..8f6984a7e9941f57aa16a829ffcd51d290004544 100644 (file)
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   Concurrency Control
@@ -504,16 +504,17 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
     most PostgreSQL commands automatically
     acquire locks of appropriate modes to ensure that referenced
     tables are not dropped or modified in incompatible ways while the
-    command executes.  (For example, ALTER TABLE cannot be
-    executed concurrently with other operations on the same table.)
+    command executes.  (For example, ALTER TABLE cannot safely be
+    executed concurrently with other operations on the same table, so it
+    obtains an exclusive lock on the table to enforce that.)
    
 
    
     To examine a list of the currently outstanding locks in a database
-    server, use the pg_locks system view
-    (). For more
-    information on monitoring the status of the lock manager
-    subsystem, refer to .
+    server, use the
+    pg_locks
+    system view. For more information on monitoring the status of the lock
+    manager subsystem, refer to .
    
 
   
@@ -545,7 +546,6 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
     an ACCESS EXCLUSIVE lock cannot be held by more than one
     transaction at a time) while others are not self-conflicting (for example,
     an ACCESS SHARE lock can be held by multiple transactions).
-    Once acquired, a lock is held till end of transaction.
    
 
      
@@ -731,6 +731,16 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
       
      
 
+   
+    Once acquired, a lock is normally held till end of transaction.  But if a
+    lock is acquired after establishing a savepoint, the lock is released
+    immediately if the savepoint is rolled back to.  This is consistent with
+    the principle that ROLLBACK cancels all effects of the
+    commands since the savepoint.  The same holds for locks acquired within a
+    PL/pgSQL exception block: an error escape from the block
+    releases locks acquired within it.
+   
+
    
 
    
@@ -741,8 +751,9 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
      can be exclusive or shared locks.  An exclusive row-level lock on a
      specific row is automatically acquired when the row is updated or
      deleted.  The lock is held until the transaction commits or rolls
-     back.  Row-level locks do not affect data querying; they block
-     writers to the same row only.
+     back, in just the same way as for table-level locks.  Row-level locks do
+     not affect data querying; they block writers to the same
+     row only.
     
 
     
@@ -759,7 +770,7 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
      other transactions from acquiring the same shared lock.  However,
      no transaction is allowed to update, delete, or exclusively lock a
      row on which any other transaction holds a shared lock.  Any attempt
-     to do so will block until the shared locks have been released.
+     to do so will block until the shared lock(s) have been released.
     
 
     
@@ -882,10 +893,11 @@ UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222;
      that are an awkward fit for the MVCC model.  Once acquired, an
      advisory lock is held until explicitly released or the session ends.
      Unlike standard locks, advisory locks do not
-     honor transaction semantics.  For example, a lock acquired during a
+     honor transaction semantics: a lock acquired during a
      transaction that is later rolled back will still be held following the
-     rollback.  The same lock can be acquired multiple times by its
-     owning process: for each lock request there must be a corresponding
+     rollback, and likewise an unlock is effective even if the calling
+     transaction fails later.  The same lock can be acquired multiple times by
+     its owning process: for each lock request there must be a corresponding
      unlock request before the lock is actually released.  (If a session
      already holds a given lock, additional requests will always succeed, even
      if other sessions are awaiting the lock.)  Like all locks in