zk 1.4.2 → 1.5.0

data/.dotfiles/ctags_paths

@@ -0,0 +1 @@
+~/vendor/ruby/*.{c,h}

data/.dotfiles/rspec-logging

@@ -1,4 +1,4 @@
 --color
---require ./spec/support/logging_progress_bar_formatter.rb
---format Motionbox::LoggingProgressBarFormatter
+--require ./spec/logging_progress_bar_formatter.rb
+--format LoggingProgressBarFormatter
 

data/.gitignore

@@ -10,3 +10,4 @@ Gemfile.*
 wiki
 zookeeper
 coverage/
+.ctags_paths

data/Gemfile

@@ -8,11 +8,10 @@ source :rubygems
 # keep closer track of this stuff to make bisecting easier and travis more
 # accurate
 
-# git 'git://github.com/slyphon/zookeeper.git', :tag => 'dev/zk/00001' do
-#   gem 'zookeeper', '~> 1.0.0'
+# git 'git://github.com/slyphon/zookeeper.git', :tag => 'dev/zk/00006' do
+#   gem 'zookeeper', '~> 1.1.0'
 # end
 
-
 gem 'rake', :group => [:development, :test]
 gem 'pry',  :group => [:development]
 
@@ -28,6 +27,13 @@ platform :mri_19 do
   gem 'simplecov', :group => :coverage, :require => false
 end
 
+group :development do
+  gem 'guard',        :require => false
+  gem 'guard-rspec',  :require => false
+  gem 'guard-shell',  :require => false
+  gem 'guard-bundler',  :require => false
+end
+
 group :test do
   gem 'rspec', '~> 2.8.0'
   gem 'flexmock', '~> 0.8.10'

data/Guardfile

@@ -0,0 +1,36 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+dot_rspec_path = File.expand_path('../.rspec', __FILE__)
+
+rspec_options = File.open('.rspec', &:readlines).map(&:chomp).reject{|n| n =~ /\A(#|\Z)/}
+
+guard 'bundler' do
+  watch 'Gemfile'
+  watch /\A.+\.gemspec\Z/
+end
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+
+  watch(%r%^spec/support/client_forker.rb$%) { 'spec/zk/00_forked_client_integration_spec.rb' }
+
+  watch(%r{^lib/(.+)\.rb$}) do |m| 
+    case m[1]
+    when %r{^zk/event_handler$}
+      "spec/zk/watch_spec.rb"
+    when %r{^zk/client/threaded.rb$}
+      ["spec/zk/client_spec.rb", "spec/zk/zookeeper_spec.rb"]
+    when %r{^zk/locker/}
+      "spec/zk/locker_spec.rb"
+    when %r{^zk\.rb$}
+      'spec'  # run all tests
+    else
+      "spec/#{m[1]}_spec.rb"
+    end
+  end
+
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+
+

data/README.markdown

@@ -65,6 +65,27 @@ In addition to all of that, I would like to think that the public API the ZK::Cl
 [zk-eventmachine]: https://github.com/slyphon/zk-eventmachine
 
 ## NEWS ##
+### v1.5.0 ###
+
+Ok, now seriously this time. I think all of the forking issues are done. 
+
+* Implemented a 'stop the world' feature to ensure safety when forking. All threads are stopped, but state is preserved. `fork()` can then be called safely, and after fork returns, all threads will be restarted in the parent, and the connection will be torn down and reopened in the child. 
+
+* The easiest, and supported, way of doing this is now to call `ZK.install_fork_hook` after requiring zk. This will install an `alias_method_chain` style hook around the `Kernel.fork` method, which handles pausing all clients in the parent, calling fork, then resuming in the parent and reconnecting in the child. If you're using ZK in resque, I *highly* recommend using this approach, as it will give the most consistent results.
+
+In your app that requires an open ZK instance and `fork()`:
+
+```ruby
+
+require 'zk'
+ZK.install_fork_hook
+
+```
+
+Then use fork as you normally would.
+
+* Logging is now off by default, but we now use the excellent, can't-recommend-it-enough, [logging](https://github.com/TwP/logging) gem. If you want to tap into the ZK logs, you can assign a stdlib compliant logger to `ZK.logger` and that will be used. Otherwise, you can use the Logging framework's controls. All ZK logs are consolidated under the 'ZK' logger instance.
+
 
 ### v1.4.1 ###
 
@@ -105,24 +126,6 @@ Phusion Passenger and Unicorn users are encouraged to upgrade!
 
 * See the fork-handling documentation [on the wiki](http://github.com/slyphon/zk/wiki/Forking).
 
-### v1.2.0 ###
-
-You are __STRONGLY ENCOURAGED__ to go and look at the [CHANGELOG](http://git.io/tPbNBw) from the zookeeper 1.0.0 release
-
-* NOTICE: This release uses the 1.0 release of the zookeeper gem, which has had a MAJOR REFACTORING of its namespaces. Included in that zookeeper release is a compatibility layer that should ease the transition, but any references to Zookeeper\* heirarchy should be changed. 
-
-* Refactoring related to the zokeeper gem, use all the new names internally now.
-
-* Create a new Subscription class that will be used as the basis for all subscription-type things.
-
-* Add new Locker features!
-  * `LockerBase#assert!` - will raise an exception if the lock is not held. This check is not only for local in-memory "are we locked?" state, but will check the connection state and re-run the algorithmic tests that determine if a given Locker implementation actually has the lock.
-  * `LockerBase#acquirable?` - an advisory method that checks if any condition would prevent the receiver from acquiring the lock. 
-
-* Deprecation of the `lock!` and `unlock!` methods. These may change to be exception-raising in a future relase, so document and refactor that `lock` and `unlock` are the way to go.
-
-* Fixed a race condition in `event_catcher_spec.rb` that would cause 100% cpu usage and hang.
-
 
 ## Caveats
 

data/RELEASES.markdown

@@ -1,5 +1,15 @@
 This file notes feature differences and bugfixes contained between releases. 
 
+### v1.5.0 ###
+
+Ok, now seriously this time. I think all of the forking issues are done. 
+
+* Implemented a 'stop the world' feature to ensure safety when forking. All threads are stopped, but state is preserved. `fork()` can then be called safely, and after fork returns, all threads will be restarted in the parent, and the connection will be torn down and reopened in the child. 
+
+* The easiest, and supported, way of doing this is now to call `ZK.install_fork_hook` after requiring zk. This will install an `alias_method_chain` style hook around the `Kernel.fork` method, which handles pausing all clients in the parent, calling fork, then resuming in the parent and reconnecting in the child. If you're using ZK in resque, I *highly* recommend using this approach, as it will give the most consistent results.
+
+* Logging is now off by default, and uses the excellent, can't-recommend-it-enough, [logging](https://github.com/TwP/logging) gem. If you want to tap into the ZK logs, you can assign a stdlib compliant logger to `ZK.logger` and that will be used. Otherwise, you can use the Logging framework's controls. All ZK logs are consolidated under the 'ZK' logger instance.
+
 ### v1.4.1 ###
 
 * True fork safety! The `zookeeper` at 1.1.0 is finally fork-safe. You can now use ZK in whatever forking library you want. Just remember to call `#reopen` on your client instance in the child process before attempting any opersations.

data/Rakefile

@@ -8,7 +8,7 @@ if File.exists?(release_ops_path)
   require File.join(release_ops_path, 'releaseops')
 
   # sets up the multi-ruby zk:test_all rake tasks
-  ReleaseOps::TestTasks.define_for(*%w[1.8.7 1.9.2 jruby rbx ree 1.9.3])
+  ReleaseOps::TestTasks.define_for(*%w[1.8.7 1.9.2 jruby ree 1.9.3])
 
   # sets up the task :default => 'spec:run' and defines a simple
   # "run the specs with the current rvm profile" task

data/lib/zk.rb

@@ -1,6 +1,6 @@
 require 'rubygems'
 
-require 'logger'
+require 'logging'
 require 'zookeeper'
 
 # XXX: after 1.0 we'll need this
@@ -12,21 +12,28 @@ require 'monitor'
 require 'set'
 require 'time'
 require 'date'
+require 'weakref'
 
 module ZK
+  # just like stdlib Monitor but provides the SAME API AS MUTEX, FFS!
+  # @private
+  class Monitor < Zookeeper::Monitor
+  end
 end
 
 require 'zk/core_ext'
-require 'zk/logging'
 require 'zk/exceptions'
 require 'zk/extensions'
+require 'zk/logging'
 require 'zk/event'
 require 'zk/stat'
 require 'zk/subscription'
+require 'zk/fork_hook'
 require 'zk/threadpool'
 require 'zk/threaded_callback'
 require 'zk/event_handler_subscription'
 require 'zk/event_handler'
+require 'zk/node_deletion_watcher'
 require 'zk/message_queue'
 require 'zk/locker'
 require 'zk/election'
@@ -46,9 +53,7 @@ module ZK
     KILL_TOKEN = Object.new 
   end
 
-  unless @logger
-    @logger = Logger.new($stderr).tap { |n| n.level = ENV['ZK_DEBUG'] ? Logger::DEBUG : Logger::ERROR }
-  end
+  @@logger = nil unless defined? @@logger
  
   @default_host   = 'localhost' unless @default_host
   @default_port   = 2181        unless @default_port
@@ -65,14 +70,6 @@ module ZK
     attr_accessor :default_chroot
   end
 
-  # @private
-  def self.default_connection_string
-    "#{default_host}:#{default_port}".tap do |str|
-      # XXX: this is seriously blech
-      str.replace(File.join(str, default_chroot)) if default_chroot != ''
-    end
-  end
-
   # The logger used by the ZK library. uses a Logger stderr with Logger::ERROR
   # level. The only thing that should ever be logged are exceptions that are
   # swallowed by background threads.
@@ -81,12 +78,20 @@ module ZK
   # implements the stdllb Logger API.
   #
   def self.logger
-    @logger
+    @@logger
   end
 
-  # Assign the Logger instance to be used by ZK
-  def self.logger=(logger)
-    @logger = logger
+  # set the ZK logger instance
+  def self.logger=(log)
+    @@logger = log
+  end
+
+  # @private
+  def self.default_connection_string
+    "#{default_host}:#{default_port}".tap do |str|
+      # XXX: this is seriously blech
+      str.replace(File.join(str, default_chroot)) if default_chroot != ''
+    end
   end
 
   # Create a new ZK::Client instance. If no arguments are given, the default
@@ -205,9 +210,10 @@ module ZK
     cnx = new(*args)
     yield cnx
   ensure
-    cnx.close! if cnx
-    # XXX: need some way of waiting for the connection to reach closed? state
-    #      ensure there's no leakage
+    if cnx
+      cnx.close! 
+      Thread.pass until cnx.closed?
+    end
   end
 
   # creates a new ZK::Pool::Bounded with the default options.
@@ -292,7 +298,6 @@ module ZK
       open(host) do |zk|                # do path stuff with the virgin connection
         unless zk.exists?(chroot_path)  # someting must be done
           if chroot_opt == :create      # here, let me...
-            logger.debug { "creating chroot path #{chroot_path}" }
             zk.mkdir_p(chroot_path)     # ...get that for you
           else                          # careful with that axe
             raise Exceptions::ChrootPathDoesNotExistError.new(host, chroot_path)  # ...eugene
@@ -304,3 +309,5 @@ module ZK
     end
 end
 
+ZK::Logging.set_default
+

data/lib/zk/client/threaded.rb

@@ -140,8 +140,15 @@ module ZK
         @reconnect = opts.fetch(:reconnect, true)
 
         @mutex = Monitor.new
+        @cond  = @mutex.new_cond
 
-        @close_requested = false
+        @cli_state = :running # this is to distinguish between *our* state and the underlying connection state
+
+        @fork_subs = [
+          ForkHook.prepare_for_fork(method(:pause_before_fork_in_parent)),
+          ForkHook.after_fork_in_parent(method(:resume_after_fork_in_parent)),
+          ForkHook.after_fork_in_child(method(:reopen)),
+        ]
 
         yield self if block_given?
 
@@ -169,25 +176,69 @@ module ZK
           # ok, just to sanity check here
           raise "[BUG] we hit the fork-reopening code in JRuby!!" if defined?(::JRUBY_VERSION)
 
-          logger.debug { "#{self.class}##{__method__} reopening everything, fork detected!" }
+          logger.debug { "reopening everything, fork detected!" }
 
           @mutex = Monitor.new
-          @threadpool.reopen_after_fork!      # prune dead threadpool threads after a fork()
-          @event_handler.reopen_after_fork!
           @pid = Process.pid
+          @cli_state = :running                     # reset state to running if we were paused
 
           old_cnx, @cnx = @cnx, nil
           old_cnx.close! if old_cnx # && !old_cnx.closed?
+
+          @mutex.synchronize do
+            # it's important that we're holding the lock, as access to 'cnx' is
+            # synchronized, and we want to avoid a race where event handlers
+            # might see a nil connection. I've seen this exception occur *once*
+            # so it's pretty rare (it was on 1.8.7 too), but just to be double
+            # extra paranoid
+
+            @event_handler.reopen_after_fork!
+            @threadpool.reopen_after_fork!          # prune dead threadpool threads after a fork()
+
+            connect
+          end
         else
-          logger.debug { "#{self.class}##{__method__} not reopening, no fork detected" }
-          @cnx.reopen(timeout)
+          @mutex.synchronize do
+            if @cli_state == :paused
+              # XXX: what to do in this case? does it matter?
+            end
+
+            logger.debug { "reopening, no fork detected" }
+            @cnx.reopen(timeout)                # ok, we werent' forked, so just reopen
+          end
         end
 
-        @mutex.synchronize { @close_requested = false }
-        connect
         state
       end
 
+      # Before forking, call this method to peform a "stop the world" operation on all
+      # objects associated with this connection. This means that this client will spin down
+      # and join all threads (so make sure none of your callbacks will block forever), 
+      # and will tke no action to keep the session alive. With the default settings,
+      # if a ping is not received within 20 seconds, the session is considered dead
+      # and must be re-established so be sure to call {#resume_after_fork_in_parent}
+      # before that deadline, or you will have to re-establish your session.
+      #
+      # @raise [InvalidStateError] when called and not in running? state
+      def pause_before_fork_in_parent
+        @mutex.synchronize do
+          raise InvalidStateError, "client must be running? when you call #{__method__}" unless running?
+          @cli_state = :paused
+        end
+        logger.debug { "#{self.class}##{__method__}" }
+        [@event_handler, @threadpool, @cnx].each(&:pause_before_fork_in_parent)
+      end
+
+      def resume_after_fork_in_parent
+        @mutex.synchronize do
+          raise InvalidStateError, "client must be paused? when you call #{__method__}" unless paused?
+          @cli_state = :running
+        end
+
+        logger.debug { "#{self.class}##{__method__}" }
+        [@cnx, @event_handler, @threadpool].each(&:resume_after_fork_in_parent)
+      end
+
       # (see Base#close!)
       #
       # @note We will make our best effort to do the right thing if you call
@@ -198,8 +249,9 @@ module ZK
       #
       def close!
         @mutex.synchronize do 
-          return if @close_requested
-          @close_requested = true 
+          return if [:closed, :close_requested].include?(@cli_state)
+#           logger.debug { "moving to :close_requested state" }
+          @cli_state = :close_requested
         end
 
         on_tpool = on_threadpool?
@@ -213,18 +265,24 @@ module ZK
         # and wait for it to exit
         #
         shutdown_thread = Thread.new do
-          @threadpool.shutdown(2)
+          @threadpool.shutdown(10)
           super
-        end
 
-        shutdown_thread.join unless on_tpool
+          @mutex.synchronize do
+#             logger.debug { "moving to :closed state" }
+            @cli_state = :closed
+          end
+        end
 
-        nil
+        on_tpool ? shutdown_thread : shutdown_thread.join 
       end
 
       # {see Base#close}
       def close
         super
+        subs, @fork_subs = @fork_subs, []
+        subs.each(&:unsubscribe)
+        nil
       end
 
       # (see Threadpool#on_threadpool?)
@@ -245,12 +303,13 @@ module ZK
           return unless @reconnect
 
           @mutex.synchronize do
-            unless @close_requested  # a legitimate shutdown case
+            unless dead_or_dying?  # a legitimate shutdown case
 
               logger.error { "Got event #{event.state_name}, calling reopen(0)! things may be messed up until this works itself out!" }
                
               # reopen(0) means that we don't want to wait for the connection
-              # to reach the connected state before returning
+              # to reach the connected state before returning as we're on the
+              # event thread.
               reopen(0)
             end
           end
@@ -259,11 +318,42 @@ module ZK
         logger.error { "BUG: Exception caught in raw_event_handler: #{e.to_std_format}" } 
       end
 
+      def closed?
+        return true if @mutex.synchronize { @cli_state == :closed }
+        super
+      end
+
+      # are we in running (not-paused) state?
+      def running?
+        @mutex.synchronize { @cli_state == :running }
+      end
+
+      # are we in paused state?
+      def paused?
+        @mutex.synchronize { @cli_state == :paused }
+      end
+
+      # has shutdown time arrived?
+      def close_requested?
+        @mutex.synchronize { @cli_state == :close_requested }
+      end
+
       protected
+        # in the threaded version of the client, synchronize access around cnx
+        # so that callers don't wind up with a nil object when we're in the middle
+        # of reopening it
+        def cnx
+          @mutex.synchronize { @cnx }
+        end
+
         # @private
         def create_connection(*args)
           ::Zookeeper.new(*args)
         end
-      end
+
+        def dead_or_dying?
+          (@cli_state == :close_requested) || (@cli_state == :closed)
+        end
+    end
   end
 end