zk 1.1.1 → 1.2.0

data/lib/zk/client/unixisms.rb

@@ -1,7 +1,7 @@
 module ZK
   module Client
     module Unixisms
-      include ZookeeperConstants
+      include Zookeeper::Constants
       include Exceptions
 
       # Creates all parent paths and 'path' in zookeeper as persistent nodes with
@@ -114,15 +114,15 @@ module ZK
       #   mixes in the InterruptedSession module will be raised, so for convenience,
       #   users can just rescue {InterruptedSession}.
       #
-      # @raise [ZookeeperExceptions::ZookeeperException::SessionExpired] raised
+      # @raise [Zookeeper::Exceptions::SessionExpired] raised
       #   when we receive `ZOO_EXPIRED_SESSION_STATE` while blocking waiting for
       #   a deleted event. Includes the {InterruptedSession} module.
       #
-      # @raise [ZookeeperExceptions::ZookeeperException::NotConnected] raised
+      # @raise [Zookeeper::Exceptions::NotConnected] raised
       #   when we receive `ZOO_CONNECTING_STATE` while blocking waiting for
       #   a deleted event. Includes the {InterruptedSession} module.
       #
-      # @raise [ZookeeperExceptions::ZookeeperException::ConnectionClosed] raised
+      # @raise [Zookeeper::Exceptions::ConnectionClosed] raised
       #   when we receive `ZOO_CLOSED_STATE` while blocking waiting for
       #   a deleted event. Includes the {InterruptedSession} module.
       #
@@ -162,11 +162,11 @@ module ZK
         when :deleted
           true
         when ZOO_EXPIRED_SESSION_STATE
-          raise ZookeeperExceptions::ZookeeperException::SessionExpired
+          raise Zookeeper::Exceptions::SessionExpired
         when ZOO_CONNECTING_STATE
-          raise ZookeeperExceptions::ZookeeperException::NotConnected
+          raise Zookeeper::Exceptions::NotConnected
         when ZOO_CLOSED_STATE
-          raise ZookeeperExceptions::ZookeeperException::ConnectionClosed
+          raise Zookeeper::Exceptions::ConnectionClosed
         else
           raise "Hit unexpected case in block_until_node_deleted"
         end

data/lib/zk/core_ext.rb

@@ -73,3 +73,29 @@ module ::Kernel
   end
 end
 
+# @private
+class ::Module
+  unless method_defined?(:alias_method_chain)
+    def alias_method_chain(target, feature)
+      # Strip out punctuation on predicates or bang methods since
+      # e.g. target?_without_feature is not a valid method name.
+      aliased_target, punctuation = target.to_s.sub(/([?!=])$/, ''), $1
+      yield(aliased_target, punctuation) if block_given?
+
+      with_method, without_method = "#{aliased_target}_with_#{feature}#{punctuation}", "#{aliased_target}_without_#{feature}#{punctuation}"
+
+      alias_method without_method, target
+      alias_method target, with_method
+
+      case
+        when public_method_defined?(without_method)
+          public target
+        when protected_method_defined?(without_method)
+          protected target
+        when private_method_defined?(without_method)
+          private target
+      end
+    end
+  end
+end
+

data/lib/zk/event.rb

@@ -1,10 +1,10 @@
 module ZK
   # Provides most of the functionality ZK uses around events. Base class is actually
-  # [ZookeeperCallbacks::WatcherCallback](http://rubydoc.info/gems/slyphon-zookeeper/ZookeeperCallbacks/WatcherCallback),
+  # [Zookeeper::Callbacks::WatcherCallback](http://rubydoc.info/gems/slyphon-zookeeper/Zookeeper::Callbacks/WatcherCallback),
   # but this module is mixed in and provides a lot of useful syntactic sugar.
   #
   module Event
-    include ZookeeperConstants
+    include Zookeeper::Constants
 
     # unless defined? apparently messes up yard's ability to see the @private
     silence_warnings do
@@ -26,10 +26,10 @@ module ZK
       EVENT_TYPES = %w[created deleted changed child session notwatching].freeze 
     end
 
-    # for testing, create a new ZookeeperCallbacks::WatcherCallback and return it
+    # for testing, create a new Zookeeper::Callbacks::WatcherCallback and return it
     # @private
     def self.new(hash)
-      ZookeeperCallbacks::WatcherCallback.new.tap do |wc|
+      Zookeeper::Callbacks::WatcherCallback.new.tap do |wc|
         wc.call(hash)
       end
     end
@@ -170,7 +170,7 @@ module ZK
 end
 
 # @private
-class ZookeeperCallbacks::WatcherCallback
+Zookeeper::Callbacks::WatcherCallback.class_eval do
   include ::ZK::Event
 end
 

data/lib/zk/event_handler.rb

@@ -257,7 +257,7 @@ module ZK
     protected
       # @private
       def watcher_callback
