zk 0.6.5 → 0.7.1

data/lib/z_k/client/conveniences.rb

@@ -0,0 +1,134 @@
+module ZK
+  module Client
+    module Conveniences
+      # Queue an operation to be run on an internal threadpool. You may either
+      # provide an object that responds_to?(:call) or pass a block. There is no
+      # mechanism for retrieving the result of the operation, it is purely
+      # fire-and-forget, so the user is expected to make arrangements for this in
+      # their code. 
+      #
+      # An ArgumentError will be raised if +callable+ does not <tt>respond_to?(:call)</tt>
+      #
+      # ==== Arguments
+      # * <tt>callable</tt>: an object that <tt>respond_to?(:call)</tt>, takes precedence
+      #   over a given block
+      #
+      def defer(callable=nil, &block)
+        @threadpool.defer(callable, &block)
+      end
+      
+      # does a stat on '/', rescues all zookeeper-protocol exceptions
+      #
+      # @private intended for use in monitoring scripts
+      # @return [bool]
+      def ping?
+        false unless connected?
+        false|stat('/')
+      rescue ZK::Exceptions::KeeperException
+        false
+      end
+
+
+      #--
+      #
+      # EXTENSIONS
+      #
+      # convenience methods for dealing with zookeeper (rm -rf, mkdir -p, etc)
+      #
+      #++
+      
+      # creates a new locker based on the name you send in
+      #
+      # see ZK::Locker::ExclusiveLocker
+      #
+      # returns a ZK::Locker::ExclusiveLocker instance using this Client and provided
+      # lock name
+      #
+      # ==== Arguments
+      # * <tt>name</tt> name of the lock you wish to use
+      #
+      # ==== Examples
+      #
+      #   zk.locker("blah")
+      #   # => #<ZK::Locker::ExclusiveLocker:0x102034cf8 ...>
+      #
+      def locker(name)
+        Locker.exclusive_locker(self, name)
+      end
+
+      # create a new shared locking instance based on the name given
+      #
+      # returns a ZK::Locker::SharedLocker instance using this Client and provided
+      # lock name
+      #
+      # ==== Arguments
+      # * <tt>name</tt> name of the lock you wish to use
+      #
+      # ==== Examples
+      #
+      #   zk.shared_locker("blah")
+      #   # => #<ZK::Locker::SharedLocker:0x102034cf8 ...>
+      #
+      def shared_locker(name)
+        Locker.shared_locker(self, name)
+      end
+
+      # Convenience method for acquiring a lock then executing a code block. This
+      # will block the caller until the lock is acquired.
+      #
+      # ==== Arguments
+      # * <tt>name</tt>: the name of the lock to use
+      # * <tt>:mode</tt>: either :shared or :exclusive, defaults to :exclusive
+      #
+      # ==== Examples
+      #
+      #   zk.with_lock('foo') do
+      #     # this code is executed while holding the lock
+      #   end
+      #
+      def with_lock(name, opts={}, &b)
+        mode = opts[:mode] || :exclusive
+
+        raise ArgumentError, ":mode option must be either :shared or :exclusive, not #{mode.inspect}" unless [:shared, :exclusive].include?(mode)
+
+        if mode == :shared
+          shared_locker(name).with_lock(&b)
+        else
+          locker(name).with_lock(&b)
+        end
+      end
+
+      # Convenience method for constructing a ZK::Election::Candidate object using this 
+      # Client connection, the given election +name+ and +data+.
+      #
+      def election_candidate(name, data, opts={})
+        opts = opts.merge(:data => data)
+        ZK::Election::Candidate.new(self, name, opts)
+      end
+
+      # Convenience method for constructing a ZK::Election::Observer object using this 
+      # Client connection, and the given election +name+.
+      #
+      def election_observer(name, opts={})
+        ZK::Election::Observer.new(self, name, opts)
+      end
+
+      # creates a new message queue of name +name+
+      #
+      # returns a ZK::MessageQueue object
+      #
+      # ==== Arguments
+      # * <tt>name</tt> the name of the queue
+      #
+      # ==== Examples
+      #
+      #   zk.queue("blah").publish({:some_data => "that is yaml serializable"})
+      #
+      def queue(name)
+        MessageQueue.new(self, name)
+      end
+
+    end # Conveniences
+  end   # Client
+end     # ZK
+

data/lib/z_k/client/state_mixin.rb

