zk 0.8.9 → 0.9.0

data/.dotfiles/rvmrc

@@ -1 +1 @@
-rvm jruby-1.6.7@zk --create
+rvm 1.9.3@zk --create

data/.yardopts

@@ -2,6 +2,7 @@
 --no-private
 --tag hidden_example:Hidden
 --hide-tag hidden_example
+--markup markdown
 -
 LICENSE
 README.markdown

data/Gemfile

@@ -2,15 +2,25 @@
 source ENV['MBOX_BUNDLER_SOURCE'] if ENV['MBOX_BUNDLER_SOURCE']
 source "http://rubygems.org"
 
+# gem 'slyphon-zookeeper', :path => '~/zookeeper'
+
 group :development do
   gem 'pry'
+  gem 'rake'
+end
+
+group :docs do
+  gem 'yard', '~> 0.7.5'
+
+  platform :mri_19 do
+    gem 'redcarpet'
+  end
 end
 
 group :test do
   gem 'rspec', '~> 2.8.0'
   gem 'flexmock', '~> 0.8.10'
   gem 'ZenTest', '~> 4.5.0'
-  gem 'rake'
 end
 
 # Specify your gem's dependencies in zk.gemspec

data/README.markdown

@@ -2,10 +2,14 @@
 
 ZK is a high-level interface to the Apache [ZooKeeper][] server. It is based on the [zookeeper gem][] which is a multi-Ruby low-level driver. Currently MRI 1.8.7, 1.9.2, 1.9.3, and JRuby are supported (rubinius 1.2 is experimental but _should_ work). It is licensed under the [MIT][] license. 
 
+The key place to start in the documentation is with ZK::Client::Base ([rubydoc.info][ZK::Client::Base], [local](/docs/ZK/Client/Base)
+).
+
 This library is heavily used in a production deployment and is actively developed and maintained.
 
 Development is sponsored by [Snapfish][] and has been generously released to the Open Source community by HPDC, L.P.
 
+[ZK::Client::Base]: http://rubydoc.info/gems/zk/ZK/Client/Base
 [ZooKeeper]: http://zookeeper.apache.org/ "Apache ZooKeeper"
 [zookeeper gem]: https://github.com/slyphon/zookeeper "slyphon-zookeeper gem"
 [MIT]: http://www.gnu.org/licenses/license-list.html#Expat "MIT (Expat) License"
@@ -28,7 +32,7 @@ ZooKeeper is also (relatively) easy to deploy in a [Highly Available][ha-config]
 
 ## What does ZK do that the zookeeper gem doesn't?
 
-The [zookeeper gem][] provides a low-level, cross platform library for interfacing with ZooKeeper. While it is full featured, it only handles the basic operations that the driver provides. ZK implements the majority of the [recipes][] in the ZooKeeper documentation, plus a number of other conveniences for a production environment. 
+The [zookeeper gem][] provides a low-level, cross platform library for interfacing with ZooKeeper. While it is full featured, it only handles the basic operations that the driver provides. ZK implements the majority of the [recipes][] in the ZooKeeper documentation, plus a number of other conveniences for a production environment. ZK aims to be to Zookeeper, as Sequel or ActiveRecord is to the MySQL or Postgres drivers (not that ZK is attempting to provide an object persistence system, but rather a higher level API that users can develop applications with).
 
 ZK provides:
 
@@ -38,7 +42,7 @@ ZK provides:
 * 	a simple threadpool implementation
 * 	a bounded, dynamically-growable (threadsafe) client pool implementation
 * 	a recursive Find class (like the Find module in ruby-core)
-* 	unix-like rm\_rf and mkdir\_p methods (useful for functional testing)
+* 	unix-like rm\_rf and mkdir\_p methods
 * 	an extension for the [Mongoid][] ORM to provide advisory locks on mongodb records
 
 In addition to all of that, I would like to think that the public API the ZK::Client provides is more convenient to use for the common (synchronous) case. For use with [EventMachine][] there is [zk-eventmachine][] which provides a convenient API for writing evented code that uses the ZooKeeper server.
