zk 0.8.1 → 0.8.2

data/README.markdown

@@ -41,10 +41,12 @@ ZK provides:
 * 	a recursive Find class (like the Find module in ruby-core)
 * 	unix-like rm\_rf and mkdir\_p methods (useful for functional testing)
 
-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.
+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.
 
 [recipes]: http://zookeeper.apache.org/doc/current/recipes.html
 [Mongoid]: http://mongoid.org/
+[EventMachine]: https://github.com/eventmachine/eventmachine
+[zk-eventmachine]: https://github.com/slyphon/zk-eventmachine
 
 ## Caveats
 
@@ -52,11 +54,11 @@ ZK strives to be a complete, correct, and convenient way of interacting with Zoo
 
 * _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. There is a [branch][async-branch] for making improvements in this regard. This will be improved in the near-term as a related EventMachine-based project will be making use of these.
+* 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] _(search for "chroot" in page)_ is not currently working in the C drivers, and I don't have tests for the Java version. This hasn't been an incredibly high priority item, but support for this feature is intended.
 
-* I am currently in the process of cleaning up the API documentation and converting it to use [YARD][]. You can follow along on [this branch][dev/yard] which will be merged into master and released ASAP.
+* 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

data/lib/z_k/client/base.rb

@@ -1,24 +1,28 @@
 module ZK
   module Client
     class Base
+      # The Eventhandler is used by client code to register callbacks to handle
+      # events triggerd for given paths. 
+      #
+      # @see ZK::EventHandler#register
       attr_reader :event_handler
       
       # @private the wrapped connection object
       attr_reader :cnx
 
 
-      # @deprecated: for backwards compatibility only
+      # @deprecated for backwards compatibility only
       def watcher
         event_handler
       end
 
       # returns true if the connection has been closed
-      #--
-      # XXX: should this be *our* idea of closed or ZOO_CLOSED_STATE ?
       def closed?
+        # XXX: should this be *our* idea of closed or ZOO_CLOSED_STATE ?
         defined?(::JRUBY_VERSION) ? jruby_closed? : mri_closed?
       end
 
+      # @private
       def inspect
         "#<#{self.class.name}:#{object_id} ...>"
       end
@@ -44,6 +48,7 @@ module ZK
         state
       end
 
+      # close the underlying connection and clear all pending events.
       def close!
         event_handler.clear!
         wrap_state_closed_error { @cnx.close unless @cnx.closed? }
@@ -647,11 +652,12 @@ module ZK
 
       protected
         def check_rc(hash, inputs=nil)
-          hash.tap do |h|
-            if code = h[:rc]
-              msg = inputs ? "inputs: #{inputs.inspect}" : nil
-              raise Exceptions::KeeperException.by_code(code), msg unless code == Zookeeper::ZOK
-            end
+          code = hash[:rc]
+          if code && (code != Zookeeper::ZOK)
+            msg = inputs ? "inputs: #{inputs.inspect}" : nil
+            raise Exceptions::KeeperException.by_code(code), msg 
+          else
+            hash
           end
         end
 

data/lib/z_k/client/threaded.rb

@@ -26,8 +26,8 @@ module ZK
 
       # closes the underlying connection and deregisters all callbacks
       def close!
-        super
         @threadpool.shutdown
+        super
         nil
       end
     end

data/lib/z_k/event_handler.rb

@@ -1,7 +1,8 @@
 module ZK
-  # this is the default watcher provided by the zookeeper connection
+  # This is the default watcher provided by the zookeeper connection
   # watchers are implemented by adding the :watch => true flag to
   # any #children or #get or #exists calls
+  #
   # you never really need to initialize this yourself
   class EventHandler
     include org.apache.zookeeper.Watcher if defined?(JRUBY_VERSION)
@@ -32,16 +33,50 @@ module ZK
     end
 
     # register a path with the handler
+    #
     # your block will be called with all events on that path.
-    # aliased as #subscribe
+    #
+    # @note All 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.event_handler.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 [connection, event] We will call your block with the connection the
-    #   watch event occured on and the event object
+    #
+    # @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 [ZooKeeper::EventHandlerSubscription] the subscription object
     #   you can use to to unsubscribe from an event
+    #
     # @see ZooKeeper::WatcherEvent