@@ -0,0 +1,94 @@
+module ZK
+  module Client
+    # Provides client-state related methods. Included in ZK::Client::Base.
+    # (refactored out to this class to ease documentation overload)
+    module StateMixin
+      # Returns true if the underlying connection is in the +connected+ state.
+      def connected?
+        wrap_state_closed_error { cnx and cnx.connected? }
+      end
+
+      # is the underlying connection is in the +associating+ state?
+      # @return [bool]
+      def associating?
+        wrap_state_closed_error { cnx and cnx.associating? }
+      end
+
+      # is the underlying connection is in the +connecting+ state?
+      # @return [bool]
+      def connecting?
+        wrap_state_closed_error { cnx and cnx.connecting? }
+      end
+      
+      # is the underlying connection is in the +expired_session+ state?
+      # @return [bool]
+      def expired_session?
+        return nil unless @cnx
+
+        if defined?(::JRUBY_VERSION)
+          cnx.state == Java::OrgApacheZookeeper::ZooKeeper::States::EXPIRED_SESSION
+        else
+          wrap_state_closed_error { cnx.state == Zookeeper::ZOO_EXPIRED_SESSION_STATE }
+        end
+      end
+
+      # returns the current state of the connection as reported by the underlying driver
+      # as a symbol. The possible values are <tt>[:closed, :expired_session, :auth_failed
+      # :connecting, :connected, :associating]</tt>. 
+      #
+      # See the Zookeeper session 
+      # {documentation}[http://hadoop.apache.org/zookeeper/docs/current/zookeeperProgrammers.html#ch_zkSessions]
+      # for more information
+      #
+      def state
+        if defined?(::JRUBY_VERSION) 
+          cnx.state.to_string.downcase.to_sym
+        else
+          STATE_SYM_MAP.fetch(cnx.state) { |k| raise IndexError, "unrecognized state: #{k}" }
+        end
+      end
+
+      # @private
+      #
+      # Register a block to be called on connection, when the client has
+      # connected. 
+      # 
+      # the block will be called with no arguments
+      #
+      # returns an EventHandlerSubscription object that can be used to unregister
+      # this block from further updates
+      #
+      def on_connected(&block)
+        watcher.register_state_handler(:connected, &block)
+      end
+
+      # register a block to be called when the client is attempting to reconnect
+      # to the zookeeper server. the documentation says that this state should be
+      # taken to mean that the application should enter into "safe mode" and operate
+      # conservatively, as it won't be getting updates until it has reconnected
+      #
+      def on_connecting(&block)
+        watcher.register_state_handler(:connecting, &block)
+      end
+
+      # register a block to be called when our session has expired. This usually happens
+      # due to a network partitioning event, and means that all callbacks and watches must
+      # be re-registered with the server
+      #
+      # @todo need to come up with a way to test this
+      def on_expired_session(&block)
+        watcher.register_state_handler(:expired_session, &block)
+      end
+
+      protected
+        def wrap_state_closed_error
+          yield
+        rescue RuntimeError => e
+          # gah, lame error parsing here
+          raise e unless e.message == 'zookeeper handle is closed'
+          false
+        end
+    end
+  end
+end
+

data/lib/z_k/client/unixisms.rb

@@ -0,0 +1,89 @@
+module ZK
+  module Client
+    module Unixisms
+      # Creates all parent paths and 'path' in zookeeper as persistent nodes with
+      # zero data.
+      #
+      # ==== Arguments
+      # * <tt>path</tt>: An absolute znode path to create
+      #
+      # ==== Examples
+      #
+      #   zk.exists?('/path')
+      #   # => false
+      # 
+      #   zk.mkdir_p('/path/to/blah')
+      #   # => "/path/to/blah"  
+      #
+      #--
+      # TODO: write a non-recursive version of this. ruby doesn't have TCO, so
+      # this could get expensive w/ psychotically long paths
+      def mkdir_p(path)
+        create(path, '', :mode => :persistent)
+      rescue Exceptions::NodeExists
+        return
+      rescue Exceptions::NoNode
+        if File.dirname(path) == '/'
+          # ok, we're screwed, blow up
+          raise KeeperException, "could not create '/', something is wrong", caller
+        end
+
+        mkdir_p(File.dirname(path))
+        retry
+      end
+
+      # recursively remove all children of path then remove path itself
+      def rm_rf(paths)
+        Array(paths).flatten.each do |path|
+          begin
+            children(path).each do |child|
+              rm_rf(File.join(path, child))
+            end
+
+            delete(path)
+            nil
+          rescue Exceptions::NoNode
+          end
+        end
+      end
+
+      # see ZK::Find for explanation
+      def find(*paths, &block)
+        ZK::Find.find(self, *paths, &block)
+      end
+
+      # will block the caller until +abs_node_path+ has been removed
+      #
+      # @private this method is of dubious value and may be removed in a later
+      #   version
+      #
+      # @note this is dangerous to use in callbacks! there is only one
+      #   event-delivery thread, so if you use this method in a callback or
+      #   watcher, you *will* deadlock!
+      def block_until_node_deleted(abs_node_path)
+        queue = Queue.new
+        ev_sub = nil
+
+        node_deletion_cb = lambda do |event|
+          if event.node_deleted?
+            queue.enq(:deleted) 
+          else
+            queue.enq(:deleted) unless exists?(abs_node_path, :watch => true)
+          end
+        end
+
+        ev_sub = watcher.register(abs_node_path, &node_deletion_cb)
+
+        # set up the callback, but bail if we don't need to wait
+        return true unless exists?(abs_node_path, :watch => true)  
+
+        queue.pop # block waiting for node deletion
+        true
+      ensure
+        # be sure we clean up after ourselves
+        ev_sub.unregister if ev_sub
+      end
+    end
+  end
+end
+