zk 0.8.9 → 0.9.0

data/lib/z_k/pool.rb

@@ -1,5 +1,22 @@
 module ZK
   module Pool
+    # Base class for a ZK connection pool. There are some applications that may 
+    # require high synchronous throughput, which would be a suitable use for a
+    # connection pool. The ZK::Client::Threaded class is threadsafe, so it's
+    # not a problem accessing it from multiple threads, but it is limited to
+    # one outgoing synchronous request at a time, which could cause throughput
+    # issues for apps that are making very heavy use of zookeeper. 
+    #
+    # The problem with using a connection pool is the added complexity when you
+    # try to use watchers. It may be possible to register a watch with one
+    # connection, and then call `:watch => true` on a different connection if
+    # you're not careful. Events delivered as part of an event handler have a
+    # `zk` attribute which can be used to access the connection that the
+    # callback is registered with. 
+    #
+    # Unless you're sure you *need* a connection pool, then avoid the added
+    # complexity.
+    #
     class Base
       include Logging
 
@@ -40,7 +57,6 @@ module ZK
       end
 
       # close all the connections on the pool
-      # @param optional Boolean graceful allow the checked out connections to come back first?
       def close_all!
         @mutex.synchronize do 
           return unless open?
@@ -54,7 +70,8 @@ module ZK
 
       # calls close! on all connection objects, whether or not they're back in the pool
       # this is DANGEROUS!
-      def force_close! #:nodoc:
+      # @private
+      def force_close!
         @mutex.synchronize do
           return if (closed? or forced?)
           @state = :forced
@@ -273,17 +290,18 @@ module ZK
         end
 
         def create_connection
-          ZK.new(@host, @connection_timeout, @connection_args)
+          ZK.new(@host, @connection_args.merge(:timeout => @connection_timeout))
         end
     end # Bounded
 
     # create a connection pool useful for multithreaded applications
     #
-    # Will spin up +number_of_connections+ at creation time and remain fixed at
+    # Will spin up `number_of_connections` at creation time and remain fixed at
     # that number for the life of the pool.
     #
-    # ==== Example
-    #   pool = ZK::Pool::Simple.new("localhost:2181", 10)
+    # @example
+    #
+    #   pool = ZK::Pool::Simple.new("localhost:2181", :timeout => 10)
     #   pool.checkout do |zk|
     #     zk.create("/mynew_path")
     #   end

data/lib/z_k/version.rb

@@ -1,3 +1,3 @@
 module ZK
-  VERSION = "0.8.9"
+  VERSION = "0.9.0"
 end

data/lib/z_k.rb

@@ -25,8 +25,7 @@ require 'z_k/find'
 module ZK
   ZK_ROOT = File.expand_path('../..', __FILE__)
 
-  KILL_TOKEN = :__ZK_kILL_tOkEn__ #:nodoc:
-
+  KILL_TOKEN = Object.new unless defined?(KILL_TOKEN) 
 
   # The logger used by the ZK library. uses a Logger to +/dev/null+ by default
   #

data/spec/shared/client_contexts.rb

@@ -0,0 +1,15 @@
+shared_context 'threaded client connection' do
+  before do
+    @connection_string = "localhost:#{ZK_TEST_PORT}"
+    @zk = ZK::Client::Threaded.new(@connection_string).tap { |z| wait_until { z.connected? } }
+    @zk.rm_rf('/test')
+  end
+
+  after do
+    @zk.rm_rf('/test')
+    @zk.close!
+
+    wait_until(2) { @zk.closed? }
+  end
+end
+

data/spec/shared/client_examples.rb

