zk 1.0.0 → 1.1.0

data/lib/zk/election.rb

@@ -106,39 +106,38 @@ module ZK
       end
 
       # Asynchronously call the block when the leader has acknowledged its
-      # role. The given block will *always* be called on a background thread. 
+      # role. 
       def on_leader_ack(&block)
-        creation_sub = @zk.watcher.register(leader_ack_path) do |event|
-          case event.type
-          when Zookeeper::ZOO_CREATED_EVENT, Zookeeper::ZOO_CHANGED_EVENT
+        creation_sub = @zk.register(leader_ack_path, :only => [:created, :changed]) do |event|
+          begin
+            logger.debug { "in #{leader_ack_path} watcher, got creation event, notifying" }
+            safe_call(block)
+          ensure
+            creation_sub.unregister
+          end
+        end
+
+        deletion_sub = @zk.register(leader_ack_path, :only => [:deleted, :child]) do |event|
+          if @zk.exists?(leader_ack_path, :watch => true)
             begin
-              logger.debug { "in #{leader_ack_path} watcher, got creation event, notifying" }
-              block.call
+              logger.debug { "in #{leader_ack_path} watcher, node created behind our back, notifying" }
+              safe_call(block)
             ensure
               creation_sub.unregister
             end
           else
-            if @zk.exists?(leader_ack_path, :watch => true)
-              begin
-                logger.debug { "in #{leader_ack_path} watcher, node created behind our back, notifying" }
-                block.call
-              ensure
-                creation_sub.unregister
-              end
-            else
-              logger.debug { "in #{leader_ack_path} watcher, got non-creation event, re-watching" }
-            end
+            logger.debug { "in #{leader_ack_path} watcher, got non-creation event, re-watching" }
           end
         end
 
-        @zk.defer do
-          if @zk.exists?(leader_ack_path, :watch => true)
-            logger.debug { "on_leader_ack, #{leader_ack_path} exists, calling block" }
-            begin
-              block.call
-            ensure
-              creation_sub.unregister if creation_sub
-            end
+        subs = [creation_sub, deletion_sub]
+
+        if @zk.exists?(leader_ack_path, :watch => true)
+          logger.debug { "on_leader_ack, #{leader_ack_path} exists, calling block" }
+          begin
+            safe_call(block)
+          ensure
+            subs.each { |s| s.unregister }
           end
         end
       end
@@ -154,7 +153,6 @@ module ZK
 
         def digit(path)
           path[/\d+$/].to_i
-
         end
 
         def safe_call(*callbacks)
@@ -167,6 +165,12 @@ module ZK
             end
           end
         end
+
+        def synchronize
+#           call_line = caller[0..-2]
+#           logger.debug { "synchronizing, backtrace:\n#{call_line.join("\n")}" }
+          @mutex.synchronize { yield }
+        end
     end
 
     # This class is for registering candidates in the leader election. This instance will
@@ -225,7 +229,7 @@ module ZK
       #
       # +data+ will be placed in the znode representing our vote
       def vote!
-        @mutex.synchronize do
+        synchronize do
           clear_next_node_ballot_sub!
           cast_ballot!(@data) unless @vote_path
           check_election_results!
@@ -279,17 +283,17 @@ module ZK
 
             logger.info { "ZK: following #{next_ballot} for changes, #{@data.inspect}" }
 
-            @next_node_ballot_sub ||= @zk.watcher.register(next_ballot) do |event| 
+            @next_node_ballot_sub ||= @zk.register(next_ballot) do |event| 
               if event.node_deleted? 
                 logger.debug { "#{next_ballot} was deleted, voting, #{@data.inspect}" }
-                vote! 
+                @zk.defer { vote! }
               else
                 # this takes care of the race condition where the leader ballot would
                 # have been deleted before we could re-register to receive updates
                 # if zk.stat returns false, it means the path was deleted
                 unless @zk.exists?(next_ballot, :watch => true)
                   logger.debug { "#{next_ballot} was deleted (detected on re-watch), voting, #{@data.inspect}" }
-                  vote! 
+                  @zk.defer { vote! }
                 end
               end
             end
