zk 1.1.0 → 1.1.1

data/.travis.yml

@@ -10,6 +10,11 @@ rvm:
   - 1.9.3
   - 1.9.2
   - 1.8.7
+  - ree
+
+# jruby specs are too intesive for travis
+#   - jruby-18mode
+#   - jruby-19mode
 
 bundler_args: --without development docs
 

data/Gemfile

@@ -6,7 +6,7 @@ gem 'rake', :group => [:development, :test]
 gem 'pry',  :group => [:development]
 
 group :docs do
-  gem 'yard', '~> 0.7.5'
+  gem 'yard', '~> 0.8.0'
 
   platform :mri_19 do
     gem 'redcarpet'
@@ -16,8 +16,7 @@ end
 group :test do
   gem 'rspec', '~> 2.8.0'
   gem 'flexmock', '~> 0.8.10'
-#   gem 'zk-server', :path => '~/mbox/zk-server'
-  gem 'zk-server', '~> 0.9.1'
+  gem 'zk-server', '~> 1.0.1'
 end
 
 # Specify your gem's dependencies in zk.gemspec

data/README.markdown

@@ -18,6 +18,13 @@ Development is sponsored by [Snapfish][] and has been generously released to the
 [MIT]: http://www.gnu.org/licenses/license-list.html#Expat "MIT (Expat) License"
 [Snapfish]: http://www.snapfish.com/ "Snapfish"
 