-        ZookeeperCallbacks::WatcherCallback.create { |event| process(event) }
+        Zookeeper::Callbacks::WatcherCallback.create { |event| process(event) }
       end
 
       # @private
@@ -265,7 +265,7 @@ module ZK
         int = 
           case arg
           when String, Symbol
-            ZookeeperConstants.const_get(:"ZOO_#{arg.to_s.upcase}_STATE")
+            Zookeeper::Constants.const_get(:"ZOO_#{arg.to_s.upcase}_STATE")
           when Integer
             arg
           else

data/lib/zk/event_handler_subscription/actor.rb

@@ -16,19 +16,7 @@ module ZK
     # 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
+      include Subscription::ActorStyle
 
       def async?
         true

data/lib/zk/event_handler_subscription/base.rb

@@ -1,19 +1,15 @@
 module ZK
   module EventHandlerSubscription
-    class Base
+    class Base < Subscription::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
+#       attr_accessor :callback
 
       # an array of what kinds of events this handler is interested in receiving
       # this is the :only option, essentially
@@ -24,26 +20,30 @@ module ZK
       # @private
       attr_accessor :interests
 
+      alias event_handler parent
+      alias callback callable
+
       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
+        super(event_handler, callback)
+        @path = path
         @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
+#       def unsubscribe
+#         @event_handler.unregister(self)
+#       end
+#       alias :unregister :unsubscribe
 
-      # @private
-      def call(event)
-        callback.call(event)
-      end
+#       # @private
+#       def call(event)
+#         callback.call(event)
+#       end
 
       # the Actor returns true for this
       # @private

data/lib/zk/exceptions.rb

@@ -126,6 +126,9 @@ module ZK
     # raised when someone performs a blocking ZK operation on the event dispatch thread. 
     class EventDispatchThreadException < ZKError; end
 
+    # raised when someone calls lock.assert! but they do not hold the lock
+    class LockAssertionFailedError < ZKError; end
+
     # raised when a chrooted conection is requested but the root doesn't exist
     class ChrootPathDoesNotExistError < NoNode
       def initialize(host_string, chroot_path)

data/lib/zk/extensions.rb

@@ -30,49 +30,20 @@ module ZK
       end
     end
   end
-
-  module Extensions
-    # some extensions to the ZookeeperCallbacks classes, mainly convenience
-    # interrogators
-    module Callbacks
-      module Callback
-        extend Concern
-
-        # allow access to the connection that fired this callback
-        attr_accessor :zk
-
-        module ClassMethods
-          # allows for easier construction of a user callback block that will be
-          # called with the callback object itself as an argument. 
-          #
-          # *args, if given, will be passed on *after* the callback
-          #
-          # @example
-          #   
-          #   WatcherCallback.create do |cb|
-          #     puts "watcher callback called with argument: #{cb.inspect}"
-          #   end
-          #
-          #   "watcher callback called with argument: #<ZookeeperCallbacks::WatcherCallback:0x1018a3958 @state=3, @type=1, ...>"
-          #
-          #
-          def create(*args, &block)
-            cb_inst = new { block.call(cb_inst) }
-          end
-        end
-      end # Callback
-    end   # Callbacks
-  end # Extensions
 end # ZK
 
-# ZookeeperCallbacks::Callback.extend(ZK::Extensions::Callbacks::Callback)
-ZookeeperCallbacks::Callback.send(:include, ZK::Extensions::Callbacks::Callback)
+Zookeeper::Callbacks::Base.class_eval do
+  # allows us to stick a reference to the connection associated with the event
+  # on the event
+  attr_accessor :zk
+end
+
 
-# Include the InterruptedSession module in key ZookeeperExceptions to allow
+# Include the InterruptedSession module in key Zookeeper::Exceptions to allow
 # clients to catch a single error type when waiting on a node (for example)
 
 [:ConnectionClosed, :NotConnected, :SessionExpired, :SessionMoved, :ConnectionLoss].each do |class_name|
-  ZookeeperExceptions::ZookeeperException.const_get(class_name).tap do |klass|
+  Zookeeper::Exceptions.const_get(class_name).tap do |klass|
     klass.__send__(:include, ZK::Exceptions::InterruptedSession)
   end
 end

data/lib/zk/locker.rb

@@ -93,6 +93,14 @@ module ZK
     SHARED_LOCK_PREFIX  = 'sh'.freeze
     EXCLUSIVE_LOCK_PREFIX = 'ex'.freeze
 
+    @default_root_lock_node = '/_zklocking'.freeze unless @default_root_lock_node
+
+    class << self
+      # the default root path we will use when a value is not given to a
+      # constructor
+      attr_accessor :default_root_lock_node
+    end
+
     # Create a {SharedLocker} instance
     #
     # @param client (see LockerBase#initialize)

