hadoop-zookeeper-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ph...@apache.org
Subject svn commit: r706834 [2/2] - in /hadoop/zookeeper/trunk: ./ docs/ src/c/ src/c/include/ src/c/src/ src/c/tests/ src/docs/src/documentation/content/xdocs/
Date Wed, 22 Oct 2008 01:22:07 GMT
Modified: hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/releasenotes.xml
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/releasenotes.xml?rev=706834&r1=706833&r2=706834&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/releasenotes.xml (original)
+++ hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/releasenotes.xml Tue Oct
21 18:22:06 2008
@@ -68,6 +68,26 @@
 <title>Migrating Client Code</title>
 
 <section>
+<title>Watch Management</title>
+
+<para>
+In previous releases of ZooKeeper any watches registered by clients were lost if the client
lost a connection to a ZooKeeper server.
+This meant that developers had to track watches they were interested in and reregister them
if a session disconnect event was recieved.
+In this release the client library tracks watches that a client has registered and reregisters
the watches when a connection is made to a new server.
+Applications that still manually reregister interest should continue working properly as
long as they are able to handle unsolicited watches.
+For example, an old application may register a watch for /foo and /goo, lose the connection,
and reregister only /goo.
+As long as the application is able to recieve a notification for /foo, (probably ignoring
it) the applications does not to be changes.
+One caveat to the watch management: it is possible to miss an event for the creation and
deletion of a znode if watching for creation and both the create and delete happens while
the client is disconnected from ZooKeeper.
+</para>
+
+<para>
+This release also allows clients to specify call specific watch functions.
+This gives the developer the ability to modularize logic in different watch functions rather
than cramming everything in the watch function attached to the ZooKeeper handle.
+Call specific watch functions receive all session events for as long as they are active,
but will only receive the watch callbacks for which they are registered.
+</para>
+</section>
+
+<section>
 <title>Java API</title>
 
 <orderedlist>

Modified: hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml?rev=706834&r1=706833&r2=706834&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml
(original)
+++ hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml
Tue Oct 21 18:22:06 2008
@@ -433,11 +433,13 @@
 
     <para>Watches are maintained locally at the ZooKeeper server to which the
     client is connected. This allows watches to be light weight to set,
-    maintain, and dispatch. It also means if a client connects to a different
-    server, the new server is not going to know about its watches. So, when a
-    client gets a disconnect event, it must consider that an implicit trigger
-    of all watches. When a client reconnects to a new server, the client
-    should re-set any watches that it is still interested in.</para>
+    maintain, and dispatch. When a client connects to a new server, the watch
+    will be triggered for any session events. Watches will not be received
+    while disconnected from a server. When a client reconnects, any previously
+    registered watches will be reregistered and triggered if needed. In
+    general this all occurs transparently. There is one case where a watch
+    may be missed: a watch for the existance of a znode not yet created will
+    be missed if the znode is created and deleted while disconnected.</para>
 
     <section id="sc_WatchGuarantees">
       <title>What ZooKeeper Guarantees about Watches</title>
@@ -493,10 +495,23 @@
 
       <itemizedlist>
         <listitem>
+          <para>A watch object, or function/context pair, will only be
+          triggered once for a given notification. For example, if the same
+          watch object is registered for an exists and a getData call for the
+          same file and that file is then deleted, the watch object would
+          only be invoked once with the deletion notification for the file.
+          </para>
+        </listitem>
+      </itemizedlist>
+
+      <itemizedlist>
+        <listitem>
           <para>When you disconnect from a server (for example, when the
-          server fails), all of the watches you have registered are lost, so
-          you should treat this case as if all your watches were
-          triggered.</para>
+          server fails), you will not get any watches until the connection
+          is reestablished. For this reason session events are sent to all
+          outstanding watch handlers. Use session events to go into a safe
+          mode: you will not be receiving events while disconnected, so your
+          process should act conservatively in that mode.</para>
         </listitem>
       </itemizedlist>
     </section>
@@ -1080,13 +1095,10 @@
     <orderedlist>
       <listitem>
         <para>If you are using watches, you must look for the connected watch
-        event. When a ZooKeeper client disconnects from a server, all the
-        watches are removed, so a client must treat the disconnect event as an
-        implicit trigger of watches. The easiest way to deal with this is to
-        act like the connected watch event is a watch trigger for all your
-        watches. The connected event makes a better trigger than the
-        disconnected event because you can access ZooKeeper and reestablish
-        watches when you are connected.</para>
+        event. When a ZooKeeper client disconnects from a server, you will
+        not receive notification of changes until reconnected. If you are
+        watching for a znode to come into existance, you will miss the event
+        if the znode is created and deleted while you are disconnected.</para>
       </listitem>
 
       <listitem>



Mime
View raw message