+## Contacting the author
+
+* I'm usually hanging out in IRC on freenode.net in the BRAND NEW #zk-gem channel.
+* if you really want to, you can also reach me via twitter [@slyphon][]
+
+[@slyphon]: https://twitter.com/#!/slyphon
+
 ## New in 1.1 !! ##
 
 * NEW! Thread-per-Callback event delivery model! [Read all about it!](https://github.com/slyphon/zk/wiki/EventDeliveryModel). Provides a simple, sane way to increase the concurrency in your ZK-based app while maintaining the ordering guarantees ZooKeeper makes. Each callback can perform whatever work it needs to without blocking other callbacks from receiving events. Inspired by [Celluloid's](https://github.com/celluloid/celluloid) actor model.
@@ -161,11 +168,4 @@ ZK strives to be a complete, correct, and convenient way of interacting with Zoo
 [szk-jar-gem]: https://rubygems.org/gems/slyphon-zookeeper_jar
 [szk-jar-repo]: https://github.com/slyphon/zookeeper_jar
 
-## Contacting the author
-
-* Send me a github message (slyphon)
-* I'm usually hanging out in IRC on freenode.net in #ruby-lang and in #zookeeper
-* if you really want to, you can also reach me via twitter [@slyphon][]
-
-[@slyphon]: https://twitter.com/#!/slyphon
 

data/RELEASES.markdown

@@ -1,4 +1,22 @@
 This file notes feature differences and bugfixes contained between releases. 
+### v1.1.1 ###
+
+* Documentation for Locker and ilk
+
+* Documentation cleanup
+
+* Fixes for Locker tests so that we can run specs against all supported ruby implementations on travis (relies on in-process zookeeper server in the zk-server-1.0.1 gem)
+
+* Support for 1.8.7 will be continued 
+
+## v1.1.0 ##
+
+(forgot to put this here, put it in the readme though)
+
+* NEW! Thread-per-Callback event delivery model! [Read all about it!](https://github.com/slyphon/zk/wiki/EventDeliveryModel). Provides a simple, sane way to increase the concurrency in your ZK-based app while maintaining the ordering guarantees ZooKeeper makes. Each callback can perform whatever work it needs to without blocking other callbacks from receiving events. Inspired by [Celluloid's](https://github.com/celluloid/celluloid) actor model.
+
+* Use the [zk-server](https://github.com/slyphon/zk-server) gem to run a standalone ZooKeeper server for tests (`rake SPAWN_ZOOKEEPER=1`). Makes live-fire testing of any project that uses ZK easy to run anywhere!
+
 
 ### v1.0.0 ###
 

data/Rakefile

@@ -4,7 +4,7 @@ gemset_name = 'zk'
 
 GEMSPEC_NAME = 'zk.gemspec'
 
-%w[1.8.7 1.9.2 jruby rbx 1.9.3].each do |ns_name|
+%w[1.8.7 1.9.2 jruby rbx ree 1.9.3].each do |ns_name|
   rvm_ruby = (ns_name == 'rbx') ? "rbx-2.0.testing" : ns_name
 
   ruby_with_gemset        = "#{rvm_ruby}@#{gemset_name}"
@@ -59,6 +59,10 @@ namespace :yard do
   task :server => :clean do
     sh "yard server --reload"
   end
+
+  task :gems do
+    sh 'yard server --gems --port=8809'
+  end
 end
 
 task :clean => 'yard:clean'
@@ -70,7 +74,7 @@ namespace :spec do
     require 'rspec/core/rake_task'
 
     RSpec::Core::RakeTask.new('spec:runner') do |t|
-      t.rspec_opts = '-f d'
+      t.rspec_opts = '-f d' if ENV['TRAVIS']
     end
   end
 

data/lib/zk/client/conveniences.rb

@@ -1,8 +1,10 @@
 module ZK
   module Client
-    # EXTENSIONS
+    # Convenience methods for creating instances of the cluster coordination
+    # objects ZK provides, using the current connection.
+    #
+    # Mixed into {ZK::Client::Threaded}
     #
-    # convenience methods for dealing with zookeeper (rm -rf, mkdir -p, etc)
     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
@@ -18,6 +20,7 @@ module ZK
       # @yield [] the block that should be run in the threadpool, if `callable`
       #   isn't given
       #
+      # @private
       def defer(callable=nil, &block)
         @threadpool.defer(callable, &block)
       end
@@ -33,55 +36,53 @@ module ZK
         false
       end
 
-      # 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
+      # Creates a new locker based on the name you provide, using this client
+      # as the connection.
       #
-      # ==== Arguments
-      # * <tt>name</tt> name of the lock you wish to use
+      # @param name [String] the name of the lock you wish to use. see
+      #   {ZK::Locker} for a description of how the name is used to generate a
+      #   key.
       #
-      # ==== Examples
-      #
-      #   zk.locker("blah")
-      #   # => #<ZK::Locker::ExclusiveLocker:0x102034cf8 ...>
+      # @return [Locker::ExclusiveLocker] instance using this Client and
+      #   provided lock name. 
       #
       def locker(name)
         Locker.exclusive_locker(self, name)
       end
+      alias exclusive_locker locker
 
       # 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
+      # @param name (see #locker)
       #
-      #   zk.shared_locker("blah")
-      #   # => #<ZK::Locker::SharedLocker:0x102034cf8 ...>
+      # @return [Locker::SharedLocker] instance using this Client and provided
+      #   lock name. 
       #
       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.
+      # will block the caller until the lock is acquired, and release the lock
+      # when the block is exited.
       #
-      # ==== Arguments
-      # * <tt>name</tt>: the name of the lock to use
-      # * <tt>:mode</tt>: either :shared or :exclusive, defaults to :exclusive
+      # @param name (see #locker)
       #
-      # ==== Examples
+      # @option opts [:shared,:exclusive] :mode (:exclusive) the type of lock
+      #   to create and then call with_lock on
+      #
+      # @return the return value of the given block
+      #
+      # @yield calls the block once the lock has been acquired
+      #
+      # @example
       #
       #   zk.with_lock('foo') do
       #     # this code is executed while holding the lock
       #   end
       #
+      # @raise [ArgumentError] if `opts[:mode]` is not one of the expected values
+      #
       def with_lock(name, opts={}, &b)
         mode = opts[:mode] || :exclusive
 
@@ -94,29 +95,38 @@ module ZK
         end
       end
 
-      # Convenience method for constructing a ZK::Election::Candidate object using this 
-      # Client connection, the given election +name+ and +data+.
+      # Constructs an {Election::Candidate} object using self as the connection
+      #
+      # @param [String] name the name of the election to participate in
+      # @param [String] data the data we will write to the leadership node if/when we win
       #
+      # @return [Election::Candidate] the candidate instance using self as a connection
       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+.
+      # Constructs an {Election::Observer} object using self as the connection
+      # 
+      # @param name (see #election_candidate)
       #
+      # @return [Election::Observer] the candidate instance using self as a connection
       def election_observer(name, opts={})
         ZK::Election::Observer.new(self, name, opts)
       end
 
-      # creates a new message queue of name +name+
+      # creates a new message queue of name `name`
+      # 
+      # @note The message queue has some scalability limitations. For
+      #   heavy-duty message processing, the author recommends investigating 
+      #   a purpose-built solution.
       #
-      # returns a ZK::MessageQueue object
+      # @return [MessageQueue] the new instance using self as its
+      #   client
       #
-      # ==== Arguments
-      # * <tt>name</tt> the name of the queue
+      # @param [String] name the name of the queue
       #
-      # ==== Examples
+      # @example
       #
       #   zk.queue("blah").publish({:some_data => "that is yaml serializable"})
       #

data/lib/zk/client/threaded.rb

@@ -3,7 +3,7 @@ module ZK
     # This is the default client that ZK will use. In the zk-eventmachine gem,
     # there is an Evented client.
     #
-    # If you want to register `on_*` callbacks (see ZK::Client::StateMixin)
+    # If you want to register `on_*` callbacks (see {ZK::Client::StateMixin})
     # then you should pass a block, which will be called before the
     # connection is set up (this way you can get the `on_connected` event). See
     # the 'Register on_connected callback' example.
@@ -26,7 +26,7 @@ module ZK
     #   # the nice thing about this pattern is that in the case of a call to #reopen
     #   # all your watches will be re-established
     #
-    #   ZK::Client::Threaded.new('localhsot:2181') do |zk|
+    #   ZK::Client::Threaded.new('localhost:2181') do |zk|
     #     # do not do anything in here except register callbacks
     #     
     #     zk.on_connected do |event|
@@ -45,6 +45,12 @@ module ZK
 
       # Construct a new threaded client.
       #
+      # Pay close attention to the `:threaded` option, and have a look at the
+      # [EventDeliveryModel](https://github.com/slyphon/zk/wiki/EventDeliveryModel)
+      # page in the wiki for a discussion of the relative advantages and
+      # disadvantages of the choices available. The default is safe, but the
+      # alternative will likely provide better performance.
+      #
       # @note The `:timeout` argument here is *not* the session_timeout for the
       #   connection. rather it is the amount of time we wait for the connection
       #   to be established. The session timeout exchanged with the server is 
@@ -68,12 +74,15 @@ module ZK
       #   [this wiki article](https://github.com/slyphon/zk/wiki/EventDeliveryModel) for more
       #   information and a demonstration.
       #
-      # @param [String] host (see ZK::Client::Base#initialize)
+      # @param host (see Base#initialize)
       #
       # @option opts [true,false] :reconnect (true) if true, we will register
       #   the equivalent of `on_session_expired { zk.reopen }` so that in the
       #   case of an expired session, we will keep trying to reestablish the
-      #   connection.
+      #   connection. You *almost definately* want to leave this at the default.
+      #   The only reason not to is if you already have a handler registered 
+      #   that does something application specific, and you want to avoid a 
+      #   conflict.
       #
       # @option opts [:single,:per_callback] :thread (:single) choose your event
       #   delivery model:
@@ -112,6 +121,8 @@ module ZK
       #   operations with the client as you will get a NoMethodError (the
       #   underlying connection is nil).
       #
+      # @return [Threaded] a new client instance
+      #
       # @see Base#initialize
       def initialize(host, opts={}, &b)
         super(host, opts)

data/lib/zk/client/unixisms.rb

@@ -2,6 +2,7 @@ module ZK
   module Client
     module Unixisms
       include ZookeeperConstants
+      include Exceptions
 
       # Creates all parent paths and 'path' in zookeeper as persistent nodes with
       # zero data.
@@ -21,12 +22,12 @@ module ZK
         # this could get expensive w/ psychotically long paths
 
         create(path, '', :mode => :persistent)
-      rescue Exceptions::NodeExists
+      rescue NodeExists
         return
-      rescue Exceptions::NoNode
+      rescue NoNode
         if File.dirname(path) == '/'
           # ok, we're screwed, blow up
-          raise Exceptions::NonExistentRootError, "could not create '/', are you chrooted into a non-existent path?", caller
+          raise NonExistentRootError, "could not create '/', are you chrooted into a non-existent path?", caller
         end
 
         mkdir_p(File.dirname(path))
@@ -43,7 +44,7 @@ module ZK
 
             delete(path)
             nil
-          rescue Exceptions::NoNode
+          rescue NoNode
           end
         end
       end
@@ -103,19 +104,27 @@ module ZK
         ZK::Find.find(self, *paths, &block)
       end
 
-      # Will _safely_ block the caller until `abs_node_path` has been removed.
-      # This is trickier than it first appears. This method will wake the caller
-      # if a session event occurs that would ensure the event would never be
-      # delivered, and also checks to make sure that the caller is not calling
-      # from the event distribution thread (which would cause a deadlock).
-      #
-      # @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!
+      # Will _safely_ block the caller until `abs_node_path` has been removed
+      # (this is trickier than it appears at first). This method will wake the
+      # caller if a session event occurs that would ensure the event would
+      # never be delivered. 
       #
       # @raise [Exceptions::InterruptedSession] If a session event occurs while we're
       #   blocked waiting for the node to be deleted, an exception that
-      #   mixes in the InterruptedSession module will be raised. 
+      #   mixes in the InterruptedSession module will be raised, so for convenience,
+      #   users can just rescue {InterruptedSession}.
+      #
+      # @raise [ZookeeperExceptions::ZookeeperException::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
+      #   when we receive `ZOO_CONNECTING_STATE` while blocking waiting for
+      #   a deleted event. Includes the {InterruptedSession} module.
+      #
+      # @raise [ZookeeperExceptions::ZookeeperException::ConnectionClosed] raised
+      #   when we receive `ZOO_CLOSED_STATE` while blocking waiting for
+      #   a deleted event. Includes the {InterruptedSession} module.
       #
       def block_until_node_deleted(abs_node_path)
         subs = []

data/lib/zk/client.rb

@@ -23,6 +23,7 @@ module ZK
     }.freeze unless defined?(STATE_SYM_MAP)
 
     class << self
+      # (see Threaded#initialize)
       def new(*a, &b)
         Threaded.new(*a, &b)
       end

data/lib/zk/event_handler.rb

@@ -5,7 +5,7 @@ module ZK
   #
   # you never really need to initialize this yourself
   class EventHandler
-    include org.apache.zookeeper.Watcher if defined?(JRUBY_VERSION)
+    include Java::OrgApacheZookeeper::Watcher if defined?(JRUBY_VERSION)
     include ZK::Logging
 
     # @private

data/lib/zk/exceptions.rb

@@ -74,27 +74,30 @@ module ZK
       include InterruptedSession
     end
 
-    ERROR_MAP = {
-      SYSTEMERROR             => SystemError,
-      RUNTIMEINCONSISTENCY    => RunTimeInconsistency,
-      DATAINCONSISTENCY       => DataInconsistency,
-      CONNECTIONLOSS          => ConnectionLoss,
-      MARSHALLINGERROR        => MarshallingError,
-      UNIMPLEMENTED           => Unimplemented,
-      OPERATIONTIMEOUT        => OperationTimeOut,
-      BADARGUMENTS            => BadArguments,
-      APIERROR                => ApiError,
-      NONODE                  => NoNode,
-      NOAUTH                  => NoAuth,
-      BADVERSION              => BadVersion,
-      NOCHILDRENFOREPHEMERALS => NoChildrenForEphemerals,
-      NODEEXISTS              => NodeExists,
-      NOTEMPTY                => NotEmpty,
-      SESSIONEXPIRED          => SessionExpired,
-      INVALIDCALLBACK         => InvalidCallback,
-      INVALIDACL              => InvalidACL,
-      AUTHFAILED              => AuthFailed,
-    }.freeze unless defined?(ERROR_MAP)
+    silence_warnings do
+      # @private
+      ERROR_MAP = {
+        SYSTEMERROR             => SystemError,
+        RUNTIMEINCONSISTENCY    => RunTimeInconsistency,
+        DATAINCONSISTENCY       => DataInconsistency,
+        CONNECTIONLOSS          => ConnectionLoss,
+        MARSHALLINGERROR        => MarshallingError,
+        UNIMPLEMENTED           => Unimplemented,
+        OPERATIONTIMEOUT        => OperationTimeOut,
+        BADARGUMENTS            => BadArguments,
+        APIERROR                => ApiError,
+        NONODE                  => NoNode,
+        NOAUTH                  => NoAuth,
+        BADVERSION              => BadVersion,
+        NOCHILDRENFOREPHEMERALS => NoChildrenForEphemerals,
+        NODEEXISTS              => NodeExists,
+        NOTEMPTY                => NotEmpty,
+        SESSIONEXPIRED          => SessionExpired,
+        INVALIDCALLBACK         => InvalidCallback,
+        INVALIDACL              => InvalidACL,
+        AUTHFAILED              => AuthFailed,
+      }.freeze
+    end
 
     # base class of ZK generated errors (not driver-level errors)
     class ZKError < StandardError; end

data/lib/zk/locker/exclusive_locker.rb

@@ -0,0 +1,75 @@
+module ZK
+  module Locker
+    # An exclusive lock implementation
+    #
+    # If the name 'dingus' is given, then in the case of an exclusive lock, the
+    # algorithm works like:
+    #
+    # * lock_path = `zk.create("/_zklocking/dingus/ex", :sequential => true, :ephemeral => true)`
+    # * extract the digit from the lock path
+    # * of all the children under '/_zklocking/dingus', do we have the lowest digit?
+    #   * __yes__: then we hold the lock, if we're non-blocking, return true
+    #   * __no__: is the lock blocking?
+    #       * __yes__: then set a watch on the next-to-lowest node and sleep the current thread until that node has been deleted
+    #       * __no__: return false, you lose
+    # 
+    class ExclusiveLocker < LockerBase
+      # 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)
+        return true if @locked
+        create_lock_path!(EXCLUSIVE_LOCK_PREFIX)
+
+        if got_write_lock?
+          @locked = true
+        elsif blocking
+          in_waiting_status do
+            block_until_write_lock!
+          end
+        else
+          cleanup_lock_path!
+          false
+        end
+      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)
+
+          raise WeAreTheLowestLockNumberException if my_idx == 0
+
+          ary[(my_idx - 1)] 
+        end
+
+        # @private
+        def got_write_lock?
+          ordered_lock_children.first == lock_basename
+        end
+
+        # @private
+        def block_until_write_lock!
+          begin
+            path = [root_lock_path, next_lowest_node].join('/')
+            logger.debug { "SharedLocker#block_until_write_lock! path=#{path.inspect}" }
+            @zk.block_until_node_deleted(path)
+          rescue WeAreTheLowestLockNumberException
+          end
+
+          @locked = true
+        end
+    end # ExclusiveLocker
+  end # Locker
+end # ZK
+