zk 0.9.1 → 1.0.0.rc.1

data/lib/zk/event_handler_subscription.rb

@@ -0,0 +1,68 @@
+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)
+
+    # @private
+    def initialize(event_handler, path, callback, interests)
+      @event_handler, @path, @callback = event_handler, path, callback
+      @interests = prep_interests(interests)
+    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
+
+    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
+

data/lib/{z_k → zk}/exceptions.rb

@@ -1,27 +1,29 @@
 module ZK
   module Exceptions
-    OK                      = 0
-    # System and server-side errors
-    SYSTEMERROR             = -1
-    RUNTIMEINCONSISTENCY    = SYSTEMERROR - 1
-    DATAINCONSISTENCY       = SYSTEMERROR - 2
-    CONNECTIONLOSS          = SYSTEMERROR - 3
-    MARSHALLINGERROR        = SYSTEMERROR - 4
-    UNIMPLEMENTED           = SYSTEMERROR - 5
-    OPERATIONTIMEOUT        = SYSTEMERROR - 6
-    BADARGUMENTS            = SYSTEMERROR - 7
-    # API errors  
-    APIERROR                = -100; 
-    NONODE                  = APIERROR - 1 # Node does not exist
-    NOAUTH                  = APIERROR - 2 # Current operation not permitted
-    BADVERSION              = APIERROR - 3 # Version conflict
-    NOCHILDRENFOREPHEMERALS = APIERROR - 8
-    NODEEXISTS              = APIERROR - 10
-    NOTEMPTY                = APIERROR - 11
-    SESSIONEXPIRED          = APIERROR - 12
-    INVALIDCALLBACK         = APIERROR - 13
-    INVALIDACL              = APIERROR - 14
-    AUTHFAILED              = APIERROR - 15 # client authentication failed
+    silence_warnings do
+      OK                      = 0
+      # System and server-side errors
+      SYSTEMERROR             = -1
+      RUNTIMEINCONSISTENCY    = SYSTEMERROR - 1
+      DATAINCONSISTENCY       = SYSTEMERROR - 2
+      CONNECTIONLOSS          = SYSTEMERROR - 3
+      MARSHALLINGERROR        = SYSTEMERROR - 4
+      UNIMPLEMENTED           = SYSTEMERROR - 5
+      OPERATIONTIMEOUT        = SYSTEMERROR - 6
+      BADARGUMENTS            = SYSTEMERROR - 7
+      # API errors  
+      APIERROR                = -100; 
+      NONODE                  = APIERROR - 1 # Node does not exist
+      NOAUTH                  = APIERROR - 2 # Current operation not permitted
+      BADVERSION              = APIERROR - 3 # Version conflict
+      NOCHILDRENFOREPHEMERALS = APIERROR - 8
+      NODEEXISTS              = APIERROR - 10
+      NOTEMPTY                = APIERROR - 11
+      SESSIONEXPIRED          = APIERROR - 12
+      INVALIDCALLBACK         = APIERROR - 13
+      INVALIDACL              = APIERROR - 14
+      AUTHFAILED              = APIERROR - 15 # client authentication failed
+    end
 
 
     # these errors are returned rather than the driver level errors
@@ -92,7 +94,7 @@ module ZK
       INVALIDCALLBACK         => InvalidCallback,
       INVALIDACL              => InvalidACL,
       AUTHFAILED              => AuthFailed,
-    }
+    }.freeze unless defined?(ERROR_MAP)
 
     # base class of ZK generated errors (not driver-level errors)
     class ZKError < StandardError; end
@@ -120,6 +122,19 @@ module ZK
 
     # raised when someone performs a blocking ZK operation on the event dispatch thread. 
     class EventDispatchThreadException < ZKError; end
+
+    # raised when a chrooted conection is requested but the root doesn't exist
+    class ChrootPathDoesNotExistError < NoNode
+      def initialize(host_string, chroot_path)
+        super("Chrooted connection to #{host_string} at #{chroot_path} requested, but path did not exist")
+      end
+    end
+
+    class ChrootMustStartWithASlashError < ArgumentError
+      def initialize(erroneous_string)
+        super("Chroot strings must start with a '/' you provided: #{erroneous_string.inspect}")
+      end
+    end
   end
 end
 

data/lib/zk/extensions.rb