@@ -52,19 +56,24 @@ In addition to all of that, I would like to think that the public API the ZK::Cl
 
 ZK strives to be a complete, correct, and convenient way of interacting with ZooKeeper. There are a few weak points in the implementation:
 
+* Starting with 0.9 there is only *one* event dispatch thread (in 0.8 there are 5). It is *very important* that you don't block the event delivery thread.
+
+* If you're not familiar with developing solutions with zookeeper, you should read about [sessions][] and [watches][] in the Programmer's Guide. Even if you *are* familiar, you should probably go read it again. 
+
+* It is very important that you not ignore connection state events if you're using watches.
+
 * _ACLS: HOW DO THEY WORK?!_  ACL support is mainly faith-based now. I have not had a need for ACLs, and the authors of the upstream [twitter/zookeeper][] code also don't seem to have much experience with them/use for them (purely my opinion, no offense intended). If you are using ACLs and you find bugs or have suggestions, I would much appreciate feedback or examples of how they *should* work so that support and tests can be added.
 
 * ZK::Client supports asynchronous calls of all basic methods (get, set, delete, etc.) however these versions are kind of inconvenient to use. For a fully evented stack, try [zk-eventmachine][], which is designed to be compatible and convenient to use in event-driven code.
 
 * ZooKeeper "chroot" [connection syntax][chroot] is currently being developed and should work for most cases. Right now we require that the root path exist before the chrooted client is used, but that may change [in the near future](https://github.com/slyphon/zk/issues/7).
 
-* I am currently in the process of cleaning up the API documentation and converting it to use [YARD][]. 
-
 [twitter/zookeeper]: https://github.com/twitter/zookeeper
 [async-branch]: https://github.com/slyphon/zk/tree/dev%2Fasync-conveniences
 [chroot]: http://zookeeper.apache.org/doc/current/zookeeperProgrammers.html#ch_zkSessions
 [YARD]: http://yardoc.org/
-[dev/yard]: https://github.com/slyphon/zk/tree/dev%2Fyard
+[sessions]: http://zookeeper.apache.org/doc/current/zookeeperProgrammers.html#ch_zkSessions 
+[watches]: http://zookeeper.apache.org/doc/r3.3.5/zookeeperProgrammers.html#ch_zkWatches
 
 ## Dependencies
 
@@ -78,11 +87,11 @@ ZK strives to be a complete, correct, and convenient way of interacting with Zoo
 [szk-jar-gem]: https://rubygems.org/gems/slyphon-zookeeper_jar
 [szk-jar-repo]: https://github.com/slyphon/zookeeper_jar
 
-### Related Projects
-
-There are a few related projects that extend ZK.
+## Contacting the author
 
-* [ZK::Znode][]: a simple ORM to provide ActiveModel semantics around znodes. While still in early development, may also be a useful example of how to use ZK.
+* Send me a github message (slyphon)
+* I'm usually hanging out in IRC on freenode.net in #ruby-lang and in #zookeeper
+* if you really want to, you can also reach me via twitter [@slyphon][]
 
-[ZK::Znode]: https://github.com/slyphon/zk-znode
+[@slyphon]: https://twitter.com/#!/slyphon
 

data/RELEASES.markdown

@@ -0,0 +1,14 @@
+This file notes feature differences and bugfixes contained between releases. 
+
+### v0.9.0 ###
+
+* Default threadpool size has been changed from 5 to 1. This should only affect people who are using the Election code.
+* `ZK::Client::Base#register` delegates to its `event_handler` for convenience (so you can write `zk.register` instead of `zk.event_handler.register`, which always irked me)
+* `ZK::Client::Base#event_dispatch_thread?` added to more easily allow users to tell if they're currently in the event thread (and possibly make decisions about the safety of their actions). This is now used by `block_until_node_deleted` in the Unixisms module, and prevents a situation where the user could deadlock event delivery.
+* Fixed issue 9, where using a Locker in the main thread would never awaken if the connection was dropped or interrupted. Now a `ZK::Exceptions::InterruptedSession` exception (or mixee) will be thrown to alert the caller that something bad happened.
+* `ZK::Find.find` now returns the results in sorted order.
+* Added documentation explaining the Pool class, reasons for using it, reasons why you shouldn't (added complexities around watchers and events).
+* Began work on an experimental Multiplexed client, that would allow multithreaded clients to more effectively share a single connection by making all requests asynchronous behind the scenes, and using a queue to provide a synchronous (blocking) API. 
+
+
+# vim:ft=markdown

data/lib/z_k/client/base.rb

@@ -1,17 +1,47 @@
 module ZK
   module Client
+
+    # This class forms the base API for interacting with ZooKeeper. Most people will
+    # want to create instances of the class ZK::Client::Threaded, and the most
+    # convenient way of doing that is through the top-level method `ZK.new`
+    #
+    # @note There is a lot of functionality mixed into the subclasses of this
+    #   class! You should take a look at {Unixisms}, {Conveniences}, and
+    #   {StateMixin} for a lot of the higher-level functionality!
+    #
+    # @example Create a new default connection
+    #
+    #   # if no host:port is given, we connect to localhost:2181 by default
+    #   # (convenient for use in tests and in irb/pry)
+    #
+    #   zk = ZK.new
+    #
+    # @example Create a new connection, specifying host
+    #
+    #   zk = ZK.new('localhost:2181')
+    #
+    # @example For quick tasks, you can use the visitor pattern, (like the File class)
+    #
+    #   ZK.open('localhost:2181') do |zk|
+    #     # do stuff with connection
+    #   end
+    #
+    #   # connection is automatically closed
+    #
     class Base
       # The Eventhandler is used by client code to register callbacks to handle
       # events triggerd for given paths. 
       #
-      # @see ZK::EventHandler#register
+      # @see ZK::Client::Base#register
       attr_reader :event_handler
       
-      # @private the wrapped connection object
+      # the wrapped connection object
+      # @private 
       attr_reader :cnx
-
+      protected :cnx
 
       # @deprecated for backwards compatibility only
+      # use ZK::Client::Base#event_handler instead
       def watcher
         event_handler
       end
@@ -24,26 +54,44 @@ module ZK
 
       # @private
       def inspect
-        "#<#{self.class.name}:#{object_id} ...>"
+        "#<#{self.class.name}:#{object_id} zk_session_id=#{safe_session_id} ...>"
+      end
+
+      # Create a new client and connect to the zookeeper server. 
+      #
+      # @param [String] host should be a string of comma-separated host:port
+      #   pairs. You can also supply an optional "chroot" suffix that will act as
+      #   an implicit prefix to all paths supplied.
+      #
+      # @see ZK::Client::Threaded#initialize valid options to use with the
+      #   synchronous (non-evented) client
+      #
+      # @example Threaded client with two hosts and a chroot path
+      #    
+      #   ZK::Client.new("zk01:2181,zk02:2181/chroot/path")
+      #
+      def initialize(host, opts={})
+        # no-op
       end
 
       private
         # @private
         def jruby_closed?
-          @cnx.state == Java::OrgApacheZookeeper::ZooKeeper::States::CLOSED
+          cnx.state == Java::OrgApacheZookeeper::ZooKeeper::States::CLOSED
         end
 
         # @private
         def mri_closed?
-          @cnx.closed?
+          cnx.closed?
         end
 
       public
 
       # reopen the underlying connection
       # returns state of connection after operation
-      def reopen(timeout=10)
-        @cnx.reopen(timeout, @event_handler.get_default_watcher_block)
+      def reopen(timeout=nil)
+        timeout ||= @session_timeout # XXX: @session_timeout ?
+        cnx.reopen(timeout)
         @threadpool.start!  # restart the threadpool if previously stopped by close!
         state
       end
@@ -51,7 +99,7 @@ module ZK
       # close the underlying connection and clear all pending events.
       def close!
         event_handler.clear!
-        wrap_state_closed_error { @cnx.close unless @cnx.closed? }
+        wrap_state_closed_error { cnx.close unless cnx.closed? }
       end
 
       # Create a node with the given path. The node data will be the given data.
@@ -86,7 +134,7 @@ module ZK
       # @param [String] data the data to create the znode with
       # 
       # @option opts [Integer] :acl defaults to <tt>ZookeeperACLs::ZOO_OPEN_ACL_UNSAFE</tt>, 
-      #   otherwise the ACL for the node. Should be a +ZOO_*+ constant defined under the 
+      #   otherwise the ACL for the node. Should be a `ZOO_*` constant defined under the 
       #   ZookeeperACLs module in the zookeeper gem.
       #
       # @option opts [bool] :ephemeral (false) if true, the created node will be ephemeral
@@ -96,14 +144,14 @@ module ZK
       # @option opts [ZookeeperCallbacks::StringCallback] :callback (nil) provide a callback object
       #   that will be called when the znode has been created
       # 
-      # @option opts [Object] :context (nil) an object passed to the +:callback+
-      #   given as the +context+ param
+      # @option opts [Object] :context (nil) an object passed to the `:callback`
+      #   given as the `context` param
       #
       # @option opts [:ephemeral_sequential, :persistent_sequential, :persistent, :ephemeral] :mode (nil)
-      #   may be specified instead of :ephemeral and :sequence options. If +:mode+ *and* either of
-      #   the +:ephermeral+ or +:sequential+ options are given, the +:mode+ option will win
+      #   may be specified instead of :ephemeral and :sequence options. If `:mode` *and* either of
+      #   the `:ephermeral` or `:sequential` options are given, the `:mode` option will win
       #
-      # @raise [ZK::Exceptions::NodeExists] if a node with the same +path+ already exists
+      # @raise [ZK::Exceptions::NodeExists] if a node with the same `path` already exists
       # 
       # @raise [ZK::Exceptions::NoNode] if the parent node does not exist
       # 
@@ -209,17 +257,17 @@ module ZK
           end
         end
 
-        rv = check_rc(@cnx.create(h), h)
+        rv = check_rc(cnx.create(h), h)
 
         h[:callback] ? rv : rv[:path]
       end
 
       # Return the data and stat of the node of the given path.  
       # 
-      # If +:watch+ is true and the call is successful (no exception is
+      # If `:watch` is true and the call is successful (no exception is
       # raised), registered watchers on the node will be 'armed'. The watch
       # will be triggered by a successful operation that sets data on the node,
-      # or deletes the node. See +watcher+ for documentation on how to register
+      # or deletes the node. See `watcher` for documentation on how to register
       # blocks to be called when a watch event is fired.
       #
       # @todo fix references to Watcher documentation
@@ -233,8 +281,8 @@ module ZK
       #
       # @option opts [ZookeeperCallbacks::DataCallback] :callback to make this call asynchronously
       #
-      # @option opts [Object] :context an object passed to the +:callback+
-      #   given as the +context+ param
+      # @option opts [Object] :context an object passed to the `:callback`
+      #   given as the `context` param
       #
       # @return [Array] a two-element array of ['node data', #<ZookeeperStat::Stat>]
       #
@@ -271,7 +319,7 @@ module ZK
 
         setup_watcher!(:data, h)
 
-        rv = check_rc(@cnx.get(h), h)
+        rv = check_rc(cnx.get(h), h)
 
         opts[:callback] ? rv : rv.values_at(:data, :stat)
       end
@@ -308,8 +356,8 @@ module ZK
       # @option opts [ZookeeperCallbacks::StatCallback] :callback will recieve the
       #   ZookeeperStat::Stat object asynchronously
       #
-      # @option opts [Object] :context an object passed to the +:callback+
-      #   given as the +context+ param
+      # @option opts [Object] :context an object passed to the `:callback`
+      #   given as the `context` param
       #
       # @example unconditionally set the data of "/path"
       #
@@ -335,7 +383,7 @@ module ZK
 
         h = { :path => path, :data => data }.merge(opts)
 
-        rv = check_rc(@cnx.set(h), h)
+        rv = check_rc(cnx.set(h), h)
 
         opts[:callback] ? rv : rv[:stat]
       end
@@ -359,8 +407,8 @@ module ZK
       # @option opts [ZookeeperCallbacks::StatCallback] :callback will recieve the
       #   ZookeeperStat::Stat object asynchronously
       #
-      # @option opts [Object] :context an object passed to the +:callback+
-      #   given as the +context+ param
+      # @option opts [Object] :context an object passed to the `:callback`
+      #   given as the `context` param
       #
       # @return [ZookeeperStat::Stat] a stat object of the specified node
       #
@@ -399,7 +447,7 @@ module ZK
 
         setup_watcher!(:data, h)
 
-        rv = @cnx.stat(h)
+        rv = cnx.stat(h)
 
         return rv if opts[:callback] 
 
@@ -440,9 +488,12 @@ module ZK
       # If the watch is true and the call is successful (no exception is thrown),
       # registered watchers of the children of the node will be enabled. The
       # watch will be triggered by a successful operation that deletes the node
-      # of the given path or creates/delete a child under the node. See +watcher+
+      # of the given path or creates/delete a child under the node. See `watcher`
       # for documentation on how to register blocks to be called when a watch
       # event is fired.
+      #
+      # @note It is important to note that the list of children is _not sorted_. If you
+      #   need them to be ordered, you must call `.sort` on the returned array
       # 
       # @raise [ZK::Exceptions::NoNode] if the node does not exist
       # 
@@ -454,8 +505,8 @@ module ZK
       # @option opts [ZookeeperCallbacks::StringsCallback] :callback to make this
       #   call asynchronously
       #
-      # @option opts [Object] :context an object passed to the +:callback+
-      #   given as the +context+ param
+      # @option opts [Object] :context an object passed to the `:callback`
+      #   given as the `context` param
       # 
       # @example get children for path
       #
@@ -490,7 +541,7 @@ module ZK
 
         setup_watcher!(:child, h)
 
-        rv = check_rc(@cnx.get_children(h), h)
+        rv = check_rc(cnx.get_children(h), h)
         opts[:callback] ? rv : rv[:children]
       end
 
@@ -505,9 +556,6 @@ module ZK
       # Can be called with just the path, otherwise a hash with the arguments
       # set.  Supports being executed asynchronousy by passing a callback object.
       #
-      # A KeeperException with error code KeeperException::NotEmpty will be
-      # thrown if the node has children.
-      #
       # @raise [ZK::Exceptions::NoNode] raised if no node with the given path exists 
       # 
       # @raise [ZK::Exceptions::BadVersion] raised if the given version does not
@@ -524,8 +572,8 @@ module ZK
       # @option opts [ZookeeperCallbacks::VoidCallback] :callback will be called
       #   asynchronously when the operation is complete
       #
-      # @option opts [Object] :context an object passed to the +:callback+
-      #   given as the +context+ param
+      # @option opts [Object] :context an object passed to the `:callback`
+      #   given as the `context` param
       # 
       # @example delete a node
       #   zk.delete("/path")
@@ -549,7 +597,7 @@ module ZK
 
 
         h = { :path => path, :version => -1 }.merge(opts)
-        rv = check_rc(@cnx.delete(h), h)
+        rv = check_rc(cnx.delete(h), h)
         opts[:callback] ? rv : nil
       end
 
@@ -567,8 +615,8 @@ module ZK
       # @option opts [ZookeeperCallback::AclCallback] (nil) :callback for an
       #   asynchronous call to occur
       #
-      # @option opts [Object] :context (nil) an object passed to the +:callback+
-      #   given as the +context+ param
+      # @option opts [Object] :context (nil) an object passed to the `:callback`
+      #   given as the `context` param
       # 
       # @example get acl
       #
@@ -595,7 +643,7 @@ module ZK
         #   zk.acls("/path", :callback => callback, :context => context)
 
         h = { :path => path }.merge(opts)
-        rv = check_rc(@cnx.get_acl(h), h)
+        rv = check_rc(cnx.get_acl(h), h)
         opts[:callback] ? rv : rv.values_at(:children, :stat)
       end
 
@@ -619,14 +667,14 @@ module ZK
       # @option opts [ZookeeperCallbacks::VoidCallback] :callback will be called
       #   asynchronously when the operation is complete
       #
-      # @option opts [Object] :context an object passed to the +:callback+
-      #   given as the +context+ param
+      # @option opts [Object] :context an object passed to the `:callback`
+      #   given as the `context` param
       #
       # @todo: TBA - waiting on clarification of method use
       #
       def set_acl(path, acls, opts={})
         h = { :path => path, :acl => acls }.merge(opts)
-        rv = check_rc(@cnx.set_acl(h), h)
+        rv = check_rc(cnx.set_acl(h), h)
         opts[:callback] ? rv : rv[:stat]
       end
 
@@ -647,21 +695,88 @@ module ZK
 
           raise ArgumentError, "#{level.inspect} is not a valid argument to set_debug_level" unless num
 
-          @cnx.set_debug_level(num)
+          cnx.set_debug_level(num)
         end
       end
 
       # returns the session_id of the underlying connection
       def session_id
-        @cnx.session_id
+        cnx.session_id
       end
 
       # returns the session_passwd of the underlying connection
       def session_passwd
-        @cnx.session_passwd
+        cnx.session_passwd
+      end
+      
+      # Register a block that should be delivered events for a given path. After 
+      # registering a block, you need to call {#get}, {#stat}, or {#children} with the
+      # `:watch => true` option for the block to receive _the next event_ (see note).
+      # {#get} and {#stat} will cause the block to receive events when the path is
+      # created, deleted, or its data is changed. {#children} will cause the block to
+      # receive events about its list of child nodes changing (i.e. being added
+      # or deleted, but *not* their content changing).
+      #
+      # This method will return an {EventHandlerSubscription} instance that can be used
+      # to remove the block from further updates by calling its `.unsubscribe` method.
+      #
+      # @note All node watchers are one-shot handlers. After an event is delivered to
+      #   your handler, you *must* re-watch the node to receive more events. This
+      #   leads to a pattern you will find throughout ZK code that avoids races,
+      #   see the example below "avoiding a race"
+      #
+      # @example avoiding a race waiting for a node to be deleted
+      #
+      #   # we expect that '/path/to/node' exists currently and want to be notified
+      #   # when it's deleted
+      #
+      #   # register a handler that will be called back when an event occurs on
+      #   # node
+      #   # 
+      #   node_subscription = zk.register('/path/to/node') do |event|
+      #     if event.node_deleted?
+      #       do_something_when_node_deleted
+      #     end
+      #   end
+      #
+      #   # check to see if our condition is true *while* setting a watch on the node
+      #   # if our condition happens to be true while setting the watch
+      #   #
+      #   unless exists?('/path/to/node', :watch => true)
+      #     node_subscription.unsubscribe   # cancel the watch
+      #     do_something_when_node_deleted  # call the callback
+      #   end
+      #
+      #
+      # @param [String] path the path you want to listen to
+      #
+      # @param [Block] block the block to execute when a watch event happpens
+      #
+      # @yield [event] We will call your block with the watch event object (which
+      #   has the connection the event occurred on as its #zk attribute)
+      #
+      # @return [EventHandlerSubscription] the subscription object
+      #   you can use to to unsubscribe from an event
+      #
+      # @see ZooKeeper::WatcherEvent
+      # @see ZK::EventHandlerSubscription
+      #
+      def register(path, &block)
+        event_handler.register(path, &block)
+      end
+
+      # returns true if the caller is calling from the event dispatch thread
+      def event_dispatch_thread?
+        cnx.event_dispatch_thread?
+      end
+
+      # @private
+      def assert_we_are_not_on_the_event_dispatch_thread!
+        raise Exceptions::EventDispatchThreadException, "blocking method called on dispatch thread" if event_dispatch_thread?
       end
 
       protected
+        # @private
         def check_rc(hash, inputs=nil)
           code = hash[:rc]
           if code && (code != Zookeeper::ZOK)
@@ -672,9 +787,19 @@ module ZK
           end
         end
 
+        # @private
         def setup_watcher!(watch_type, opts)
           event_handler.setup_watcher!(watch_type, opts)
         end
+
+        # used in #inspect, doesn't raise an error if we're not connected
+        def safe_session_id
+          if cnx and cnx.session_id
+            '0x%x' % cnx.session_id
+          end
+        rescue ZookeeperExceptions::ZookeeperException, ZK::Exceptions::KeeperException
+          nil
+        end
     end # Base
   end   # Client
 end     # ZK

data/lib/z_k/client/continuation_proxy.rb

@@ -0,0 +1,99 @@
+module ZK
+  module Client
+    # Wraps calls to zookeeper so that the requests are made asynchronously,
+    # but still provides a blocking API
+    #
+    # @private
+    class ContinuationProxy
+      include ZK::Logging
+
+      attr_accessor :zookeeper_cnx
+
+      # @private
+      def self.call_with_continuation(*syms)
+        syms.each do |sym|
+          class_eval(<<-EOS, __FILE__, __LINE__+1)
+            def #{sym}(opts)
+              logger.debug { "_call_continue(#{sym.inspect}, \#{opts.inspect})" }
+              _call_continue(#{sym.inspect}, opts)
+            end
+          EOS
+        end
+      end
+
+      call_with_continuation :create, :get, :set, :stat, :children, :delete, :get_acl, :set_acl
+
+      def initialize(zookeeper_cnx=nil)
+        @zookeeper_cnx = zookeeper_cnx
+        @mutex = Mutex.new
+        @dropboxen = []
+      end
+
+      # called by the multiplxed client to wake up threads that are waiting for
+      # results (with an exception)
+      # @private
+      def connection_closed!
+        _oh_noes(ZookeeperExceptions::ZookeeperException::NotConnected, 'connection closed')
+      end
+
+      # called by the multiplxed client to wake up threads that are waiting for
+      # results (with an exception)
+      # @private
+      def expired_session!
+        _oh_noes(ZookeeperExceptions::ZookeeperException::SessionExpired, 'session expired')
+      end
+
+      private
+        def method_missing(m, *a, &b)
+          @zookeeper_cnx.respond_to?(m) ? @zookeeper_cnx.__send__(m, *a, &b) : super
+        end
+
+        def _oh_noes(exception, message)
+          @mutex.synchronize do
+            @dropboxen.each do |db|
+              db.oh_noes!(exception, message)
+            end
+          end
+        end
+
+        # not really callcc, but close enough
+        # opts should be an options hash as passed through to the Zookeeper
+        # layer
+        def _call_continue(meth, opts)
+          _assert_not_async!(meth, opts)
+
+          opts = opts.dup
+
+          _with_drop_box do |db|
+            cb = lambda do |hash|
+              logger.debug { "#{self.class}##{__method__} block pushing: #{hash.inspect}" } 
+              db.push(hash)
+            end
+
+            opts[:callback] = cb
+
+            @zookeeper_cnx.__send__(meth, opts)
+
+            db.pop.tap do |obj|
+              logger.debug { "#{self.class}##{__method__} popped and returning: #{obj.inspect}" } 
+            end
+          end
+        end
+
+        def _with_drop_box
+          db = DropBox.current
+          @mutex.synchronize { @dropboxen << db }
+          yield db
+        ensure
+          @mutex.synchronize { @dropboxen.delete(db) }
+          db.clear
+        end
+
+        def _assert_not_async!(meth, opts)
+          return unless opts.has_key?(:callback)
+          raise ArgumentError, "you cannot use async callbacks with a Multiplexed client! meth: #{meth.inspect}, opts: #{opts.inspect}"
+        end
+    end # ContinuationProxy
+  end
+end
+