@@ -298,7 +302,7 @@ module ZK
             # our callback has fired. In this case, retry and do this procedure again
             unless @zk.stat(next_ballot, :watch => true).exists?
               logger.debug { "#{@data.inspect}: the node #{next_ballot} did not exist, retrying" }
-              vote!
+              @zk.defer { vote! }
             end
           end
         end
@@ -331,7 +335,7 @@ module ZK
 
       # our current idea about the state of the election
       def leader_alive #:nodoc:
-        @mutex.synchronize { @leader_alive }
+        synchronize { @leader_alive }
       end
 
       # register callbacks that should be fired when a leader dies
@@ -346,11 +350,11 @@ module ZK
       end
 
       def observe!
-        @mutex.synchronize do
+        synchronize do
           return if @observing 
           @observing = true
 
-          @leader_ack_sub ||= @zk.watcher.register(leader_ack_path) do |event|
+          @leader_ack_sub ||= @zk.register(leader_ack_path) do |event|
             logger.debug { "leader_ack_callback, event.node_deleted? #{event.node_deleted?}, event.node_created? #{event.node_created?}" }
 
             if event.node_deleted?
@@ -379,7 +383,7 @@ module ZK
       end
 
       def close
-        @mutex.synchronize do
+        synchronize do
           return unless @observing
 
           @deletion_sub.unregister if @deletion_sub
@@ -397,7 +401,7 @@ module ZK
 
       protected
         def the_king_is_dead
-          @mutex.synchronize do
+          synchronize do
             safe_call(*@leader_death_cbs)
             @leader_alive = false
           end
@@ -406,7 +410,7 @@ module ZK
         end
 
         def long_live_the_king
-          @mutex.synchronize do
+          synchronize do
             safe_call(*@new_leader_cbs)
             @leader_alive = true
           end
@@ -414,5 +418,5 @@ module ZK
           the_king_is_dead unless leader_acked?(true)
         end
     end
-  end
-end
+  end # Election
+end # ZK

data/lib/zk/event.rb

@@ -26,6 +26,14 @@ module ZK
       EVENT_TYPES = %w[created deleted changed child session notwatching].freeze 
     end
 
+    # for testing, create a new ZookeeperCallbacks::WatcherCallback and return it
+    # @private
+    def self.new(hash)
+      ZookeeperCallbacks::WatcherCallback.new.tap do |wc|
+        wc.call(hash)
+      end
+    end
+
     # The numeric constant (one of `ZOO_*_EVENT`) that ZooKeeper sets to
     # indicate the type of event this is. Users are advised to use the '?'
     # methods below instead of using this value.

data/lib/zk/event_handler.rb

@@ -8,10 +8,13 @@ module ZK
     include org.apache.zookeeper.Watcher if defined?(JRUBY_VERSION)
     include ZK::Logging
 
+    # @private
     VALID_WATCH_TYPES = [:data, :child].freeze
 
+    # @private
     ALL_NODE_EVENTS_KEY = :all_node_events
 
+    # @private
     ZOOKEEPER_WATCH_TYPE_MAP = {
       Zookeeper::ZOO_CREATED_EVENT => :data,
       Zookeeper::ZOO_DELETED_EVENT => :data,
@@ -19,15 +22,24 @@ module ZK
       Zookeeper::ZOO_CHILD_EVENT   => :child,
     }.freeze
 
+    # @private
+    VALID_THREAD_OPTS = [:single, :per_callback].freeze
+
     # @private
     attr_accessor :zk
 
     # @private
     # :nodoc:
-    def initialize(zookeeper_client)
+    def initialize(zookeeper_client, opts={})
       @zk = zookeeper_client
       @callbacks = Hash.new { |h,k| h[k] = [] }
 
+      @thread_opt = opts.fetch(:thread, :single)
+
+      # this is side-effecty, will raise an ArgumentError if given a bad
+      # value. 
+      EventHandlerSubscription.class_for_thread_option(@thread_opt)
+
       @mutex = Monitor.new
 
       @outstanding_watches = VALID_WATCH_TYPES.inject({}) do |h,k|
@@ -36,10 +48,25 @@ module ZK
     end
 
     # @see ZK::Client::Base#register