@@ -0,0 +1,79 @@
+module ZK
+  # this is taken from activesupport-3.2.3, and pasted here so that we don't conflict if someone
+  # is using us as part of a rails app
+  #
+  # i've removed the code that includes InstanceMethods (tftfy)
+  # @private
+  module Concern
+    def self.extended(base)
+      base.instance_variable_set("@_dependencies", [])
+    end
+
+    def append_features(base)
+      if base.instance_variable_defined?("@_dependencies")
+        base.instance_variable_get("@_dependencies") << self
+        return false
+      else
+        return false if base < self
+        @_dependencies.each { |dep| base.send(:include, dep) }
+        super
+        base.extend const_get("ClassMethods") if const_defined?("ClassMethods")
+        base.class_eval(&@_included_block) if instance_variable_defined?("@_included_block")
+      end
+    end
+
+    def included(base = nil, &block)
+      if base.nil?
+        @_included_block = block
+      else
+        super
+      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)
+
+# Include the InterruptedSession module in key ZookeeperExceptions 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|
+    klass.__send__(:include, ZK::Exceptions::InterruptedSession)
+  end
+end
+

data/lib/{z_k → zk}/message_queue.rb

@@ -13,7 +13,6 @@ module ZK
   #     #handle message
   #   end
   class MessageQueue
-
     # @private
     # :nodoc:
     attr_accessor :zk
@@ -79,15 +78,19 @@ module ZK
     #   the message
     def subscribe(&block)
       @subscription_block = block
-      @subscription_reference = @zk.watcher.subscribe(full_queue_path) do |event, zk|
+      @sub = @zk.register(full_queue_path) do |event, zk|
         find_and_process_next_available(@zk.children(full_queue_path, :watch => true))
       end
+
       find_and_process_next_available(@zk.children(full_queue_path, :watch => true))
     end
 
     # stop listening to this queue
     def unsubscribe
-      @subscription_reference.unsubscribe
+      if @sub
+        @sub.unsubscribe
+        @sub = nil
+      end
     end
 
     # a list of the message titles in the queue
@@ -98,6 +101,7 @@ module ZK
     # highly destructive method!
     # WARNING! Will delete the queue and all messages in it
     def destroy!
+      unsubscribe  # first thing, make sure we don't get any callbacks related to this
       children = @zk.children(full_queue_path)
       locks = []
       children.each do |path|
@@ -120,7 +124,7 @@ module ZK
       messages.each do |message_title|
         message_path = "#{full_queue_path}/#{message_title}"
         locker = @zk.locker(message_path)
-        if locker.lock!
+        if locker.lock! # non-blocking lock
           begin
             data = @zk.get(message_path).first
             result = @subscription_block.call(message_title, data)

data/lib/zk/stat.rb

@@ -0,0 +1,115 @@
+module ZK
+  # Included in ZookeeperStat::Stat, extends it with some conveniences for 
+  # dealing with Stat objects. Also provides docuemntation here for the meaning
+  # of these values.
+  #
+  # Some of the methods added are to match the names in [the documentation][]
+  #
+  # Some of this may eventually be pushed down to slyphon-zookeeper
+  #
+  # [the documentation]: http://zookeeper.apache.org/doc/r3.3.5/zookeeperProgrammers.html#sc_zkStatStructure
+  module Stat
+    MEMBERS = [:version, :exists, :czxid, :mzxid, :ctime, :mtime, :cversion, :aversion, :ephemeralOwner, :dataLength, :numChildren, :pzxid].freeze
+
+    def ==(other)
+      MEMBERS.all? { |m| self.__send__(m) == other.__send__(m) }
+    end
+
+    # returns true if the node is ephemeral (will be cleaned up when the
+    # current session expires)
+    def ephemeral?
+      ephemeral_owner && (ephemeral_owner != 0)
+    end
+
+    # The zxid of the change that caused this znode to be created.
+    #
+    # (also: czxid)
+    def created_zxid
+      # @!parse alias czxid created_zxid
+      czxid
+    end
+
+    # The zxid of the change that last modified this znode.
+    #
+    # (also: mzxid)
+    def last_modified_zxid
+      mzxid
+    end
+
+    # The time in milliseconds from epoch when this znode was created
+    # 
+    # (also: created\_time)
+    #
+    # @return [Fixnum] 
+    # @see #ctime_t 
+    def created_time
+      ctime
+    end
+
+    # The time when this znode was created
+    #
+    # @return [Time] creation time of this znode
+    def ctime_t
+      Time.at(ctime * 0.001)
+    end
+
+    # The time in milliseconds from epoch when this znode was last modified.
+    #
+    # (also: mtime)
+    # @return [Fixnum]
+    # @see #mtime_t
+    def last_modified_time
+      mtime
+    end
+
+    # The time when this znode was last modified
+    #
+    # @return [Time] last modification time of this znode
+    # @see #last_modified_time
+    def mtime_t
+      Time.at(mtime * 0.001)
+    end
+
+    # The number of changes to the children of this znode
+    #
+    # (also: #cversion)
+    # @return [Fixnum]
+    def child_list_version
+      cversion
+    end
+
+    # The number of changes to the ACL of this znode.
+    #
+    # (also: #aversion)
+    # @return [Fixnum]
+    def acl_list_version
+      aversion
+    end
+
+    # The number of changes to the data of this znode.
+    #
+    # @return [Fixnum]
+    def version
+      super
+    end
+
+    # The length of the data field of this znode.
+    #
+    # @return [Fixnum]
+    def data_length
+      super
+    end
+
+    # The number of children of this znode.
+    #
+    # @return [Fixnum]
+    def num_children
+      super
+    end
+  end # Stat
+end # ZK
+
+class ZookeeperStat::Stat
+  include ZK::Stat
+end
+