-    # @see ZooKeeper::EventHandlerSubscription
+    # @see ZK::EventHandlerSubscription
+    #
     def register(path, &block)
 #       logger.debug { "EventHandler#register path=#{path.inspect}" }
       EventHandlerSubscription.new(self, path, block).tap do |subscription|
@@ -54,13 +89,14 @@ module ZK
     #
     # @param [String] state the state you want to register for
     # @param [Block] block the block to execute on state changes
-    # @yield [connection, event] yields your block with
+    # @yield [event] yields your block with
+    #
     def register_state_handler(state, &block)
       register(state_key(state), &block)
     end
 
     # @deprecated use #unsubscribe on the subscription object
-    # @see ZooKeeper::EventHandlerSubscription#unsubscribe
+    # @see ZK::EventHandlerSubscription#unsubscribe
     def unregister_state_handler(*args)
       if args.first.is_a?(EventHandlerSubscription)
         unregister(args.first)
@@ -70,7 +106,7 @@ module ZK
     end
 
     # @deprecated use #unsubscribe on the subscription object
-    # @see ZooKeeper::EventHandlerSubscription#unsubscribe
+    # @see ZK::EventHandlerSubscription#unsubscribe
     def unregister(*args)
       if args.first.is_a?(EventHandlerSubscription)
         subscription = args.first
@@ -93,7 +129,8 @@ module ZK
     alias :unsubscribe :unregister
 
     # called from the client-registered callback when an event fires
-    def process(event) #:nodoc:
+    # @private
+    def process(event)
 #       logger.debug { "EventHandler#process dispatching event: #{event.inspect}" }# unless event.type == -1
       event.zk = @zk
 
@@ -127,6 +164,7 @@ module ZK
     end
 
     # used during shutdown to clear registered listeners
+    # @private
     def clear! #:nodoc:
       synchronize do
         @callbacks.clear
@@ -134,10 +172,12 @@ module ZK
       end
     end
 
-    def synchronize #:nodoc:
+    # @private
+    def synchronize
       @mutex.synchronize { yield }
     end
 
+    # @private
     def get_default_watcher_block
       @default_watcher_block ||= lambda do |hash|
         watcher_callback.tap do |cb|
@@ -151,6 +191,8 @@ module ZK
     # doesn't re-register the watcher with the server until a response has been
     # fired. This prevents one event delivery to *every* callback per :watch => true
     # argument.
+    #
+    # @private
     def setup_watcher!(watch_type, opts)
       return unless opts.delete(:watch)
 
@@ -169,10 +211,12 @@ module ZK
     end
 
     protected
+      # @private
       def watcher_callback
         ZookeeperCallbacks::WatcherCallback.create { |event| process(event) }
       end
 
+      # @private
       def state_key(arg)
         int = 
           case arg
@@ -189,6 +233,7 @@ module ZK
         raise ArgumentError, "#{arg} is not a valid zookeeper state", caller
       end
 
+      # @private
       def safe_call(callbacks, *args)
         while cb = callbacks.shift
           begin

data/lib/z_k/extensions.rb

@@ -127,7 +127,9 @@ ZookeeperStat::Stat.send(:include, ZK::Extensions::Stat)
 class ::Exception
   unless method_defined?(:to_std_format)
     def to_std_format
-      "#{self.class}: #{message}\n\t" + backtrace.join("\n\t")
+      ary = ["#{self.class}: #{message}"]
+      ary.concat(backtrace || [])
+      ary.join("\n\t")
     end
   end
 end

data/lib/z_k/version.rb

@@ -1,3 +1,3 @@
 module ZK
-  VERSION = "0.8.1"
+  VERSION = "0.8.2"
 end

data/spec/z_k/extensions_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+module ZK
+  describe 'Extensions' do
+    describe 'Exception#to_std_format' do
+
+      it %[should not barf if backtrace is nil] do
+        exc = StandardError.new
+        exc.backtrace.should be_nil
+        lambda { exc.to_std_format }.should_not raise_error
+      end
+    end
+  end
+end
+

data/zk.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |s|
   s.summary     = %q{A high-level wrapper around the zookeeper driver}
   s.description = s.summary
 
