Log Message:
-----------
Add in documentation for SYNC slonik command, as well as several examples
including one of its use to prevent MERGE SET problems

Modified Files:
--------------
    slony1-engine/doc/adminguide:
        addthings.sgml (r1.23 -> r1.24)
        slonik_ref.sgml (r1.62 -> r1.63)

-------------- next part --------------
Index: addthings.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/addthings.sgml,v
retrieving revision 1.23
retrieving revision 1.24
diff -Ldoc/adminguide/addthings.sgml -Ldoc/adminguide/addthings.sgml -u -w -r1.23 -r1.24
--- doc/adminguide/addthings.sgml
+++ doc/adminguide/addthings.sgml
@@ -88,12 +88,30 @@
 <listitem><para> 
 Add the table to the new set <xref linkend="stmtsetaddtable"> 
 </para></listitem>
-<listitem><para> 
-Request subscription <xref linkend="stmtsubscribeset"> for this new set. If there are several nodes, you will need to <xref linkend="stmtsubscribeset"> once for each node that should subscribe.
-</para></listitem>
-<listitem><para> 
-Once the subscriptions have all been set up so that the new set has an identical set of subscriptions to the old set, you can merge the new set in alongside the old one via <xref linkend="stmtmergeset">
-</para></listitem>
+
+<listitem><para> Request subscription <xref
+linkend="stmtsubscribeset"> for this new set. If there are several
+nodes, you will need to <xref linkend="stmtsubscribeset"> once for
+each node that should subscribe.  </para></listitem>
+
+<listitem><para> If you wish to know, deterministically, that each
+subscription has completed, you'll need to submit the following sort
+of slonik script for each subscription:
+
+<screen>
+SUBSCRIBE SET (ID=1, PROVIDER=1, RECEIVER=2);
+WAIT FOR EVENT (ORIGIN=2, CONFIRMED = 1);
+SYNC(ID = 1);
+WAIT FOR EVENT (ORIGIN=1, CONFIRMED=2);
+</screen></para>
+</listitem>
+
+<listitem><para> Once the subscriptions have all been set up so that
+the new set has an identical set of subscriptions to the old set, you
+can merge the new set in alongside the old one via <xref
+linkend="stmtmergeset"> If you submit the request too soon, there is
+the risk that the subscription won't actually be complete on all
+nodes, and some subscribers may break down.  </para></listitem>
 </itemizedlist>
 </sect2>
 
@@ -104,9 +122,15 @@
 to the effect of <quote>How do I modify the definitions of replicated
 tables?</quote></para>
 
-<para>If you change the <quote>shape</quote> of a replicated table, this needs to take place at exactly the same point in all of the <quote>transaction streams</quote> on all nodes that are subscribed to the set containing the table.</para>
-
-<para> Thus, the way to do this is to construct an SQL script consisting of the DDL changes, and then submit that script to all of the nodes via the Slonik command <xref linkend="stmtddlscript">.</para>
+<para>If you change the <quote>shape</quote> of a replicated table,
+this needs to take place at exactly the same point in all of the
+<quote>transaction streams</quote> on all nodes that are subscribed to
+the set containing the table.</para>
+
+<para> Thus, the way to do this is to construct an SQL script
+consisting of the DDL changes, and then submit that script to all of
+the nodes via the Slonik command <xref
+linkend="stmtddlscript">.</para>
 
 <para> There are a number of <quote>sharp edges</quote> to note...</para>
 
Index: slonik_ref.sgml
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/adminguide/slonik_ref.sgml,v
retrieving revision 1.62
retrieving revision 1.63
diff -Ldoc/adminguide/slonik_ref.sgml -Ldoc/adminguide/slonik_ref.sgml -u -w -r1.62 -r1.63
--- doc/adminguide/slonik_ref.sgml
+++ doc/adminguide/slonik_ref.sgml
@@ -1257,9 +1257,14 @@
    </refsect1>
    <refsect1><title>Example</title>
     <programlisting>
