zkruby 3.4.3 → 3.4.4.rc3

data/.gitignore

@@ -0,0 +1,11 @@
+#No hidden files (except for .gitignore)
+.*
+!.gitignore
+!.yardopts
+# Gems should not checking Gemfile.lock
+Gemfile.lock
+#Files generated by rake
+lib/jute/
+*.out
+doc
+pkg

data/.yardopts

@@ -0,0 +1,2 @@
+-
+History.txt

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in rfuse.gemspec
+gemspec

data/README.rdoc

@@ -1,6 +1,6 @@
 = zkruby
 
-* https://github.com/lwoggardner/zkruby
+* http://rubygems.org/gems/zkruby
 
 == DESCRIPTION:
 
@@ -10,6 +10,9 @@ Pure ruby client for ZooKeeper (http://zookeeper.apache.org)
 
 Supports full ZooKeeper API, synchronous or asynchronous style, watches etc.. with implementations over EventMachine or plain old Ruby IO/Threads
 
+Other ruby libraries for zookeeper tend to use the underlying C/Java client libraries while zkruby
+implements the zookeeper wire protocol directly.
+
 Advantages:
 * Rubyist API - with block is asynchronous, without block is synchronous
 * Avoids conflicts between various Ruby threading models and the C/Java apis
@@ -18,9 +21,9 @@ Advantages:
 
 Disadvantages:
 * Duplicated code from Java/C libraries, particularly around herd effect protection
-* Maintain in parallel with breaking changes in protocol which are possibly more likely 
-  than breaking changes in the client API
-* Probably not as optimised in terms of performance (but your client code is ruby anyway) 
+* Needs to keep up with changes in wire protocol which are possibly more likely 
+  than changes in the client API
+* Possibly not as optimised in terms of performance (but your client code is ruby anyway) 
 * Not production tested (yet- do you want to be the first?)  
 
 == SYNOPSIS:
@@ -77,27 +80,27 @@ Disadvantages:
 
 == DEVELOPERS:
 
-Checkout the zookeeper source from http://zookeeper.apache.org
+Download ZooKeeper from http://zookeeper.apache.org
 
-Checkout the zkruby source into the contrib directory  
+Create a conf/zoo.cfg file (copying sample.zoo.cfg is fine)
 
-Install hoe
+Checkout the zkruby source into the contrib directory
 
-  $ (sudo) gem install hoe 
+Copy (if different) src/zookeeper.jute to contrib/zkruby/src/zookeeper.jute
 
-Install other dependencies
+Get gem dependencies
 
-  $ rake check_extra_deps
+  $ bundle install 
 
 Generate docs and run the tests/specs
 
-  $ rake newb
+  $ rake 
 
 == LICENSE:
 
 (The MIT License)
 
-Copyright (c) 2011 
+Copyright (c) 2012 Grant Gardner
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/Rakefile

@@ -1,39 +1,34 @@
-# -*- ruby -*-
-# hoe  2.12.5 goes looking for the plugins so we have to do it this way..
-$LOAD_PATH.unshift File.dirname(__FILE__) + '/jute/lib'
+#!/usr/bin/env rake
+$:.unshift "jute/lib"
 
-require 'rubygems'
-require 'hoe'
+require 'rake/clean'
+require 'yard'
+require './yard_ext/enum_handler.rb'
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+require 'jute/task'
 
-begin
-    require './yard_ext/enum_handler'
-rescue LoadError => err
-     warn "%p while trying to load yard extensions: %s" % [ err.class, err.message ]
+RSpec::Core::RakeTask.new
+RSpec::Core::RakeTask.new(:perf_spec) do |t|
+      t.rspec_opts = "--tag perf"
 end
-    
 
+YARD::Rake::YardocTask.new 
 
-# Hoe.plugin :compiler
-#Hoe.plugin :gem_prelude_sucks
-Hoe.plugin :git
-# Hoe.plugin :inline
-# Hoe.plugin :racc
-# Hoe.plugin :rubyforge
-Hoe.plugin :yard
-Hoe.plugin :jute
-
-Hoe.spec 'zkruby' do
-  self.readme_file="README.rdoc"
-  developer('Grant Gardner', 'grant@lastweekend.com.au')
-  dependency 'slf4r' , '~> 0.4.2' 
-  dependency 'eventmachine', '~> 0.12.10', :development 
-  dependency 'strand', '~> 0.1.0', :development 
-  dependency 'logging', '>= 1.4.1', :development
-  dependency 'rspec', '>=2.7.0', :development
-  dependency 'hoe-yard', '>=0.1.2', :development
-
-  self.jute_modules = {
+Jute::Task.new() do |t|
+  t.modules = {
       "org.apache.zookeeper.data" => "ZooKeeper::Data",
       "org.apache.zookeeper.proto" => "ZooKeeper::Proto"}
 end
-# vim: syntax=ruby
+
+task :perf_spec => :jute
+task :spec => :jute
+task :build => :jute
+task :install => :jute
+task :release => :jute
+task :yard => :jute
+
+task :default => [:spec,:yard]
+
+CLEAN.include "*.out","Gemfile.lock",".yardoc/"
+CLOBBER.include "doc/","pkg/","lib/jute"

data/jute/lib/hoe/jute.rb

@@ -8,8 +8,8 @@ module Hoe::Jute
    #attr_accessor :jute_compiler
    def initialize_jute
         self.jute_tasks = [:test,:spec,:package]
-        dependency 'citrus', '~> 2.4.0', :development
         #dependency 'jute' # if jute is ever a separate gem
+        dependency 'citrus', '~> 2.4.0', :development
         dependency 'bindata', '~> 1.4.1'
    end
 

data/jute/lib/jute/task.rb

@@ -0,0 +1,62 @@
+# coding: utf-8
+require 'rake/tasklib'
+require 'jute'
+
+class Jute::Task < Rake::TaskLib
+
+   attr_accessor :modules
+   attr_accessor :files
+   attr_accessor :pathmap
+
+   def initialize name = :jute
+        
+        defaults
+
+        @name = name
+
+        yield self if block_given?
+
+        define_jute_tasks
+   end
+
+   def defaults
+       @files = "src/jute/*.jute"
+       @pathmap = "%{src,lib}X.rb"
+   end
+
+   def define_jute_tasks
+	desc "Compile jute files to ruby classes"
+	task jute_task_name
+
+	raise "modules hash must be defined" unless Hash === @modules
+        FileList.new(@files).each do | source |
+           target = source.pathmap(@pathmap)
+
+           target_dir = target.pathmap("%d")
+           directory target_dir
+
+           file target => [source,target_dir] do
+                compile_jute(source,target)
+           end
+           task jute_task_name => target
+        end
+   end
+
+   def jute_task_name
+	@name
+   end
+
+   def compile_jute(source,target)
+ 
+      @jute_compiler = ::Jute::Compiler.new() unless @jute_compiler
+
+      File.open(source) do |input|
+        File.open(target,"w") do |output|
+             puts "Compiling #{input.inspect} to #{output.inspect}"
+             @jute_compiler.compile(input,output,modules)
+        end
+      end
+   end
+end
+
+

data/lib/em_zkruby.rb

@@ -1,4 +1,4 @@
-# This is the main require for standard ruby io/thread based binding
+# This is the main require for the eventmachine based binding
 
 require 'zkruby/zkruby'
 require 'zkruby/eventmachine'

data/lib/zkruby/async_op.rb

@@ -0,0 +1,193 @@
+module ZooKeeper
+
+    # Returned by asynchronous calls
+    # 
+    # @example
+    #    op = zk.stat("\apath") { |stat| something_with_stat() }
+    #
+    #    op.async_rescue ZK::Error::SESSION_EXPIRED do 
+    #        puts "Ignoring session expired"
+    #        result_when_session_expired()
+    #    end
+    #    
+    #    op.async_rescue ZK::Error::CONNECTION_LOST do |ex|
+    #        puts "Retrying stat due to connection lost"
+    #        op.async_retry()
+    #        # the result of this block is ignored!
+    #    end
+    #
+    #    begin
+    #       result_of_somthing_with_stat = op.value
+    #    rescue StandardError => ex
+    #       puts "Oops"
+    #    end
+    #
+    #
+    class AsyncOp
+
+        # @api private
+        def initialize(event_loop,callback,&operation)
+            @event_loop = event_loop
+            @operation = operation
+            @callback = callback
+            @mutex,@cv = Strand::Mutex.new(), Strand::ConditionVariable.new()
+            begin
+                execute()
+            rescue ZooKeeper::Error => ex
+                # Capture any initial exception
+                # The only expected condition is :session_expired
+                @op_error = ex
+                logger.debug { "Error during initial call #{ex}" }
+            end
+        end
+
+        # @param [Proc,#to_proc] block the error callback as a Proc
+        # @deprecated use {#async_rescue}
+        def errback=(block)
+            async_rescue(&block)
+        end
+
+        #Rescue asynchronous exceptions in a similar manner to normal
+        #ruby. Unfortunately rescue is a reserved word
+        # @param matches [Class,...] subclasses of Exception to match, defaults to {::StandardError}
+        # @param errblock the block to call if an error matches
+        # @return self
+        # @yieldparam [Exception] ex the exception raised by the async operation OR by its callback
+        def async_rescue(*matches,&errblock)
+            matches << StandardError if matches.empty?
+            rescue_blocks << [ matches ,errblock ]
+            if @op_error && matches.any? { |m| m  === @op_error }
+                begin
+                    @allow_retry = true
+                    @op_rescue= [ nil, errblock.call(@op_error) ]
+                rescue StandardError => ex
+                    @operation_rescue_result = [ ex, nil ]
+                ensure
+                    @resumed = true
+                    @op_error = nil
+                    @allow_retry = false
+                end
+            end
+            self
+        end
+        alias :on_error :async_rescue
+        alias :op_rescue :async_rescue
+
+        # @deprecated
+        alias :errback :async_rescue
+
+
+        # Must only be called inside a block supplied to {#async_rescue}
+        # Common case is to retry on connection lost
+        # Retrying :session_expired is guaranteed to give infinite loops!
+        def async_retry()
+            raise ProtocolError "cannot retry outside of a rescue block" unless @allow_retry
+            begin
+                execute()
+                nil
+            rescue ZooKeeper::Error => ex
+                error,result = process_response(ex,nil)
+                if resumed?
+                    raise error if error
+                    return result
+                end
+            end
+        end
+
+        alias :op_retry :async_retry
+        alias :try_again :async_retry
+
+        # Wait for the async op to finish and returns its value
+        # @return result of the operation's callback or matched rescue handler
+        # @raise [StandardError] any unrescued exception
+        def value();
+            if @op_error
+                raise @op_error
+            elsif @op_rescue
+                error, result = @op_rescue
+                raise error if error
+                return result
+            else
+                wait_value()
+            end
+        end
+        
+        # @api private
+        attr_accessor :backtrace
+
+        # @api private
+        def resume(op_error,response)
+            mutex.synchronize do
+                # remember this mutex is only used to wait for this response anyway
+                # so synchronizing here is not harmful even if processing the response
+                # includes a long running callback. (which can't create deadlocks
+                # by referencing this op!
+                @resumed = true
+                @error, @result = process_response(op_error,response)
+                cv.signal() if resumed? 
+            end
+        end
+
+        private
+        attr_reader :callback, :operation, :event_loop
+        attr_reader :mutex, :cv, :error, :result
+        
+        def execute()
+            @op_error = nil
+            @op_rescue = nil
+            @resumed = false
+            operation.call(self)
+            true
+        end
+
+        def resumed?
+            @resumed 
+        end
+
+        def rescue_blocks
+            @rescue_blocks ||= []
+        end
+
+        def process_response(op_error,response)
+            logger.debug { "Processing response #{op_error} #{response}" }
+            
+            # For ZooKeeper errors, set the backtrace to the original caller, rather than the ZK event loop
+            op_error.set_backtrace(@backtrace) if @backtrace && ZooKeeper::Error === op_error
+            
+            begin
+                return [ nil, callback.call(response) ] unless op_error
+            rescue Exception => ex #enable clients to rescue Exceptions
+                op_error = ex
+            end
+
+            matches,rb = rescue_blocks.detect() { |matches,errblock| matches.any? { |m| m === op_error } }
+            return [ op_error, nil ] unless rb
+
+            begin
+                @allow_retry = true
+                return [ nil, rb.call(op_error) ]
+            rescue StandardError => ex
+                return [ ex , nil ]
+            ensure
+                @allow_retry = false
+            end
+        end
+
+        def wait_value()
+            if event_loop.current?
+                #Waiting in the event loop (eg made a synchronous call inside a callback)
+                #Keep processing events until we are resumed
+                until resumed? || event_loop.dead?
+                    event_loop.pop_event_queue()
+                end
+            else
+                mutex.synchronize { 
+                    cv.wait(mutex) unless resumed?
+                }
+            end
+
+            raise error if error
+            result
+        end
+    end
+end

data/lib/zkruby/client.rb

@@ -48,7 +48,7 @@ module ZooKeeper
 
 
     # Combine permissions constants
-    # @param [Perms] perms... list of permissions to combine, can be {Perms} constants, symbols or ints 
+    # @param [Perms...] perms list of permissions to combine, can be {Perms} constants, symbols or ints 
     # @return [Fixnum] integer representing the combined permission
     def self.perms(*perms)
         perms.inject(0) { | result, perm | result = result | Perms.get(perm) }
@@ -56,7 +56,7 @@ module ZooKeeper
 
     # Convenience method to create a zk Identity
     # @param [String] scheme
-    # @param [String] identity
+    # @param [String] id
     # @return [Data::Identity] the encapsulated identity for the given scheme
     def self.id(scheme,id)
         Data::Identity.new(:scheme => scheme, :identity => id)
@@ -65,7 +65,7 @@ module ZooKeeper
     # Convenience method to create a zk ACL
     #    ZK.acl(ZK.id("world","anyone"), ZK::Perms.DELETE, ZL::Perms.WRITE)
     # @param [Data::Identity] id
-    # @param [Perms] *perms list of permissions
+    # @param [Perms...] perms list of permissions
     # @return [Data::ACL] an access control list
     # @see #perms
     # 
@@ -108,8 +108,6 @@ module ZooKeeper
     CURRENT = :zookeeper_current
     # Main method for connecting to a client
     # @param addresses [Array<String>] list of host:port for the ZK cluster as Array or comma separated String
-    # @option options [Class]  :binding binding optional implementation class
-    #    either {EventMachine::Binding} or {RubyIO::Binding} but normally autodiscovered
     # @option options [String] :chroot chroot path.
     #    All client calls will be made relative to this path 
     # @option options [Watcher] :watch the default watcher
@@ -118,37 +116,48 @@ module ZooKeeper
     # @yieldparam [Client]
     # @return [Client] 
     def self.connect(addresses,options={},&block)
-        if options.has_key?(:binding)
-            binding_type = options[:binding]
+
+        binding_module = if Strand.event_machine?                 
+            require 'zkruby/eventmachine'
+            ZooKeeper::EventMachine::Binding
         else
-            binding_type = @bindings.detect { |b| b.available? }
-            raise ProtocolError,"No available binding" unless binding_type
+            require 'zkruby/rubyio'
+            ZooKeeper::RubyIO::Binding
         end
-        binding = binding_type.new()
-        session = Session.new(binding,addresses,options)
-        client = Client.new(binding)
-        binding.start(client,session)
 
+        logger.debug { "Using binding #{binding_module}" }
+        session = Session.new(addresses,options)
+        # Extend the appropriate #connect method into the session
+        session.extend(binding_module)
+
+        client = Client.new(session)
+
+        session.start(client)
+        
         return client unless block_given?
 
-        binding_type.context() do |storage|
-            @binding_storage = storage
-            storage.current[CURRENT] ||= []
-            storage.current[CURRENT].push(client)
-            begin
-                block.call(client)
-            ensure
-                storage.current[CURRENT].pop
-                client.close() unless session.closed?
-            end
+        storage = Strand.current[CURRENT] ||= []
+        storage.push(client)
+        begin
+            yield client
+        ensure
+            storage.pop
+            #TODO this will throw an exception if expired
+            client.close() 
         end
     end
 
-    # within the block supplied to {#connect} this will return the
+    # within the block supplied to {ZooKeeper.connect} this will return the
     # current ZK client
     def self.current
         #We'd use if key? here if strand supported it
-        @binding_storage.current[CURRENT].last if @binding_storage.current[CURRENT]
+        Strand.current[CURRENT].last if Strand.current[CURRENT]
+    end
+
+    # Allow ZK a chance to send its data/ping
+    # particularly required for the eventmachine binding
+    def self.pass
+        Strand.pass
     end
 
     class WatchEvent
@@ -175,7 +184,8 @@ module ZooKeeper
     end
 
 
-    # @abstract.
+    # @abstract
+    # The watch interface
     class Watcher
         # @param [KeeperState] state representing the session state
         #    (:connected, :disconnected, :auth_failed, :session_expired)
@@ -243,7 +253,7 @@ module ZooKeeper
     # All calls operate asynchronously or synchronously based on whether a block is supplied
     #
     # Without a block, requests are executed synchronously and either return results directly or raise
-    # a {Error}
+    # an {Error}
     #
     # With a block, the request returns immediately with a {AsyncOp}. When the server responds the
     # block is passed the results. Errors will be sent to an error callback if registered on the {AsyncOp}
@@ -257,35 +267,36 @@ module ZooKeeper
     # or with state :expired and event :none when the session is finalised 
     class Client
 
+        attr_reader :session
         include Operations
         # @api private
         # See {::ZooKeeper.connect}
-        def initialize(binding)
-            @binding = binding
+        def initialize(session)
+            @session = session 
         end
 
         # Session timeout, initially as supplied, but once connected is the negotiated
         # timeout with the server. 
         def timeout
-            @binding.session.timeout
+            session.timeout
         end
 
         # The currently registered default watcher
         def watcher 
-            @binding.session.watcher
+            session.watcher
         end
 
         # Assign the watcher to the session. This watcher will receive session connect/disconnect/expired
         # events as well as any path based watches registered to the API calls using the literal value "true"
-        # @param [Watcher|Proc] watcher
+        # @param [Watcher,#process_watch,Proc] watcher
         def watcher=(watcher)
-            @binding.session.watcher=watcher
+            session.watcher=watcher
         end
 
         # Retrieve the list of children at the given path
         # @overload children(path,watch=nil)
         #    @param [String] path 
-        #    @param [Watcher] if supplied sets a child watch on the given path
+        #    @param [Watcher,#process_watch,Proc] if supplied sets a child watch on the given path
         #    @return [Data::Stat,Array<String>] stat,children stat of path and the list of child nodes
         #    @raise [Error] 
         # @overload children(path,watch=nil)
@@ -321,7 +332,7 @@ module ZooKeeper
         # Retrieve data
         # @overload get(path,watch=nil)
         #   @param [String] path
-        #   @param [Watcher] watch optional data watch to set on this path
+        #   @param [Watcher,#process_watch,Proc] watch optional data watch to set on this path
         #   @return [Data::Stat,String] stat,data at path 
         #   @raise [Error]
         # @overload get(path,watch=nil)
@@ -342,19 +353,19 @@ module ZooKeeper
         # Retrieve the {Data::Stat} of a path, or nil if the path does not exist
         # @overload exists(path,watch=nil)
         #   @param [String] path
-        #   @param [Watcher] wath optional exists watch to set on this path
+        #   @param [Watcher,#process_watch,Proc] watch optional exists watch to set on this path
         #   @return [Data::Stat] Stat of the path or nil if the path does not exist
         #   @raise [Error]
         # @overload exists(path,watch=nil)
         #   @return [AsyncOp] asynchronous operation
         #   @yieldparam [Data:Stat] stat Stat of the path or nil if the path did not exist
-        def exists(path,watch=nil,&blk)
+        def exists(path,watch=nil,&callback)
             return synchronous_call(:exists,path,watch)[0] unless block_given?
             path = chroot(path) 
 
             req = Proto::ExistsRequest.new(:path => path, :watch => watch)
             queue_request(req,:exists,3,Proto::ExistsResponse,:exists,watch,ExistsPacket) do | response |
-                blk.call( response.nil? ? nil : response.stat )
+                callback.call( response.nil? ? nil : response.stat )
             end
         end
         alias :exists? :exists
@@ -445,13 +456,13 @@ module ZooKeeper
 
         # Close the session
         # @overload close()
-        #    @raise [Error]
+        #    @raise [Error] 
         # @overload close()
         #    @return [AsyncOp] asynchronous operation
         #    @yield [] callback invoked when session is closed 
         def close(&blk)
             return synchronous_call(:close) unless block_given?
-            @binding.close(&blk)
+            session.close(&blk)
         end
 
         # @api private
@@ -501,23 +512,26 @@ module ZooKeeper
             yield txn
             txn.commit
         end
-        private
 
-        def session
-            @binding.session
-        end
 
+        private
+
+        # This is where the magic happens!
         def synchronous_call(method,*args)
+            # Re-enter the calling method in asynchronous style
             op = self.send(method,*args) do |*results|
                 results 
             end
+
+            # Remove this call from the stored backtrace
             op.backtrace = op.backtrace[2..-1] if op.backtrace
 
+            # Wait for the asynchronous op to finish and return its value
             op.value
         end
 
         def queue_request(*args,&blk)
-            op = @binding.queue_request(*args,&blk)
+            op = session.request(*args,&blk)
             op.backtrace = caller[1..-1]
             op
         end
@@ -540,7 +554,8 @@ module ZooKeeper
     # If the transaction fails none of these callbacks will be executed.
     class Transaction
         include Operations
-        #:nodoc
+        # @api private
+        # See {Client#transaction}
         def initialize(client,session)
             @client = client
             @session = session