data/lib/{z_k → zk}/threadpool.rb

@@ -22,6 +22,8 @@ module ZK
 
       @mutex = Mutex.new
 
+      @error_callbacks = []
+
       start!
     end
 
@@ -35,7 +37,7 @@ module ZK
       callable ||= blk
 
       # XXX(slyphon): do we care if the threadpool is not running?
-      raise Exceptions::ThreadpoolIsNotRunningException unless running?
+#       raise Exceptions::ThreadpoolIsNotRunningException unless running?
       raise ArgumentError, "Argument to Threadpool#defer must respond_to?(:call)" unless callable.respond_to?(:call)
 
       @threadqueue << callable
@@ -46,6 +48,12 @@ module ZK
       @mutex.synchronize { @running }
     end
 
+    # returns true if the current thread is one of the threadpool threads
+    def on_threadpool?
+      tp = @mutex.synchronize { @threadpool.dup }
+      tp and tp.respond_to?(:include?) and tp.include?(Thread.current)
+    end
+
     # starts the threadpool if not already running
     def start!
       @mutex.synchronize do
@@ -56,6 +64,18 @@ module ZK
       true
     end
 
+    # register a block to be called back with unhandled exceptions that occur
+    # in the threadpool. 
+    # 
+    # @note if your exception callback block itself raises an exception, I will
+    #   make fun of you.
+    #
+    def on_exception(&blk)
+      @mutex.synchronize do
+        @error_callbacks << blk
+      end
+    end
+
     # join all threads in this threadpool, they will be given a maximum of +timeout+
     # seconds to exit before they are considered hung and will be ignored (this is an
     # issue with threads in general: see 
@@ -90,18 +110,46 @@ module ZK
     end
 
     private
+      def dispatch_to_error_handler(e)
+        # make a copy that will be free from thread manipulation
+        # and doesn't require holding the lock
+        cbs = @mutex.synchronize { @error_callbacks.dup }
+
+        if cbs.empty?
+          default_exception_handler(e)
+        else
+          while cb = cbs.shift
+            begin
+              cb.call(e)
+            rescue Exception => e
+              msg = [ 
+                "Exception caught in user supplied on_exception handler.", 
+                "Just meditate on the irony of that for a moment. There. Good.",
+                "The callback that errored was: #{cb.inspect}, the exception was",
+                ""
+              ]
+
+              default_exception_handler(e, msg.join("\n"))
+            end
+          end
+        end
+      end
+
+      def default_exception_handler(e, msg=nil)
+        msg ||= 'Exception caught in threadpool'
+        logger.error { "#{msg}: #{e.to_std_format}" }
+      end
+
       def spawn_threadpool #:nodoc:
         until @threadpool.size >= @size.to_i
           thread = Thread.new do
             while @running
               begin
                 op = @threadqueue.pop
-#                 $stderr.puts "thread #{Thread.current.inspect} got #{op.inspect}"
                 break if op == KILL_TOKEN
                 op.call
               rescue Exception => e
-                logger.error { "Exception caught in threadpool" }
-                logger.error { e.to_std_format }
+                dispatch_to_error_handler(e)
               end
             end
           end

data/lib/zk/version.rb

@@ -0,0 +1,3 @@
+module ZK
+  VERSION = "1.0.0.rc.1"
+end