You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@zookeeper.apache.org by ph...@apache.org on 2008/10/22 03:22:07 UTC
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/
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>