You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@zookeeper.apache.org by ma...@apache.org on 2011/12/08 23:15:07 UTC
svn commit: r1212166 - in /zookeeper/trunk: ./ docs/
src/docs/src/documentation/content/xdocs/
Author: mahadev
Date: Thu Dec 8 22:15:06 2011
New Revision: 1212166
URL: http://svn.apache.org/viewvc?rev=1212166&view=rev
Log:
ZOOKEEPER-1262. Documentation for Lock recipe has major flaw. (Jordan Zimmerman via mahadev)
Modified:
zookeeper/trunk/CHANGES.txt
zookeeper/trunk/docs/bookkeeperConfig.pdf
zookeeper/trunk/docs/bookkeeperOverview.pdf
zookeeper/trunk/docs/bookkeeperProgrammer.pdf
zookeeper/trunk/docs/bookkeeperStarted.pdf
zookeeper/trunk/docs/bookkeeperStream.pdf
zookeeper/trunk/docs/index.pdf
zookeeper/trunk/docs/javaExample.pdf
zookeeper/trunk/docs/linkmap.pdf
zookeeper/trunk/docs/recipes.html
zookeeper/trunk/docs/recipes.pdf
zookeeper/trunk/docs/releasenotes.pdf
zookeeper/trunk/docs/zookeeperAdmin.html
zookeeper/trunk/docs/zookeeperAdmin.pdf
zookeeper/trunk/docs/zookeeperHierarchicalQuorums.pdf
zookeeper/trunk/docs/zookeeperInternals.pdf
zookeeper/trunk/docs/zookeeperJMX.pdf
zookeeper/trunk/docs/zookeeperObservers.pdf
zookeeper/trunk/docs/zookeeperOver.pdf
zookeeper/trunk/docs/zookeeperProgrammers.pdf
zookeeper/trunk/docs/zookeeperQuotas.pdf
zookeeper/trunk/docs/zookeeperStarted.pdf
zookeeper/trunk/docs/zookeeperTutorial.pdf
zookeeper/trunk/src/docs/src/documentation/content/xdocs/recipes.xml
Modified: zookeeper/trunk/CHANGES.txt
URL: http://svn.apache.org/viewvc/zookeeper/trunk/CHANGES.txt?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
--- zookeeper/trunk/CHANGES.txt (original)
+++ zookeeper/trunk/CHANGES.txt Thu Dec 8 22:15:06 2011
@@ -62,6 +62,9 @@ BUGFIXES:
ZOOKEEPER-1305. zookeeper.c:prepend_string func can dereference null ptr.
(Daniel Lescohier via mahadev)
+
+ ZOOKEEPER-1262. Documentation for Lock recipe has major flaw.
+ (Jordan Zimmerman via mahadev)
IMPROVEMENTS:
Modified: zookeeper/trunk/docs/bookkeeperConfig.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/bookkeeperConfig.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Files zookeeper/trunk/docs/bookkeeperConfig.pdf (original) and zookeeper/trunk/docs/bookkeeperConfig.pdf Thu Dec 8 22:15:06 2011 differ
Modified: zookeeper/trunk/docs/bookkeeperOverview.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/bookkeeperOverview.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Files zookeeper/trunk/docs/bookkeeperOverview.pdf (original) and zookeeper/trunk/docs/bookkeeperOverview.pdf Thu Dec 8 22:15:06 2011 differ
Modified: zookeeper/trunk/docs/bookkeeperProgrammer.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/bookkeeperProgrammer.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Files zookeeper/trunk/docs/bookkeeperProgrammer.pdf (original) and zookeeper/trunk/docs/bookkeeperProgrammer.pdf Thu Dec 8 22:15:06 2011 differ
Modified: zookeeper/trunk/docs/bookkeeperStarted.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/bookkeeperStarted.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Files zookeeper/trunk/docs/bookkeeperStarted.pdf (original) and zookeeper/trunk/docs/bookkeeperStarted.pdf Thu Dec 8 22:15:06 2011 differ
Modified: zookeeper/trunk/docs/bookkeeperStream.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/bookkeeperStream.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Files zookeeper/trunk/docs/bookkeeperStream.pdf (original) and zookeeper/trunk/docs/bookkeeperStream.pdf Thu Dec 8 22:15:06 2011 differ
Modified: zookeeper/trunk/docs/index.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/index.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/trunk/docs/javaExample.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/javaExample.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/trunk/docs/linkmap.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/linkmap.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/trunk/docs/recipes.html
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/recipes.html?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
--- zookeeper/trunk/docs/recipes.html (original)
+++ zookeeper/trunk/docs/recipes.html Thu Dec 8 22:15:06 2011
@@ -210,6 +210,9 @@ document.write("Last Published: " + docu
<a href="#ch_recipes">A Guide to Creating Higher-level Constructs with ZooKeeper</a>
<ul class="minitoc">
<li>
+<a href="#sc_recipes_errorHandlingNote">Important Note About Error Handling</a>
+</li>
+<li>
<a href="#sc_outOfTheBox">Out of the Box Applications: Name Service, Configuration, Group
Membership</a>
</li>
@@ -233,6 +236,9 @@ document.write("Last Published: " + docu
<a href="#sc_recipes_Locks">Locks</a>
<ul class="minitoc">
<li>
+<a href="#sc_recipes_GuidNote">Recoverable Errors and the GUID</a>
+</li>
+<li>
<a href="#Shared+Locks">Shared Locks</a>
</li>
<li>
@@ -281,6 +287,17 @@ document.write("Last Published: " + docu
as event handles or queues, a more practical means of performing the same
function. In general, the examples in this section are designed to
stimulate thought.</p>
+<a name="sc_recipes_errorHandlingNote"></a>
+<h3 class="h4">Important Note About Error Handling</h3>
+<p>When implementing the recipes you must handle recoverable exceptions
+ (see the <a href="http://wiki.apache.org/hadoop/ZooKeeper/FAQ">FAQ</a>). In
+ particular, several of the recipes employ sequential ephemeral
+ nodes. When creating a sequential ephemeral node there is an error case in
+ which the create() succeeds on the server but the server crashes before
+ returning the name of the node to the client. When the client reconnects its
+ session is still valid and, thus, the node is not removed. The implication is
+ that it is difficult for the client to know if its node was created or not. The
+ recipes below include measures to handle this.</p>
<a name="sc_outOfTheBox"></a>
<h3 class="h4">Out of the Box Applications: Name Service, Configuration, Group
Membership</h3>
@@ -454,7 +471,7 @@ document.write("Last Published: " + docu
<li>
<p>if <em>p</em> is the lowest process
- node in L, wait on highest process node in L</p>
+ node in L, wait on highest process node in P</p>
</li>
@@ -563,8 +580,9 @@ document.write("Last Published: " + docu
<li>
<p>Call <strong>create( )</strong> with a pathname
- of "_locknode_/lock-" and the <em>sequence</em> and
- <em>ephemeral</em> flags set.</p>
+ of "_locknode_/guid-lock-" and the <em>sequence</em> and
+ <em>ephemeral</em> flags set. The <em>guid</em>
+ is needed in case the create() result is missed. See the note below.</p>
</li>
@@ -639,6 +657,22 @@ document.write("Last Published: " + docu
</li>
</ul>
+<a name="sc_recipes_GuidNote"></a>
+<h4>Recoverable Errors and the GUID</h4>
+<ul>
+
+<li>
+
+<p>If a recoverable error occurs calling <strong>create()</strong> the
+ client should call <strong>getChildren()</strong> and check for a node
+ containing the <em>guid</em> used in the path name.
+ This handles the case (noted <a href="#sc_recipes_errorHandlingNote">above</a>) of
+ the create() succeeding on the server but the server crashing before returning the name
+ of the new node.</p>
+
+</li>
+
+</ul>
<a name="Shared+Locks"></a>
<h4>Shared Locks</h4>
<p>You can implement shared locks by with a few changes to the lock
@@ -666,7 +700,7 @@ document.write("Last Published: " + docu
<p>Call <strong>create( )</strong> to
create a node with pathname
- "<span class="codefrag filename">_locknode_/read-</span>". This is the
+ "<span class="codefrag filename">guid-/read-</span>". This is the
lock node use later in the protocol. Make sure to set both
the <em>sequence</em> and
<em>ephemeral</em> flags.</p>
@@ -731,7 +765,7 @@ document.write("Last Published: " + docu
<p>Call <strong>create( )</strong> to
create a node with pathname
- "<span class="codefrag filename">_locknode_/write-</span>". This is the
+ "<span class="codefrag filename">guid-/write-</span>". This is the
lock node spoken of later in the protocol. Make sure to
set both <em>sequence</em> and
<em>ephemeral</em> flags.</p>
@@ -784,9 +818,10 @@ document.write("Last Published: " + docu
</table>
-<div class="note">
-<div class="label">Note</div>
-<div class="content">
+<p>Notes:</p>
+<ul>
+
+<li>
<p>It might appear that this recipe creates a herd effect:
when there is a large group of clients waiting for a read
@@ -796,11 +831,20 @@ document.write("Last Published: " + docu
as all those waiting reader clients should be released since
they have the lock. The herd effect refers to releasing a
"herd" when in fact only a single or a small number of
- machines can proceed.
- </p>
+ machines can proceed.</p>
-</div>
-</div>
+</li>
+
+</ul>
+<ul>
+
+<li>
+
+<p>See the <a href="#sc_recipes_GuidNote">note for Locks</a> on how to use the guid in the node.</p>
+
+</li>
+
+</ul>
<a name="sc_recoverableSharedLocks"></a>
<h4>Recoverable Shared Locks</h4>
<p>With minor modifications to the Shared Lock protocol, you make
@@ -860,7 +904,7 @@ document.write("Last Published: " + docu
<p>A simple way of doing leader election with ZooKeeper is to use the
<strong>SEQUENCE|EPHEMERAL</strong> flags when creating
znodes that represent "proposals" of clients. The idea is to have a znode,
- say "/election", such that each znode creates a child znode "/election/n_"
+ say "/election", such that each znode creates a child znode "/election/guid-n_"
with both flags SEQUENCE|EPHEMERAL. With the sequence flag, ZooKeeper
automatically appends a sequence number that is greater that any one
previously appended to a child of "/election". The process that created
@@ -889,7 +933,7 @@ document.write("Last Published: " + docu
<li>
-<p>Create znode z with path "ELECTION/n_" with both SEQUENCE and
+<p>Create znode z with path "ELECTION/guid-n_" with both SEQUENCE and
EPHEMERAL flags;</p>
</li>
@@ -905,7 +949,7 @@ document.write("Last Published: " + docu
<li>
-<p>Watch for changes on "ELECTION/n_j", where j is the smallest
+<p>Watch for changes on "ELECTION/guid-n_j", where j is the smallest
sequence number such that j < i and n_j is a znode in C;</p>
</li>
@@ -931,17 +975,35 @@ document.write("Last Published: " + docu
<li>
-<p>Otherwise, watch for changes on "ELECTION/n_j", where j is the
+<p>Otherwise, watch for changes on "ELECTION/guid-n_j", where j is the
smallest sequence number such that j < i and n_j is a znode in C;
</p>
</li>
</ol>
+<p>Notes:</p>
+<ul>
+
+<li>
+
<p>Note that the znode having no preceding znode on the list of
- children does not imply that the creator of this znode is aware that it is
- the current leader. Applications may consider creating a separate to znode
- to acknowledge that the leader has executed the leader procedure. </p>
+ children does not imply that the creator of this znode is aware that it is
+ the current leader. Applications may consider creating a separate to znode
+ to acknowledge that the leader has executed the leader procedure. </p>
+
+</li>
+
+</ul>
+<ul>
+
+<li>
+
+<p>See the <a href="#sc_recipes_GuidNote">note for Locks</a> on how to use the guid in the node.</p>
+
+</li>
+
+</ul>
</div>
<p align="right">
Modified: zookeeper/trunk/docs/recipes.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/recipes.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/trunk/docs/releasenotes.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/releasenotes.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/trunk/docs/zookeeperAdmin.html
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/zookeeperAdmin.html?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
--- zookeeper/trunk/docs/zookeeperAdmin.html (original)
+++ zookeeper/trunk/docs/zookeeperAdmin.html Thu Dec 8 22:15:06 2011
@@ -291,6 +291,9 @@ document.write("Last Published: " + docu
<a href="#sc_authOptions">Authentication & Authorization Options</a>
</li>
<li>
+<a href="#Experimental+Options%2FFeatures">Experimental Options/Features</a>
+</li>
+<li>
<a href="#Unsafe+Options">Unsafe Options</a>
</li>
<li>
@@ -1155,6 +1158,21 @@ server.3=zoo3:2888:3888</pre>
the <strong>tickTime</strong>.</p>
</dd>
+
+<dt>
+<term>fsync.warningthresholdms</term>
+</dt>
+<dd>
+<p>(Java system property: <strong>fsync.warningthresholdms</strong>)</p>
+<p>
+<strong>New in 3.3.4:</strong> A
+ warning message will be output to the log whenever an
+ fsync in the Transactional Log (WAL) takes longer than
+ this value. The values is specified in milliseconds and
+ defaults to 1000. This value can only be set as a
+ system property.</p>
+</dd>
+
<dt>
<term>autopurge.snapRetainCount</term>
@@ -1372,6 +1390,31 @@ server.3=zoo3:2888:3888</pre>
</dd>
</dl>
+<a name="Experimental+Options%2FFeatures"></a>
+<h4>Experimental Options/Features</h4>
+<p>New features that are currently considered experimental.</p>
+<dl>
+
+<dt>
+<term>Read Only Mode Server</term>
+</dt>
+<dd>
+<p>(Java system property: <strong>readonlymode.enabled</strong>)</p>
+<p>
+<strong>New in 3.4.0:</strong>
+ Setting this value to true enables Read Only Mode server
+ support (disabled by default). ROM allows clients
+ sessions which requested ROM support to connect to the
+ server even when the server might be partitioned from
+ the quorum. In this mode ROM clients can still read
+ values from the ZK service, but will be unable to write
+ values and see changes from other clients. See
+ ZOOKEEPER-784 for more details.
+ </p>
+</dd>
+
+
+</dl>
<a name="Unsafe+Options"></a>
<h4>Unsafe Options</h4>
<p>The following options can be useful, but be careful when you use
Modified: zookeeper/trunk/docs/zookeeperAdmin.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/zookeeperAdmin.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/trunk/docs/zookeeperHierarchicalQuorums.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/zookeeperHierarchicalQuorums.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Files zookeeper/trunk/docs/zookeeperHierarchicalQuorums.pdf (original) and zookeeper/trunk/docs/zookeeperHierarchicalQuorums.pdf Thu Dec 8 22:15:06 2011 differ
Modified: zookeeper/trunk/docs/zookeeperInternals.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/zookeeperInternals.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/trunk/docs/zookeeperJMX.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/zookeeperJMX.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Files zookeeper/trunk/docs/zookeeperJMX.pdf (original) and zookeeper/trunk/docs/zookeeperJMX.pdf Thu Dec 8 22:15:06 2011 differ
Modified: zookeeper/trunk/docs/zookeeperObservers.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/zookeeperObservers.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Files zookeeper/trunk/docs/zookeeperObservers.pdf (original) and zookeeper/trunk/docs/zookeeperObservers.pdf Thu Dec 8 22:15:06 2011 differ
Modified: zookeeper/trunk/docs/zookeeperOver.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/zookeeperOver.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/trunk/docs/zookeeperProgrammers.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/zookeeperProgrammers.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/trunk/docs/zookeeperQuotas.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/zookeeperQuotas.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Files zookeeper/trunk/docs/zookeeperQuotas.pdf (original) and zookeeper/trunk/docs/zookeeperQuotas.pdf Thu Dec 8 22:15:06 2011 differ
Modified: zookeeper/trunk/docs/zookeeperStarted.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/zookeeperStarted.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/trunk/docs/zookeeperTutorial.pdf
URL: http://svn.apache.org/viewvc/zookeeper/trunk/docs/zookeeperTutorial.pdf?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
Binary files - no diff available.
Modified: zookeeper/trunk/src/docs/src/documentation/content/xdocs/recipes.xml
URL: http://svn.apache.org/viewvc/zookeeper/trunk/src/docs/src/documentation/content/xdocs/recipes.xml?rev=1212166&r1=1212165&r2=1212166&view=diff
==============================================================================
--- zookeeper/trunk/src/docs/src/documentation/content/xdocs/recipes.xml (original)
+++ zookeeper/trunk/src/docs/src/documentation/content/xdocs/recipes.xml Thu Dec 8 22:15:06 2011
@@ -72,6 +72,19 @@
function. In general, the examples in this section are designed to
stimulate thought.</para>
+ <section id="sc_recipes_errorHandlingNote">
+ <title>Important Note About Error Handling</title>
+
+ <para>When implementing the recipes you must handle recoverable exceptions
+ (see the <ulink url="http://wiki.apache.org/hadoop/ZooKeeper/FAQ">FAQ</ulink>). In
+ particular, several of the recipes employ sequential ephemeral
+ nodes. When creating a sequential ephemeral node there is an error case in
+ which the create() succeeds on the server but the server crashes before
+ returning the name of the node to the client. When the client reconnects its
+ session is still valid and, thus, the node is not removed. The implication is
+ that it is difficult for the client to know if its node was created or not. The
+ recipes below include measures to handle this.</para>
+ </section>
<section id="sc_outOfTheBox">
<title>Out of the Box Applications: Name Service, Configuration, Group
@@ -203,7 +216,7 @@
<listitem>
<para>if <emphasis>p</emphasis> is the lowest process
- node in L, wait on highest process node in L</para>
+ node in L, wait on highest process node in P</para>
</listitem>
<listitem>
@@ -308,8 +321,9 @@
<orderedlist>
<listitem>
<para>Call <emphasis role="bold">create( )</emphasis> with a pathname
- of "_locknode_/lock-" and the <emphasis>sequence</emphasis> and
- <emphasis>ephemeral</emphasis> flags set.</para>
+ of "_locknode_/guid-lock-" and the <emphasis>sequence</emphasis> and
+ <emphasis>ephemeral</emphasis> flags set. The <emphasis>guid</emphasis>
+ is needed in case the create() result is missed. See the note below.</para>
</listitem>
<listitem>
@@ -365,6 +379,20 @@
</listitem>
</itemizedlist>
+ <section id="sc_recipes_GuidNote">
+ <title>Recoverable Errors and the GUID</title>
+ <itemizedlist>
+ <listitem>
+ <para>If a recoverable error occurs calling <emphasis role="bold">create()</emphasis> the
+ client should call <emphasis role="bold">getChildren()</emphasis> and check for a node
+ containing the <emphasis>guid</emphasis> used in the path name.
+ This handles the case (noted <ulink url="#sc_recipes_errorHandlingNote">above</ulink>) of
+ the create() succeeding on the server but the server crashing before returning the name
+ of the new node.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
<section>
<title>Shared Locks</title>
@@ -387,7 +415,7 @@
<listitem>
<para>Call <emphasis role="bold">create( )</emphasis> to
create a node with pathname
- "<filename>_locknode_/read-</filename>". This is the
+ "<filename>guid-/read-</filename>". This is the
lock node use later in the protocol. Make sure to set both
the <emphasis>sequence</emphasis> and
<emphasis>ephemeral</emphasis> flags.</para>
@@ -433,7 +461,7 @@
<listitem>
<para>Call <emphasis role="bold">create( )</emphasis> to
create a node with pathname
- "<filename>_locknode_/write-</filename>". This is the
+ "<filename>guid-/write-</filename>". This is the
lock node spoken of later in the protocol. Make sure to
set both <emphasis>sequence</emphasis> and
<emphasis>ephemeral</emphasis> flags.</para>
@@ -474,7 +502,10 @@
</tgroup>
</informaltable>
- <note>
+ <para>Notes:</para>
+
+ <itemizedlist>
+ <listitem>
<para>It might appear that this recipe creates a herd effect:
when there is a large group of clients waiting for a read
lock, and all getting notified more or less simultaneously
@@ -483,10 +514,17 @@
as all those waiting reader clients should be released since
they have the lock. The herd effect refers to releasing a
"herd" when in fact only a single or a small number of
- machines can proceed.
- </para>
- </note>
- </section>
+ machines can proceed.</para>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>See the <ulink url="#sc_recipes_GuidNote">note for Locks</ulink> on how to use the guid in the node.</para>
+ </listitem>
+ </itemizedlist>
+
+ </section>
<section id="sc_recoverableSharedLocks">
<title>Recoverable Shared Locks</title>
@@ -563,7 +601,7 @@
<para>A simple way of doing leader election with ZooKeeper is to use the
<emphasis role="bold">SEQUENCE|EPHEMERAL</emphasis> flags when creating
znodes that represent "proposals" of clients. The idea is to have a znode,
- say "/election", such that each znode creates a child znode "/election/n_"
+ say "/election", such that each znode creates a child znode "/election/guid-n_"
with both flags SEQUENCE|EPHEMERAL. With the sequence flag, ZooKeeper
automatically appends a sequence number that is greater that any one
previously appended to a child of "/election". The process that created
@@ -594,7 +632,7 @@
<orderedlist>
<listitem>
- <para>Create znode z with path "ELECTION/n_" with both SEQUENCE and
+ <para>Create znode z with path "ELECTION/guid-n_" with both SEQUENCE and
EPHEMERAL flags;</para>
</listitem>
@@ -604,7 +642,7 @@
</listitem>
<listitem>
- <para>Watch for changes on "ELECTION/n_j", where j is the smallest
+ <para>Watch for changes on "ELECTION/guid-n_j", where j is the smallest
sequence number such that j < i and n_j is a znode in C;</para>
</listitem>
</orderedlist>
@@ -622,16 +660,29 @@
</listitem>
<listitem>
- <para>Otherwise, watch for changes on "ELECTION/n_j", where j is the
+ <para>Otherwise, watch for changes on "ELECTION/guid-n_j", where j is the
smallest sequence number such that j < i and n_j is a znode in C;
</para>
</listitem>
</orderedlist>
- <para>Note that the znode having no preceding znode on the list of
- children does not imply that the creator of this znode is aware that it is
- the current leader. Applications may consider creating a separate to znode
- to acknowledge that the leader has executed the leader procedure. </para>
+ <para>Notes:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Note that the znode having no preceding znode on the list of
+ children does not imply that the creator of this znode is aware that it is
+ the current leader. Applications may consider creating a separate to znode
+ to acknowledge that the leader has executed the leader procedure. </para>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>See the <ulink url="#sc_recipes_GuidNote">note for Locks</ulink> on how to use the guid in the node.</para>
+ </listitem>
+ </itemizedlist>
+
</section>
</section>
</article>