@@ -0,0 +1,155 @@
+shared_examples_for 'client' do
+  describe :mkdir_p do
+    before(:each) do
+      @path_ary = %w[test mkdir_p path creation]
+      @bogus_path = File.join('/', *@path_ary)
+    end
+    
+    it %[should create all intermediate paths for the path givem] do
+      @zk.should_not be_exists(@bogus_path)
+      @zk.should_not be_exists(File.dirname(@bogus_path))
+      @zk.mkdir_p(@bogus_path)
+      @zk.should be_exists(@bogus_path)
+    end
+  end
+
+  describe :stat do
+    describe 'for a missing node' do
+      before do
+        @missing_path = '/thispathdoesnotexist'
+        @zk.delete(@missing_path) rescue ZK::Exceptions::NoNode
+      end
+
+      it %[should not raise any error] do
+        lambda { @zk.stat(@missing_path) }.should_not raise_error
+      end
+
+      it %[should return a Stat object] do
+        @zk.stat(@missing_path).should be_kind_of(ZookeeperStat::Stat)
+      end
+
+      it %[should return a stat that not exists?] do
+        @zk.stat(@missing_path).should_not be_exists
+      end
+    end
+  end
+
+  describe :block_until_node_deleted do
+    before do
+      @path = '/_bogualkjdhsna'
+    end
+
+    describe 'no node initially' do
+      before do
+        @zk.exists?(@path).should be_false
+      end
+
+      it %[should not block] do
+        @a = false
+
+        th = Thread.new do
+          @zk.block_until_node_deleted(@path)
+          @a = true
+        end
+
+        th.join(2)
+        @a.should be_true
+      end
+    end
+
+    describe 'node exists initially' do
+      before do
+        @zk.create(@path, '', :mode => :ephemeral)
+        @zk.exists?(@path).should be_true
+      end
+
+      it %[should block until the node is deleted] do
+        @a = false
+
+        th = Thread.new do
+          @zk.block_until_node_deleted(@path)
+          @a = true
+        end
+
+        Thread.pass
+        @a.should be_false
+
+        @zk.delete(@path)
+
+        wait_until(2) { @a }
+        @a.should be_true
+      end
+    end
+  end
+
+  describe 'session_id and session_passwd' do
+    it %[should expose the underlying session_id] do
+      @zk.session_id.should be_kind_of(Fixnum)
+    end
+
+    it %[should expose the underlying session_passwd] do
+      @zk.session_passwd.should be_kind_of(String)
+    end
+  end
+
+  describe 'reopen' do
+    describe 'watchers' do
+      before do
+        @path = '/testwatchers'
+        @queue = Queue.new
+        @zk.delete(@path) rescue ZK::Exceptions::NoNode
+      end
+
+#       after do
+#         logger.info { "AFTER EACH" } 
+#         @zk.delete(@path)
+#       end
+
+      def ensure_event_delivery!
+        @sub ||= @zk.event_handler.register(@path) do |event|
+          logger.debug { "got event: #{event.inspect}" } 
+          @queue << event
+        end
+
+        @zk.exists?(@path, :watch => true).should be_false
+        @zk.create(@path, '')
+
+        logger.debug { "waiting for event delivery" } 
+
+        wait_until(2) do 
+          begin
+            @events << @queue.pop(true)
+            true
+          rescue ThreadError
+            false
+          end
+        end
+
+        # first watch delivered correctly
+        @events.length.should > 0
+      end
+
+      it %[should fire re-registered watchers after reopen (#9)] do
+        @events = []
+
+        logger.debug { "ensure event delivery" }
+        ensure_event_delivery!
+
+        logger.debug { "reopening connection" }
+        @zk.reopen
+
+        wait_until(2) { @zk.connected? }
+
+        logger.debug { "deleting path" }
+        @zk.delete(@path)
+
+        logger.debug { "clearing events" }
+        @events.clear
+
+        logger.debug  { "taunt them a second time" }
+        ensure_event_delivery!
+      end
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -8,65 +8,25 @@ require 'benchmark'
 
 ZK_TEST_PORT = 2181
 
-LOG_FILE = File.open(File.join(ZK::ZK_ROOT, 'test.log'), 'a').tap { |f| f.sync = true }
-
-ZK.logger = Logger.new(LOG_FILE).tap { |log| log.level = Logger::DEBUG }
-Zookeeper.logger = ZK.logger
-
-ZK.logger.debug { "LOG OPEN" }
-
 # Requires supporting ruby files with custom matchers and macros, etc,
 # in spec/support/ and its subdirectories.
-Dir[File.expand_path("../support/**/*.rb", __FILE__)].each {|f| require f}
+Dir[File.expand_path("../{support,shared}/**/*.rb", __FILE__)].each {|f| require f}
 
 $stderr.sync = true
 
-# COMMENT THESE LINES FOR REMOTE DEBUGGING
-# require 'ruby-debug'
 require 'flexmock'
 
 RSpec.configure do |config|
   config.mock_with :flexmock
   config.include(FlexMock::ArgumentTypes)
 
-#   config.before(:all) do
-#     unless $did_debug
-#       $did_debug = true
-#       $stderr.puts "debugger started? is #{Debugger.started?.inspect}"
+  config.include(WaitWatchers)
+  config.extend(WaitWatchers)
 
-#       Debugger.wait_connection = true
-#       $stderr.puts "run 'rdebug -c -p #{Debugger::PORT}'"
-#       Debugger.start_remote
-
-#       config.debug = true
-#     end
-#   end
+  config.include(SpecGlobalLogger)
+  config.extend(SpecGlobalLogger)
 end
 
-def logger
-  ZK.logger
-end
-
-# method to wait until block passed returns true or timeout (default is 2 seconds) is reached 
-def wait_until(timeout=2)
-  time_to_stop = Time.now + timeout
-
-  until yield 
-    break if Time.now > time_to_stop
-    Thread.pass
-  end
-end
-
-def wait_while(timeout=2)
-  time_to_stop = Time.now + timeout
-
-  while yield 
-    break if Time.now > time_to_stop
-    Thread.pass
-  end
-end
-
-
 class ::Thread
   # join with thread until given block is true, the thread joins successfully, 
   # or timeout seconds have passed
@@ -76,7 +36,8 @@ class ::Thread
 
     until yield
       break if Time.now > time_to_stop
-      break if join(0.1)
+      break if join(0)
+      Thread.pass
     end
   end
   
@@ -85,15 +46,10 @@ class ::Thread
 
     while yield
       break if Time.now > time_to_stop
-      break if join(0.1)
+      break if join(0)
+      Thread.pass
     end
   end
 end
 
-def report_realtime(what)
-  return yield
-  t = Benchmark.realtime { yield }
-  $stderr.puts "#{what}: %0.3f" % [t.to_f]
-end
-
 

data/spec/support/logging.rb

@@ -0,0 +1,27 @@
+module ZK
+  LOG_FILE = File.open(File.join(ZK::ZK_ROOT, 'test.log'), 'a').tap { |f| f.sync = true }
+#   LOG_FILE = $stderr
+end
+
+ZK.logger = Logger.new(ZK::LOG_FILE).tap { |log| log.level = Logger::DEBUG }
+
+# Zookeeper.logger = ZK.logger
+# Zookeeper.set_debug_level(4)
+
+ZK.logger.debug { "LOG OPEN" }
+
+module SpecGlobalLogger
+  def logger
+    ZK.logger
+  end
+
+  # sets the log level to FATAL for the duration of the block
+  def mute_logger
+    orig_level, ZK.logger.level = ZK.logger.level, Logger::FATAL
+    orig_zk_level, Zookeeper.debug_level = Zookeeper.debug_level, ZookeeperConstants::ZOO_LOG_LEVEL_ERROR
+    yield
+  ensure
+    ZK.logger.level = orig_level
+  end
+end
+

data/spec/support/special_happy_funtime_error.rb

@@ -0,0 +1,6 @@
+module ZK
+  # nothing to see here, move along
+  class SpecialHappyFuntimeError < RuntimeError
+  end
+end
+

data/spec/support/wait_watchers.rb

@@ -0,0 +1,48 @@
+module WaitWatchers
+  class TimeoutError < StandardError; end
+
+  # method to wait until block passed returns truthy (false will not work) or
+  # timeout (default is 2 seconds) is reached raises TiemoutError on timeout
+  #
+  # @returns the truthy value
+  #
+  # @example 
+  #     
+  #   @a = nil
+  #
+  #   th = Thread.new do
+  #     sleep(1)
+  #     @a = :fudge
+  #   end
+  #
+  #   wait_until(2) { @a }.should == :fudge
+  #
+  def wait_until(timeout=2)
+    time_to_stop = Time.now + timeout
+    while true
+      rval = yield
+      return rval if rval
+      raise TimeoutError, "timeout of #{timeout}s exceeded" if Time.now > time_to_stop
+      Thread.pass
+    end
+  end
+
+  # inverse of wait_until
+  def wait_while(timeout=2)
+    time_to_stop = Time.now + timeout
+    while true
+      rval = yield
+      return rval unless rval
+      raise TimeoutError, "timeout of #{timeout}s exceeded" if Time.now > time_to_stop
+      Thread.pass
+    end
+  end
+
+  def report_realtime(what)
+    return yield
+    t = Benchmark.realtime { yield }
+    $stderr.puts "#{what}: %0.3f" % [t.to_f]
+  end
+end
+
+

data/spec/watch_spec.rb

@@ -16,7 +16,9 @@ describe ZK do
         wait_until { !@zk.connected? }
       end
 
-      ZK.open(@cnx_str) { |zk| zk.rm_rf(@path) }
+      mute_logger do
+        ZK.open(@cnx_str) { |zk| zk.rm_rf(@path) }
+      end
     end
 
     it "should call back to path registers" do
@@ -37,6 +39,16 @@ describe ZK do
       callback_called.should be_true
     end
 
+    # this is stupid, and a bad test, but we have to check that events 
+    # don't get re-delivered to a single registered callback just because 
+    # :watch => true was called twice
+    #
+    # again, we're testing a negative here, so consider this a regression check
+    #
+    def wait_for_events_to_not_be_delivered(events)
+      lambda { wait_until(0.2) { events.length >= 2 } }.should raise_error(WaitWatchers::TimeoutError)
+    end
+
     it %[should only deliver an event once to each watcher registered for exists?] do
       events = []
 
@@ -51,7 +63,8 @@ describe ZK do
 
       @zk.create(@path, '', :mode => :ephemeral)
 
-      wait_until { events.length >= 2 }
+      wait_for_events_to_not_be_delivered(events)
+
       events.length.should == 1
     end
 
@@ -72,7 +85,8 @@ describe ZK do
 
       @zk.set(@path, 'two')
 
-      wait_until { events.length >= 2 }
+      wait_for_events_to_not_be_delivered(events)
+
       events.length.should == 1
     end
 
@@ -94,7 +108,8 @@ describe ZK do
 
       @zk.create("#{@path}/pfx", '', :mode => :ephemeral_sequential)
 
-      wait_until { events.length >= 2 }
+      wait_for_events_to_not_be_delivered(events)
+
       events.length.should == 1
     end
   end

data/spec/z_k/client/drop_box_spec.rb

@@ -0,0 +1,90 @@
+require 'spec_helper'
+
+module ZK
+  module Client
+    describe 'ZK::Client::DropBox' do
+      let(:drop_box) { DropBox.new }
+
+      after do
+        DropBox.remove_current
+      end
+
+      it %[should start out with an undefined value] do
+        drop_box.value.should == DropBox::UNDEFINED
+      end
+
+      it %[should block the caller waiting for a response] do
+        @rv = nil
+
+        th1 = Thread.new do
+          Thread.current.abort_on_exception = true
+          @rv = drop_box.pop
+        end
+
+        wait_until(2) { th1.status == 'sleep' }
+
+        th1.status.should == 'sleep'
+
+        th2 = Thread.new do
+          drop_box.push :result
+        end
+
+        th2.join(2).should == th2
+        th1.join(2).should == th1
+
+        @rv.should == :result
+      end
+
+      describe :oh_noes! do
+        let(:error_class) { SpecialHappyFuntimeError }
+        let(:error_msg)   { 'this is a unique message' }
+
+        it %[should wake the caller by raising the exception class and message given] do
+          drop_box.should_not be_done # sanity check
+
+          th1 = Thread.new do
+            drop_box.pop
+          end
+
+          wait_until(2) { th1.status == 'sleep' }
+
+          th1.status.should == 'sleep'
+
+          drop_box.oh_noes!(error_class, error_msg).should_not be_nil
+
+          lambda { th1.join(2) }.should raise_error(error_class, error_msg)
+
+          drop_box.should be_done
+        end
+      end
+
+      describe :done? do
+        it %[should be done if the value is defined] do
+          drop_box.should_not be_done
+          drop_box.push :defined
+          drop_box.should be_done
+        end
+
+        it %[should not be done once cleared] do
+          drop_box.push :defined
+          drop_box.should be_done
+          drop_box.clear
+          drop_box.should_not be_done
+        end
+      end
+
+      describe :with_current do
+        it %[should clear the current thread's drop_box once the block exits] do
+          DropBox.with_current do |c|
+            c.should_not be_done
+            c.push 'yo_mama'
+            c.should be_done
+          end
+
+          DropBox.current.should_not be_done
+        end
+      end
+    end
+  end
+end
+

data/spec/z_k/client/locking_and_session_death_spec.rb

@@ -0,0 +1,108 @@
+require 'spec_helper'
+
+shared_examples_for 'session death' do
+  def deliver_session_event_to(event_num, zk)
+    # jeez, Zookeeper callbacks are so frustratingly stupid
+    bogus_event = ZookeeperCallbacks::WatcherCallback.new
+    bogus_event.initialize_context(:type => -1, :state => event_num, :path => '', :context => 'bogustestevent')
+    # XXX: this is bad because we're in the wrong thread, but we'll fix this after the next Zookeeper release
+    zk.event_handler.process(bogus_event)
+  end
+
+  before do
+    @other_zk = ZK.new(@connection_string)
+  end
+
+  after do
+    @other_zk.close! unless @other_zk.closed?
+  end
+
+  it %[should wake up in the case of an expired session and throw an exception] do
+    @a = false
+
+    @other_zk.event_handler.register_state_handler(zoo_state) do |event|
+      @a = event
+    end
+
+    th = Thread.new do
+      @other_zk.block_until_node_deleted(@path)
+    end
+
+    # we don't expect an exception yet, so warn us if there is on while this
+    # thread is on its way to sleep
+    th.abort_on_exception = true
+
+    wait_until(2) { th.status == 'sleep' }
+
+    th.abort_on_exception = false   # after here, we're raising an exception on purpose
+
+    th.join if th.status.nil?       # this indicates an exception happened...already
+
+    # not on the other thread, this may be bad
+    deliver_session_event_to(zoo_state, @other_zk)
+
+    # ditto, this is probably happening synchrnously
+    wait_until(2) { @a }.should be_true
+
+    lambda { th.join(2) }.should raise_error(zoo_error_class)
+  end
+end # session death
+
+shared_examples_for 'locking and session death' do
+  describe 'exceptional conditions' do
+    describe 'ZOO_EXPIRED_SESSION_STATE' do
+      let(:zoo_state) { ZookeeperConstants::ZOO_EXPIRED_SESSION_STATE }
+      let(:zoo_error_class) { ZookeeperExceptions::ZookeeperException::SessionExpired }
+
+      it_behaves_like 'session death'
+    end
+
+    describe 'ZOO_CONNECTING_STATE' do
+      let(:zoo_state) { ZookeeperConstants::ZOO_CONNECTING_STATE }
+      let(:zoo_error_class) { ZookeeperExceptions::ZookeeperException::NotConnected }
+
+      it_behaves_like 'session death'
+    end
+
+    describe 'ZOO_CLOSED_STATE' do
+      let(:zoo_state) { ZookeeperConstants::ZOO_CLOSED_STATE }
+      let(:zoo_error_class) { ZookeeperExceptions::ZookeeperException::ConnectionClosed }
+
+      it_behaves_like 'session death'
+    end
+  end
+end
+
+describe 'threaded client and locking behavior' do
+  include_context 'threaded client connection'
+
+  before do
+    @path = '/test'
+    @zk.create('/test') rescue ZK::Exceptions::NodeExists
+  end
+
+  describe 'block_until_node_deleted' do
+    it %[should raise an EventDispatchThreadException if called in the context of the event dispatch thread] do
+      @exception = nil
+
+      @zk.register(@path) do |event|
+        @zk.event_dispatch_thread?.should be_true
+
+        begin
+          @zk.block_until_node_deleted(@path)
+        rescue Exception => e
+          @exception = e
+        end
+      end
+
+      @zk.exists?(@path, :watch => true)
+
+      @zk.set(@path, 'blah')
+
+      wait_until(2) { @exception }.should be_kind_of(ZK::Exceptions::EventDispatchThreadException)
+    end
+  end
+
+  it_should_behave_like 'locking and session death'
+end
+