-  s.add_runtime_dependency 'slyphon-zookeeper', '~> 0.2.0'
+  s.add_runtime_dependency 'slyphon-zookeeper', '~> 0.2.1'
 
   s.add_development_dependency 'rspec', '~> 2.4.0'
   s.add_development_dependency 'wirble'

metadata

@@ -1,78 +1,106 @@
 --- !ruby/object:Gem::Specification 
 name: zk
 version: !ruby/object:Gem::Version 
+  hash: 59
   prerelease: 
-  version: 0.8.1
+  segments: 
+  - 0
+  - 8
+  - 2
+  version: 0.8.2
 platform: ruby
 authors: 
-  - Jonathan D. Simms
-  - Topper Bowers
+- Jonathan D. Simms
+- Topper Bowers
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2011-06-17 00:00:00 +00:00
+date: 2011-06-27 00:00:00 +00:00
 default_executable: 
 dependencies: 
-  - !ruby/object:Gem::Dependency 
-    name: slyphon-zookeeper
-    prerelease: false
-    requirement: &id001 !ruby/object:Gem::Requirement 
-      none: false
-      requirements: 
-        - - ~>
-          - !ruby/object:Gem::Version 
-            version: 0.2.0
-    type: :runtime
-    version_requirements: *id001
-  - !ruby/object:Gem::Dependency 
-    name: rspec
-    prerelease: false
-    requirement: &id002 !ruby/object:Gem::Requirement 
-      none: false
-      requirements: 
-        - - ~>
-          - !ruby/object:Gem::Version 
-            version: 2.4.0
-    type: :development
-    version_requirements: *id002
-  - !ruby/object:Gem::Dependency 
-    name: wirble
-    prerelease: false
-    requirement: &id003 !ruby/object:Gem::Requirement 
-      none: false
-      requirements: 
-        - - ">="
-          - !ruby/object:Gem::Version 
-            version: "0"
-    type: :development
-    version_requirements: *id003
-  - !ruby/object:Gem::Dependency 
-    name: flexmock
-    prerelease: false
-    requirement: &id004 !ruby/object:Gem::Requirement 
-      none: false
-      requirements: 
-        - - ~>
-          - !ruby/object:Gem::Version 
-            version: 0.8.10
-    type: :development
-    version_requirements: *id004
-  - !ruby/object:Gem::Dependency 
-    name: ZenTest
-    prerelease: false
-    requirement: &id005 !ruby/object:Gem::Requirement 
-      none: false
-      requirements: 
-        - - ~>
-          - !ruby/object:Gem::Version 
-            version: 4.5.0
-    type: :development
-    version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: slyphon-zookeeper
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 21
+        segments: 
+        - 0
+        - 2
+        - 1
+        version: 0.2.1
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 31
+        segments: 
+        - 2
+        - 4
+        - 0
+        version: 2.4.0
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: wirble
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: flexmock
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 43
+        segments: 
+        - 0
+        - 8
+        - 10
+        version: 0.8.10
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: ZenTest
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 43
+        segments: 
+        - 4
+        - 5
+        - 0
+        version: 4.5.0
+  type: :development
+  version_requirements: *id005
 description: A high-level wrapper around the zookeeper driver
 email: 
-  - simms@hp.com
-  - tobowers@hp.com
+- simms@hp.com
+- tobowers@hp.com
 executables: []
 
 extensions: []
