Log Message:
-----------
Improve discussion of locking

Modified Files:
--------------
    slony1-engine/doc/adminguide:
        defineset.sgml (r1.21 -> r1.22)
        locking.sgml (r1.6 -> r1.7)

-------------- next part --------------
Index: defineset.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/defineset.sgml,v
retrieving revision 1.21
retrieving revision 1.22
diff -Ldoc/adminguide/defineset.sgml -Ldoc/adminguide/defineset.sgml -u -w -r1.21 -r1.22
--- doc/adminguide/defineset.sgml
+++ doc/adminguide/defineset.sgml
@@ -52,7 +52,8 @@
 <listitem><para> If the table hasn't even got a candidate primary key,
 you can ask &slony1; to provide one.  This is done by first using
 <xref linkend="stmttableaddkey"> to add a column populated using a
-&slony1; sequence, and then having the <xref linkend="stmtsetaddtable"> include the directive
+&slony1; sequence, and then having the <xref
+linkend="stmtsetaddtable"> include the directive
 <option>key=serial</option>, to indicate that &slony1;'s own column
 should be used.</para></listitem>
 
@@ -93,17 +94,20 @@
 
 <para> If you can split such a large set into several smaller pieces,
 that will shorten the length of each of the transactions, lessening
-the degree of <quote>injury</quote> to performance.</para>
+the degree of the <quote>injury</quote> to performance.</para>
 
 <para> These <quote>negative effects</quote> tend to emerge when the
-database being subscribed to is tens of gigabytes in size.  For
-relatively small databases, this shouldn't be a material factor.
+database being subscribed to is many gigabytes in size and where it
+takes many hours or even days for the subscriber to complete the
+initial data copy.  For relatively small databases, this shouldn't be
+a material factor.
 </para>
 </listitem>
 
 <listitem><para> Any time you invoke <xref linkend="stmtddlscript">,
 this requests a lock on <emphasis> every single table in the
-replication set. </emphasis></para>
+replication set, first, on the origin node, and then, as the event
+propagates to other nodes, to each subscriber node. </emphasis></para>
 
 <para> There have been reports <quote>in the field</quote> of this
 leading to deadlocks such that the <xref linkend="stmtddlscript">
@@ -118,6 +122,10 @@
 linkend="stmtsetmovetable"> to move them temporarily to a new
 replication set.  By diminishing the number of locks needed, this
 should ease the ability to get the DDL change into place.</para>
+
+<para> There is a further <link linkend="locking"> discussion of
+locking </link> which outlines where &slony1; requires locks likely to
+intrude on your applications.</para>
 </listitem>
 
 </itemizedlist></para>
Index: locking.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/locking.sgml,v
retrieving revision 1.6
retrieving revision 1.7
diff -Ldoc/adminguide/locking.sgml -Ldoc/adminguide/locking.sgml -u -w -r1.6 -r1.7
--- doc/adminguide/locking.sgml
+++ doc/adminguide/locking.sgml
@@ -25,7 +25,7 @@
 <listitem><para><link linkend="stmtsetaddtable"> <command>set add
 table</command> </link></para>
 
-<para> A momentary table lock must be acquired on the
+<para> A momentary exclusive table lock must be acquired on the
 <quote>origin</quote> node in order to add the trigger that collects
 updates for that table.  It only needs to be acquired long enough to
 establish the new trigger.</para>
@@ -34,10 +34,10 @@
 <listitem><para><link linkend="stmtmoveset"> <command> move
 set</command> </link></para>
 
-<para> When a set origin is shifted from one node to another, locks
-must be acquired on each of the tables on both the old origin and the
-new origin in order to change the triggers on the tables.
-</para></listitem>
+<para> When a set origin is shifted from one node to another,
+exclusive locks must be acquired on each replicated table on both the
+old origin and the new origin in order to change the triggers on the
+tables.  </para></listitem>
 
 <listitem><para><link linkend="stmtlockset"> <command> lock set
 </command> </link> </para>
@@ -56,13 +56,22 @@
 all replicated tables on each node. </para>
 </listitem>
 
-<listitem><para> During the <command>COPY_SET</command> event on a new
-subscriber </para>
+<listitem><para> During the <command>SUBSCRIBE_SET</command> event on
+a new subscriber </para>
 
 <para> In a sense, this is the least provocative scenario, since,
 before the replication set has been populated, it is pretty reasonable
 to say that the node is <quote>unusable</quote> and that &slony1;
 could reasonably demand exclusive access to the node. </para>
+
+<para> A change in version 1.2 is that an express <command>LOCK
+TABLE</command> SQL request is submitted in the loop that validates
+that all of the tables are there.  This means that
+<emphasis>all</emphasis> tables in the replication set will be locked
+via an exclusive lock for the entire duration of the process of
+subscription.  By locking the tables early, this means that the
+subscription cannot fail after copying some of the data due to some
+other process having held on to a table. </para>
 </listitem>
 
 </itemizedlist>