-    def register(path, interests=nil, &block)
+    def register(path, opts={}, &block)
       path = ALL_NODE_EVENTS_KEY if path == :all
 
-      EventHandlerSubscription.new(self, path, block, interests).tap do |subscription|
+      hash = {:thread => @thread_opt}
+
+      # gah, ok, handle the 1.0 form
+      case opts
+      when Array, Symbol
+        warn "Deprecated! #{self.class}#register use the :only option instead of passing a symbol or array"
+        hash[:only] = opts
+      when Hash
+        hash.merge!(opts)
+      when nil
+        # no-op
+      else
+        raise ArgumentError, "don't know how to handle options: #{opts.inspect}" 
+      end
+
+      EventHandlerSubscription.new(self, path, block, hash).tap do |subscription|
         synchronize { @callbacks[path] << subscription }
       end
     end
@@ -65,7 +92,7 @@ module ZK
     # @deprecated use #unsubscribe on the subscription object
     # @see ZK::EventHandlerSubscription#unsubscribe
     def unregister_state_handler(*args)
-      if args.first.is_a?(EventHandlerSubscription)
+      if args.first.is_a?(EventHandlerSubscription::Base)
         unregister(args.first)
       else
         unregister(state_key(args.first), args[1])
@@ -75,9 +102,9 @@ module ZK
     # @deprecated use #unsubscribe on the subscription object
     # @see ZK::EventHandlerSubscription#unsubscribe
     def unregister(*args)
-      if args.first.is_a?(EventHandlerSubscription)
+      if args.first.is_a?(EventHandlerSubscription::Base)
         subscription = args.first
-      elsif args.first.is_a?(String) and args[1].is_a?(EventHandlerSubscription)
+      elsif args.first.is_a?(String) and args[1].is_a?(EventHandlerSubscription::Base)
         subscription = args[1]
       else
         path, index = args[0..1]
@@ -258,7 +285,11 @@ module ZK
         callbacks.each do |cb|
           next unless cb.respond_to?(:call)
 
-          zk.defer { cb.call(*args) }
+          if cb.async?
+            cb.call(*args)
+          else
+            zk.defer { cb.call(*args) }
+          end
         end
       end
 

data/lib/zk/event_handler_subscription.rb

@@ -2,67 +2,31 @@ module ZK
   # the subscription object that is passed back from subscribing
   # to events.
   # @see ZK::Client::Base#register
-  class EventHandlerSubscription
-    # the event handler associated with this subscription
-    # @return [EventHandler]
-    attr_accessor :event_handler
-
-    # the path this subscription is for
-    # @return [String]
-    attr_accessor :path
-    
-    # the block associated with the path
-    # @return [Proc]
-    attr_accessor :callback
-
-    # an array of what kinds of events this handler is interested in receiving
-    #
-    # @return [Set] containing any combination of :create, :change, :delete,
-    #   or :children
-    #
-    # @private
-    attr_accessor :interests
-
-    ALL_EVENTS    = [:created, :deleted, :changed, :child].freeze unless defined?(ALL_EVENTS)
-    ALL_EVENT_SET = Set.new(ALL_EVENTS).freeze                    unless defined?(ALL_EVENT_SET)
+  module EventHandlerSubscription
 
     # @private
-    def initialize(event_handler, path, callback, interests)
-      @event_handler, @path, @callback = event_handler, path, callback
-      @interests = prep_interests(interests)
+    def self.class_for_thread_option(thopt)
+      case thopt
+      when :single
+        Base
+      when :per_callback
+        Actor
+      else
+        raise ArgumentError, "Unrecognized :thread option: #{thopt}"
+      end
     end
 
-    # unsubscribe from the path or state you were watching
-    # @see ZK::Client::Base#register
-    def unsubscribe
-      @event_handler.unregister(self)
-    end
-    alias :unregister :unsubscribe
+    def self.new(*a, &b)
+      opts = a.extract_options!
+ 
+      klass = class_for_thread_option(opts.delete(:thread))
 
-    # @private
-    def call(event)
-      callback.call(event)
+      a << opts
+      klass.new(*a, &b)
     end