data/lib/zk/locker/exclusive_locker.rb

@@ -14,17 +14,10 @@ module ZK
     #       * __no__: return false, you lose
     # 
     class ExclusiveLocker < LockerBase
+      # (see LockerBase#lock)
       # obtain an exclusive lock.
       #
-      # @param blocking (see SharedLocker#lock!)
-      # @return (see SharedLocker#lock!)
-      #
-      # @raise [InterruptedSession] raised when blocked waiting for a lock and
-      #   the underlying client's session is interrupted. 
-      #
-      # @see ZK::Client::Unixisms#block_until_node_deleted more about possible execptions
-      # 
-      def lock!(blocking=false)
+      def lock(blocking=false)
         return true if @locked
         create_lock_path!(EXCLUSIVE_LOCK_PREFIX)
 
@@ -40,10 +33,31 @@ module ZK
         end
       end
 
+      # (see LockerBase#assert!)
+      #
+      # checks that we:
+      #
+      # * we have obtained the lock (i.e. {#locked?} is true)
+      # * have a lock path
+      # * our lock path still exists
+      # * there are no locks, _exclusive or shared_, with lower numbers than ours
+      # 
+      def assert!
+        super
+      end
+
+      # (see LockerBase#acquirable?)
+      def acquirable?
+        return true if locked? 
+        stat = zk.stat(root_lock_path)
+        !stat.exists? or stat.num_children == 0
+      rescue Exceptions::NoNode
+        true
+      end
+
       protected
         # the node that is next-lowest in sequence number to ours, the one we
         # watch for updates to
-        # @private
         def next_lowest_node
           ary = ordered_lock_children()
           my_idx = ary.index(lock_basename)
@@ -53,12 +67,11 @@ module ZK
           ary[(my_idx - 1)] 
         end
 
-        # @private
         def got_write_lock?
           ordered_lock_children.first == lock_basename
         end
+        alias got_lock? got_write_lock?
 
-        # @private
         def block_until_write_lock!
           begin
             path = [root_lock_path, next_lowest_node].join('/')

data/lib/zk/locker/locker_base.rb

@@ -9,6 +9,7 @@ module ZK
     #
     class LockerBase
       include ZK::Logging
+      include ZK::Exceptions
 
       # @private
       attr_accessor :zk
@@ -42,14 +43,15 @@ module ZK
       #   holding the same lock.
       #
       # @param [String] root_lock_node the root path on the server under which all
-      #   locks will be generated
+      #   locks will be generated, the default is Locker.default_root_lock_node
       #
-      def initialize(client, name, root_lock_node = "/_zklocking") 
+      def initialize(client, name, root_lock_node=nil) 
         @zk = client
-        @root_lock_node = root_lock_node
+        @root_lock_node = root_lock_node || Locker.default_root_lock_node
         @path = name
         @locked = false
         @waiting = false
+        @lock_path = nil
         @root_lock_path = "#{@root_lock_node}/#{@path.gsub("/", "__")}"
       end
       
@@ -58,10 +60,10 @@ module ZK
       # there is no non-blocking version of this method
       #
       def with_lock
-        lock!(true)
+        lock(true)
         yield
       ensure
-        unlock!
+        unlock
       end
 
       # the basename of our lock path
@@ -79,9 +81,36 @@ module ZK
         lock_path and File.basename(lock_path)
       end
 
-      # @return [true,false] true if we hold the lock
-      def locked?
-        false|@locked
+      # returns our current idea of whether or not we hold the lock, which does
+      # not actually check the state on the server.
+      #
+      # The reason for the equivocation around _thinking_ we hold the lock is
+      # to contrast our current state and the actual state on the server. If you
+      # want to make double-triple certain of the state of the lock, use {#assert!}
+      #
+      # @return [true] if we hold the lock
+      # @return [false] if we don't hold the lock
+      #
+      def locked?(check_if_any=false)
+        false|@locked 
+      end
+
+      # * If this instance holds the lock {#locked? is true} we return true (as
+      #   we have already succeeded in acquiring the lock)
+      # * If this instance doesn't hold the lock, we'll do a check on the server 
+      #   to see if there are any participants _who hold the lock and would
+      #   prevent us from acquiring the lock_. 
+      #   * If this instance could acquire the lock we will return true. 
+      #   * If another client would prevent us from acquiring the lock, we return false. 
+      #
+      # @note It should be obvious, but there is no way to guarantee that
+      #   between the time this method checks the server and taking any action to
+      #   acquire the lock, another client may grab the lock before us (or
+      #   converseley, another client may release the lock). This is simply meant
+      #   as an advisory, and may be useful in some cases.
+      #
+      def acquirable?
+        raise NotImplementedError
       end
       
       # @return [true] if we held the lock and this method has
@@ -89,7 +118,7 @@ module ZK
       #
       # @return [false] we did not own the lock
       #