-     MERGE SET ( ID = 2, 
-     ADD ID = 9999,
-     ORIGIN = 1 );
+     # Assuming that set 1 has direct subscribers 2 and 3
+     SUBSCRIBE SET (ID = 999, PROVIDER = 1, RECEIVER = 2);
+     WAIT FOR EVENT (ORIGIN = 2, CONFIRMED = 1);
+     SYNC (ID=1);
+     SUBSCRIBE SET (ID = 999, PROVIDER = 1, RECEIVER = 3);
+     WAIT FOR EVENT (ORIGIN = 3, CONFIRMED = 1);
+     SYNC (ID=1);
+     MERGE SET ( ID = 2, ADD ID = 9999, ORIGIN = 1 );
     </programlisting>
    </refsect1>
    <refsect1> <title> Locking Behaviour </title>
@@ -2070,7 +2075,19 @@
 
      <listitem><para> The fact that the request returns immediately
      even though the subscription may take considerable time to
-     complete may be a bit surprising. </para> </listitem>
+     complete may be a bit surprising. </para> 
+
+     <para> Processing of the subscription involves
+     <emphasis>two</emphasis> events; the
+     <command>SUBSCRIBE_SET</command>, initiated from the provider
+     node, and an <command>ENABLE_SUBSCRIPTION</command>, which is
+     initiated on the subscriber node.  This means that <xref
+     linkend="stmtwaitevent"> cannot directly wait for completion of a
+     subscription.  If you need to wait for completion of a
+     subscription, then what you need to do instead is to submit a
+     <xref linkend="stmtsync"> request, and wait for
+     <emphasis>that</emphasis> event.</para>
+     </listitem>
 
      <listitem><para> This command has <emphasis>two</emphasis>
      purposes; setting up subscriptions (which should be unsurprising)
@@ -2078,7 +2095,7 @@
      obvious to intuition. </para> </listitem>
 
      <listitem><para> New subscriptions are set up by using
-     <command>DELETE</command> or <command>TRUNCATE</emphasis> to
+     <command>DELETE</command> or <command>TRUNCATE</command> to
      empty the table on a subscriber.  If you created a new node by
      copying data from an existing node, it might <quote>seem
      intuitive</quote> that that data should be kept; that is not the
@@ -2822,6 +2839,48 @@
     <para> This command was introduced in &slony1; 1.1 </para>
    </refsect1>
   </refentry>
+<!-- **************************************** -->
+
+  <refentry id="stmtsync"><refmeta><refentrytitle>SYNC</refentrytitle>
+   <manvolnum>7</manvolnum></refmeta>
+
+   <refnamediv><refname>SYNC</refname>
+    
+    <refpurpose> Generate an ordinary SYNC event </refpurpose></refnamediv>
+   <refsynopsisdiv>
+    <cmdsynopsis>
+     <command>SYNC (options);</command>
+    </cmdsynopsis>
+   </refsynopsisdiv>
+   <refsect1>
+    <title>Description</title>
+    
+    <para> Generates a SYNC event on a specified node.</para>
+    
+     <variablelist>
+      <varlistentry><term><literal> ID = ival </literal></term>
+       <listitem><para> The node on which to generate the SYNC event.</para></listitem>
+       
+      </varlistentry>
+     </variablelist>
+
+   </refsect1>
+   <refsect1><title>Example</title>
+    <programlisting>
+     SUBSCRIBE SET (ID = 10, PROVIDER = 1, RECEIVER = 2);
+     WAIT FOR EVENT (ORIGIN = 2, CONFIRMED = 1);
+     SYNC (ID = 1);
+     WAIT FOR EVENT (ORIGIN = 1, CONFIRMED = 2);
+    </programlisting>
+   </refsect1>
+   <refsect1> <title> Locking Behaviour </title>
+
+    <para> No application-visible locking should take place. </para>
+   </refsect1>
+   <refsect1> <title> Version Information </title>
+    <para> This command was introduced in &slony1; 1.1.6 / 1.2.1 </para>
+   </refsect1>
+  </refentry>
 
 
  </reference>