-
-    private
-      def prep_interests(a)
-        return ALL_EVENT_SET if a.nil?
-
-        rval = 
-          case a
-          when Array
-            Set.new(a)
-          when Symbol
-            Set.new([a])
-          else
-            raise ArgumentError, "Don't know how to handle interests: #{a.inspect}" 
-          end
-
-        rval.tap do |rv|
-          invalid = (rv - ALL_EVENT_SET)
-          raise ArgumentError, "Invalid event name(s) #{invalid.to_a.inspect} given" unless invalid.empty?
-        end
-      end
   end
 end
 
+require 'zk/event_handler_subscription/base'
+require 'zk/event_handler_subscription/actor'
+

data/lib/zk/event_handler_subscription/actor.rb

@@ -0,0 +1,38 @@
+module ZK
+  module EventHandlerSubscription
+    # Stealing some ideas from Celluloid, this event handler subscription
+    # (basically, the wrapper around the user block), will spin up its own
+    # thread for delivery, and use a queue. This gives us the basis for better
+    # concurrency (event handlers run in parallel), but preserves the
+    # underlying behavior that a single-event-thread ZK gives us, which is that
+    # a single callback block is inherently serial. Without this, you have to
+    # make sure your callbacks are either synchronized, or totally reentrant,
+    # so that multiple threads could be calling your block safely (which is
+    # really difficult, and annoying).
+    #
+    # Using this delivery mechanism means that the block still must not block
+    # forever, however each event will "wait its turn" and all callbacks will
+    # receive their events in the same order (which is what ZooKeeper
+    # guarantees), just perhaps at different times.
+    #
+    class Actor < Base
+      extend Forwardable
+
+      def_delegators :@threaded_callback, :call
+
+      def initialize(*a)
+        super
+        @threaded_callback = ThreadedCallback.new(@callback)
+      end
+
+      def unsubscribe
+        @threaded_callback.shutdown
+        super
+      end
+
+      def async?
+        true
+      end
+    end
+  end
+end

data/lib/zk/event_handler_subscription/base.rb

@@ -0,0 +1,76 @@
+module ZK
+  module EventHandlerSubscription
+    class Base
+      include ZK::Logging
+
+      # the event handler associated with this subscription
+      # @return [EventHandler]
+      attr_accessor :event_handler
+
+      # the path this subscription is for
+      # @return [String]
+      attr_accessor :path
+      
+      # the block associated with the path
+      # @return [Proc]
+      attr_accessor :callback
+
+      # an array of what kinds of events this handler is interested in receiving
+      # this is the :only option, essentially
+      #
+      # @return [Set] containing any combination of :create, :change, :delete,
+      #   or :children
+      #
+      # @private
+      attr_accessor :interests
+
+      ALL_EVENTS    = [:created, :deleted, :changed, :child].freeze unless defined?(ALL_EVENTS)
+      ALL_EVENT_SET = Set.new(ALL_EVENTS).freeze                    unless defined?(ALL_EVENT_SET)
+
+      # @private
+      def initialize(event_handler, path, callback, opts={})
+        @event_handler, @path, @callback = event_handler, path, callback
+        @interests = prep_interests(opts[:only])
+      end
+
+      # unsubscribe from the path or state you were watching
+      # @see ZK::Client::Base#register
+      def unsubscribe
+        @event_handler.unregister(self)
+      end
+      alias :unregister :unsubscribe
+
+      # @private
+      def call(event)
+        callback.call(event)
+      end
+
+      # the Actor returns true for this
+      # @private
+      def async?
+        false
+      end
+
+      protected
+        def prep_interests(a)
+#           logger.debug { "prep_interests: #{a.inspect}" }
+          return ALL_EVENT_SET if a.nil?
+
+          rval = 
+            case a
+            when Array
+              Set.new(a)
+            when Symbol
+              Set.new([a])
+            else
+              raise ArgumentError, "Don't know how to handle interests: #{a.inspect}" 
+            end
+
+          rval.tap do |rv|
+            invalid = (rv - ALL_EVENT_SET)
+            raise ArgumentError, "Invalid event name(s) #{invalid.to_a.inspect} given" unless invalid.empty?
+          end
+        end
+    end # Base
+  end # EventHandlerSubscription
+end # ZK