@@ -80,50 +108,51 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-  - .dotfiles/rspec-logging
-  - .gitignore
-  - .yardopts
-  - Gemfile
-  - LICENSE
-  - README.markdown
-  - Rakefile
-  - lib/z_k.rb
-  - lib/z_k/client.rb
-  - lib/z_k/client/base.rb
-  - lib/z_k/client/conveniences.rb
-  - lib/z_k/client/state_mixin.rb
-  - lib/z_k/client/threaded.rb
-  - lib/z_k/client/unixisms.rb
-  - lib/z_k/election.rb
-  - lib/z_k/event_handler.rb
-  - lib/z_k/event_handler_subscription.rb
-  - lib/z_k/exceptions.rb
-  - lib/z_k/extensions.rb
-  - lib/z_k/find.rb
-  - lib/z_k/locker.rb
-  - lib/z_k/logging.rb
-  - lib/z_k/message_queue.rb
-  - lib/z_k/mongoid.rb
-  - lib/z_k/pool.rb
-  - lib/z_k/threadpool.rb
-  - lib/z_k/version.rb
-  - lib/zk.rb
-  - spec/log4j.properties
-  - spec/message_queue_spec.rb
-  - spec/spec_helper.rb
-  - spec/support/bogus_mongoid.rb
-  - spec/support/logging_progress_bar_formatter.rb
-  - spec/support/queuey_thread.rb
-  - spec/test_file.txt
-  - spec/watch_spec.rb
-  - spec/z_k/client_spec.rb
-  - spec/z_k/election_spec.rb
-  - spec/z_k/locker_spec.rb
-  - spec/z_k/mongoid_spec.rb
-  - spec/z_k/pool_spec.rb
-  - spec/z_k/threadpool_spec.rb
-  - spec/zookeeper_spec.rb
-  - zk.gemspec
+- .dotfiles/rspec-logging
+- .gitignore
+- .yardopts
+- Gemfile
+- LICENSE
+- README.markdown
+- Rakefile
+- lib/z_k.rb
+- lib/z_k/client.rb
+- lib/z_k/client/base.rb
+- lib/z_k/client/conveniences.rb
+- lib/z_k/client/state_mixin.rb
+- lib/z_k/client/threaded.rb
+- lib/z_k/client/unixisms.rb
+- lib/z_k/election.rb
+- lib/z_k/event_handler.rb
+- lib/z_k/event_handler_subscription.rb
+- lib/z_k/exceptions.rb
+- lib/z_k/extensions.rb
+- lib/z_k/find.rb
+- lib/z_k/locker.rb
+- lib/z_k/logging.rb
+- lib/z_k/message_queue.rb
+- lib/z_k/mongoid.rb
+- lib/z_k/pool.rb
+- lib/z_k/threadpool.rb
+- lib/z_k/version.rb
+- lib/zk.rb
+- spec/log4j.properties
+- spec/message_queue_spec.rb
+- spec/spec_helper.rb
+- spec/support/bogus_mongoid.rb
+- spec/support/logging_progress_bar_formatter.rb
+- spec/support/queuey_thread.rb
+- spec/test_file.txt
+- spec/watch_spec.rb
+- spec/z_k/client_spec.rb
+- spec/z_k/election_spec.rb
+- spec/z_k/extensions_spec.rb
+- spec/z_k/locker_spec.rb
+- spec/z_k/mongoid_spec.rb
+- spec/z_k/pool_spec.rb
+- spec/z_k/threadpool_spec.rb
+- spec/zookeeper_spec.rb
+- zk.gemspec
 has_rdoc: true
 homepage: ""
 licenses: []
@@ -132,39 +161,46 @@ post_install_message:
 rdoc_options: []
 
 require_paths: 
-  - lib
+- lib
 required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.5.1
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: A high-level wrapper around the zookeeper driver
 test_files: 
-  - spec/log4j.properties
-  - spec/message_queue_spec.rb
-  - spec/spec_helper.rb
-  - spec/support/bogus_mongoid.rb
-  - spec/support/logging_progress_bar_formatter.rb
-  - spec/support/queuey_thread.rb
-  - spec/test_file.txt
-  - spec/watch_spec.rb
-  - spec/z_k/client_spec.rb
-  - spec/z_k/election_spec.rb
-  - spec/z_k/locker_spec.rb
-  - spec/z_k/mongoid_spec.rb
-  - spec/z_k/pool_spec.rb
-  - spec/z_k/threadpool_spec.rb
-  - spec/zookeeper_spec.rb
+- spec/log4j.properties
+- spec/message_queue_spec.rb
+- spec/spec_helper.rb
+- spec/support/bogus_mongoid.rb
+- spec/support/logging_progress_bar_formatter.rb
+- spec/support/queuey_thread.rb
+- spec/test_file.txt
+- spec/watch_spec.rb
+- spec/z_k/client_spec.rb
+- spec/z_k/election_spec.rb
+- spec/z_k/extensions_spec.rb
+- spec/z_k/locker_spec.rb
+- spec/z_k/mongoid_spec.rb
+- spec/z_k/pool_spec.rb
+- spec/z_k/threadpool_spec.rb
+- spec/zookeeper_spec.rb