-      def unlock!
+      def unlock
         if @locked
           cleanup_lock_path!
           @locked = false
@@ -99,6 +128,38 @@ module ZK
         end
       end
 
+      # (see #unlock)
+      # @deprecated the use of unlock! is deprecated and may be removed or have
+      #   its semantics changed in a future release
+      def unlock!
+        unlock
+      end
+
+      # @param blocking [true,false] if true we block the caller until we can obtain
+      #   a lock on the resource
+      # 
+      # @return [true] if we're already obtained a shared lock, or if we were able to
+      #   obtain the lock in non-blocking mode.
+      #
+      # @return [false] if we did not obtain the lock in non-blocking mode
+      #
+      # @return [void] if we obtained the lock in blocking mode. 
+      #
+      # @raise [InterruptedSession] raised when blocked waiting for a lock and
+      #   the underlying client's session is interrupted. 
+      #
+      # @see ZK::Client::Unixisms#block_until_node_deleted more about possible execptions
+      def lock(blocking=false)
+        raise NotImplementedError
+      end
+
+      # (see #lock)
+      # @deprecated the use of lock! is deprecated and may be removed or have
+      #   its semantics changed in a future release
+      def lock!(blocking=false)
+        lock(blocking)
+      end
+
       # returns true if this locker is waiting to acquire lock 
       #
       # @private
@@ -106,8 +167,43 @@ module ZK
         false|@waiting
       end
 
+      # This is for users who wish to check that the assumption is correct
+      # that they actually still hold the lock. (check for session interruption,
+      # perhaps a lock is obtained in one method and handed to another)
+      #
+      # This, unlike {#locked?} will actually go and check the conditions
+      # that constitute "holding the lock" with the server.
+      #
+      # @raise [InterruptedSession] raised when the zk session has either
+      #   closed or is in an invalid state.
+      #
+      # @raise [LockAssertionFailedError] raised if the lock is not held
+      #
+      # @example 
+      #   
+      #   def process_jobs
+      #     @lock.with_lock do
+      #       @jobs.each do |j| 
+      #         @lock.assert!
+      #         perform_job(j)
+      #       end
+      #     end
+      #   end
+      #
+      #   def perform_job(j)
+      #     puts "hah! he thinks we're workin!"
+      #     sleep(60)
+      #   end
+      #
+      def assert!
+        raise LockAssertionFailedError, "have not obtained the lock yet"            unless locked?
+        raise LockAssertionFailedError, "not connected"                             unless zk.connected?
+        raise LockAssertionFailedError, "lock_path was #{lock_path.inspect}"        unless lock_path
+        raise LockAssertionFailedError, "the lock path #{lock_path} did not exist!" unless zk.exists?(lock_path)
+        raise LockAssertionFailedError, "we do not actually hold the lock"          unless got_lock?
+      end
+
       protected 
-        # @private
         def in_waiting_status
           w, @waiting = @waiting, true
           yield
@@ -115,46 +211,53 @@ module ZK
           @waiting = w
         end
 
-        # @private
         def digit_from(path)
           self.class.digit_from_lock_path(path)
         end
 
-        # @private
+        # possibly lighter weight check to see if the lock path has any children
+        # (using stat, rather than getting the list of children).
+        def any_lock_children?
+        end
+
         def lock_children(watch=false)
-          @zk.children(root_lock_path, :watch => watch)
+          zk.children(root_lock_path, :watch => watch)
         end
 
-        # @private
         def ordered_lock_children(watch=false)
           lock_children(watch).tap do |ary|
             ary.sort! { |a,b| digit_from(a) <=> digit_from(b) }
           end
         end
 
-        # @private
         def create_root_path!
-          @zk.mkdir_p(@root_lock_path)
+          zk.mkdir_p(@root_lock_path)
+        end
+
+        # performs the checks that (according to the recipe) mean that we hold
+        # the lock. used by (#assert!)
+        #
+        def got_lock?
+          raise NotImplementedError
         end
 
         # prefix is the string that will appear in front of the sequence num,
         # defaults to 'lock'
         #
-        # @private
         def create_lock_path!(prefix='lock')
           @lock_path = @zk.create("#{root_lock_path}/#{prefix}", "", :mode => :ephemeral_sequential)
           logger.debug { "got lock path #{@lock_path}" }
           @lock_path
-        rescue Exceptions::NoNode
+        rescue NoNode
           create_root_path!
           retry
         end
 
-        # @private
         def cleanup_lock_path!
           logger.debug { "removing lock path #{@lock_path}" }
-          @zk.delete(@lock_path)
-          @zk.delete(root_lock_path) rescue Exceptions::NotEmpty
+          zk.delete(@lock_path)
+          zk.delete(root_lock_path) rescue NotEmpty
+          @lock_path = nil
         end
     end # LockerBase
   end # Locker