em-hyperdex-client 0.3.1 → 0.3.2

data/.gitignore

@@ -1,3 +1,5 @@
 Gemfile.lock
 /pkg
 /html
+/.yardoc
+/doc

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/Rakefile

@@ -17,13 +17,10 @@ task :release do
 	sh "git release"
 end
 
-require 'rdoc/task'
+require 'yard'
 
-RDoc::Task.new do |rd|
-	rd.main = "README.md"
-	rd.title = 'em-pg-client-helper'
-	rd.markup = "markdown"
-	rd.rdoc_files.include("README.md", "lib/**/*.rb")
+YARD::Rake::YardocTask.new :doc do |yardoc|
+	yardoc.files = %w{lib/**/*.rb - README.md}
 end
 
 desc "Run guard"

data/em-hyperdex-client.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |s|
 
 	s.add_runtime_dependency "eventmachine", "~> 1.0"
 	s.add_runtime_dependency "git-version-bump", "~> 0.10"
-	s.add_runtime_dependency "hyperdex", '>= 1.4.4.3'
+	s.add_runtime_dependency "hyperdex", '>= 1.4.5.pre', '< 2'
 
 	s.add_development_dependency 'bundler'
 	s.add_development_dependency 'eventmachine'
@@ -30,4 +30,5 @@ Gem::Specification.new do |s|
 	s.add_development_dependency 'rake'
 	s.add_development_dependency 'rdoc'
 	s.add_development_dependency 'rspec'
+	s.add_development_dependency 'yard', '~> 0.7'
 end

data/lib/em-hyperdex-client.rb

@@ -1,19 +1,51 @@
 require 'hyperdex'
 require 'eventmachine'
 
-module EM; end
-module EM::HyperDex; end
+module EM; end  #:nodoc:
+module EM::HyperDex; end  #:nodoc:
 
+# An EventMachine-enabled client for [HyperDex](http://hyperdex.org/).
+#
+# This is a fairly straightforward async-friendly interface to the hyperdex
+# NoSQL data store.  All of the normal (synchronous) methods that you are
+# used to using are available, except that they're automatically async.
+# Schweeeeeet.
+#
+# Using it is quite simple (for an EM client, anyway...).  You just create
+# an instance of `EM::HyperDex::Client`, and then call (almost) any of the
+# standard HyperDex methods you know and love against it, with the same
+# arguments.  The only difference is that you can pass a block to the
+# method, indicating what you want to do once the request is complete, and
+# the method returns a Deferrable which you can define callbacks and
+# errbacks.  The callback will be passed whatever the HyperDex data method
+# would ordinarily return, in a synchronous world.
+#
+# Searching methods ({#search}, {#sorted_search}) work *slightly*
+# differently.  Instead of the entire resultset being passed back in a
+# single callback, the callback is executed *after* the result set has been
+# processed.  Each item in the search result is accessed via
+# {EnumerableDeferrable#each} on the deferrable that is returned from the
+# {#search} method.  See the docs for {#search} and {#sorted_search} for
+# examples of what this looks like.
+#
 class EM::HyperDex::Client
-	def initialize(host, port)
+	# Create a new `EM::HyperDex::Client` for you to play with.
+	#
+	# This method does **not** take a callback block; the client is created
+	# synchronously.  However, this isn't the problem you might otherwise
+	# expect it to be, because initializing a client doesn't make any network
+	# connections or otherwise potentially-blocking calls; rather, it simply
+	# initializes some data structures and then returns.
+	#
+	# @param host [String] A hostname or IP address (v4 or v6) of a coordinator
+	#   within the cluster to make initial contact.
+	#
+	# @param port [Integer] The port of the coordinator you wish to contact.
+	#
+	def initialize(host = 'localhost', port = 1982)
 		@client = HyperDex::Client::Client.new(host, port)
 		@failed = false
 		@outstanding = {}
-
-		if ::EM.reactor_running?
-			@em_conn = ::EM.watch(@client.poll_fd, Watcher, self)
-			@em_conn.notify_readable = true
-		end
 	end
 
 	ASYNC_METHODS = HyperDex::Client::Client.
@@ -21,22 +53,22 @@ class EM::HyperDex::Client
 	                  map(&:to_s).
 	                  grep(/^async_/).
 	                  map { |m| m.gsub(/^async_/, '') }
+	private_constant :ASYNC_METHODS
 
 	ASYNC_METHODS.each do |m|
 		hyperdex_method = "async_#{m}"
 
 		define_method(m) do |*args, &block|
-			df = ::EM::DefaultDeferrable.new
-
 			if @failed
-				return df.tap do |df|
-					df.fail(RuntimeError.new("This client has failed.  Please open a new one."))
-				end
+				return failed_deferrable("This client has failed.  Please open a new one.")
 			end
 
+			df = ::EM::Completion.new
+			df.callback(&block) if block
+
 			begin
 				if ::EM.reactor_running?
-					@outstanding[@client.__send__(hyperdex_method, *args)] = df
+					add_outstanding(@client.__send__(hyperdex_method, *args), df)
 				else
 					df.succeed(@client.__send__(m, *args))
 				end
@@ -49,34 +81,106 @@ class EM::HyperDex::Client
 	end
 
 	ITERATOR_METHODS = %w{search sorted_search}
+	private_constant :ITERATOR_METHODS
+
+	# @!macro search_params
+	#   @param spacename [#to_s] The name of the hyperdex space to search
+	#
+	#   @param predicates [Hash<#to_s, HyperDex::Client::Predicate>] A
+	#     collection of predicates to apply to the search.
+	#
+	#   @return [EnumerableDeferrable] a deferrable which responds to
+	#     {EnumerableDeferrable#each each} to return the search results.
+	#   
+	#
+	# @!method search(spacename, predicates)
+	#
+	# Perform a search for all objects in the specified space that match the
+	# predicates provided.
+	#
+	# @macro search_params
+	#
+	# @example iterating through search results
+	#   c = EM::HyperDex::Client.new
+	#   c.search(:test, :towels => HyperDex::Client::GreaterThan.new(42)).each do |r|
+	#     puts "This is an object with a high towel count: #{r.inspect}"
+	#   end.callback do
+	#     puts "Towel search complete"
+	#   end.errback do |ex|
+	#     puts "Towel search failed: #{ex.class}: #{ex.message}"
+	#   end
+	#
 
+	# @!method sorted_search(spacename, predicates, sortby, limit, maxmin)
+	#
+	# Perform a search for all objects in the specified space that match
+	# the predicates provided, sorting the results and optionally returning
+	# only a subset of the results.
+	#
+	# @macro search_params
+	#
+	# @param sortby [#to_s] the attribute to sort the results by
+	#
+	# @param limit [Integer] the maximum number of results to return
+	#
+	# @param maxmin [String] Maximize (`"max"`) or minimize (`"min"`)
+	#   (I shit you not, that's what the upstream docs say)
+	#
+	# @todo Document the `maxmin` parameter *properly*.
+	#
+	# @see #search
+	#
 	ITERATOR_METHODS.each do |m|
 		define_method(m) do |*args, &block|
 			if @failed
-				return ::EM::DefaultDeferrable.new.tap do |df|
-					df.fail(RuntimeError.new("This client has failed.  Please open a new one."))
+				return failed_deferrable("This client has failed.  Please open a new one.")
+			end
+
+			begin
+				iter = @client.__send__(m, *args)
+			rescue StandardError => ex
+				return EM::Completion.new.tap do |df|
+					df.fail(ex)
 				end
 			end
 
-			iter = @client.__send__(m, *args)
-			df = DeferrableEnumerable.new(iter)
-			df.callback(&block) if block_given?
+			df = EnumerableDeferrable.new(iter)
+			df.callback(&block) if block
 
-			begin
-				@outstanding[iter] = df
-			rescue HyperDex::Client::HyperDexClientException => ex
-				::EM::DefaultDeferrable.new.fail(ex)
+			if ::EM.reactor_running?
+				add_outstanding(iter, df)
+			else
+				begin
+					until (item = iter.next).nil?
+						df.item_available(item)
+					end
+					df.item_available(nil)
+				rescue Exception => ex
+					df.fail(ex)
+				end
 			end
+
+			df
 		end
 	end
 
+	# Callback from the `EM.watch` system, to poke us when a response is
+	# ready to be processed.
+	#
+	# @api private
+	#
 	def handle_response
 		begin
-			df = @outstanding.delete(op = @client.loop(0))
+			op = @client.loop(0)
 		rescue HyperDex::Client::HyperDexClientException
 			# Something has gone wrong, and we're just going to take our bat
 			# and ball and go home.
 			@outstanding.values.each { |op| op.fail(ex) }
+			@outstanding = {}
+
+			# Call a dummy get_outstanding so EM stops watching the socket
+			get_outstanding(nil)
+
 			@failed = true
 			return
 		end
@@ -90,9 +194,14 @@ class EM::HyperDex::Client
 			return
 		end
 
+		df = get_outstanding(op)
+
 		begin
 			if df.respond_to?(:item_available)
 				df.item_available
+				# Put the deferrable back in the outstanding ops hash if
+				# there's more items to go
+				add_outstanding(op, df) unless df.completed?
 			else
 				df.succeed(op.wait)
 			end
@@ -101,47 +210,133 @@ class EM::HyperDex::Client
 		end
 	end
 
-	def close
-		@outstanding.each { |o| o.wait }
-		@em_conn.detach
-		@client = nil
+	# Associate an in-progress operation with the deferrable that will be
+	# completed when the operation completes.  Also handles telling EM to
+	# start watching the client's `poll_fd` if necessary.
+	#
+	def add_outstanding(op, df)
+		# If we don't have any operations already in progress, then
+		# we aren't watching the poll_fd, so we probably want to start
+		# doing that now
+		if @outstanding.empty?
+			@em_conn = ::EM.watch(@client.poll_fd, Watcher, self)
+			@em_conn.notify_readable = true
+		end
+
+		@outstanding[op] = df
+	end
+
+	# Retrieve the deferrable associated with the specified operation, if
+	# one exists.  Also handles telling EM to stop watching the `poll_fd`,
+	# if there are now no more outstanding operations.
+	def get_outstanding(op)
+		@outstanding.delete(op).tap do
+			if @outstanding.empty?
+				@em_conn.detach
+				@em_conn = nil
+			end
+		end
+	end
+
+	private
+	# Return a new deferrable that has failed with a `RuntimeError` with the
+	# given message.
+	#
+	def failed_deferrable(msg)
+		::EM::Completion.new.tap do |df|
+			df.fail(RuntimeError.new(msg))
+		end
 	end
 
+	# Mix-in module for EM.watch.
+	#
+	# @api private
+	#
 	module Watcher
+		# Create the watcher.
+		#
+		# @api private
 		def initialize(em_client)
 			@em_client = em_client
 		end
 
+		# Handle the fact that more data is available.
+		#
+		# @api private
 		def notify_readable
 			@em_client.handle_response
 		end
 	end
 
-	class DeferrableEnumerable
-		include Enumerable
-		include ::EM::Deferrable
-
+	# A deferrable that can be enumerated.
+	#
+	# This is a really *freaky* kind of a deferrable.  It accepts the usual
+	# `callback` and `errback` blocks, but it *also* has a special {#each}
+	# callback, which will cause the block provided for each item in the
+	# search result set.  Once the result set has been enumerated, the
+	# `callback` will be called.
+	#
+	# @todo Define a set of other Enumerable methods that can be usefully
+	#   used asynchronously (if there are any), like perhaps `#map`,
+	#   `#inject`, etc.
+	#
+	class EnumerableDeferrable < EM::Completion
+		# Create a new EnumerableDeferrable
+		#
+		# @param iter [HyperDex::Client::Iterator] What to call `#next` on
+		#   to get the next item.
+		#
+		# @api private
+		#
 		def initialize(iter)
 			@iter = iter
+			@items = []
+			super()
 		end
 
+		# Define a block to call for each item in the result set.
+		#
+		# @yield the next available item in the result set
+		#
+		# @yieldparam item [Hash<Symbol, Object>] the hyperdex value object
+		#
 		def each(&blk)
-			return self unless block_given?
+			return Enumeration.new(self) unless block_given?
 
-			@each_block = blk
+			if state == :succeeded
+				@items.each { |i| blk.call(i) }
+			else
+				@each_block = blk
+			end
+
+			self
 		end
 
-		def item_available
-			val = @iter.next
+		# Trigger whenever we know there's an item available.
+		#
+		# @api private
+		#
+		def item_available(val = NoValue)
+			if val == NoValue
+				val = @iter.next
+			end
+
 			if val.nil?
-				succeed
+				self.succeed
 			else
-				begin
-					@each_block.call(val)
-				rescue Exception => ex
-					fail(ex)
+				if @each_block
+					begin
+						@each_block.call(val)
+					rescue Exception => ex
+						fail(ex)
+					end
+				else
+					@items << val
 				end
 			end
 		end
+
+		NoValue = Object.new
+		private_constant :NoValue
 	end
 end

data/spec/get_spec.rb

@@ -0,0 +1,88 @@
+require_relative './spec_helper'
+
+describe "#get" do
+	let(:client) { EM::HyperDex::Client.new }
+
+	it "works when standalone" do
+		expect(mock_client).
+		  to receive(:get).
+		  with(:foo, 42).
+		  and_return("towels")
+
+		client.get(:foo, 42).callback do |v|
+			expect(v).to eq("towels")
+		end
+	end
+
+	it "works inside EM" do
+		in_em do
+			expect_op(:get, [:foo, 42], "towels")
+
+			df = client.get(:foo, 42) do |v|
+				expect(v).to eq("towels")
+				EM.stop
+			end
+
+			expect(df).to be_a(::EM::Completion)
+		end
+	end
+
+	it "works multiple times" do
+		in_em do
+			expect_op(:get, [:foo, 42], "towels")
+			expect_op(:get, [:bar, "baz"], "wombat")
+
+			client.get(:foo, 42) do |v|
+				expect(v).to eq("towels")
+				client.get(:bar, "baz") do |v|
+					expect(v).to eq("wombat")
+					EM.stop
+				end
+			end
+		end
+	end
+
+	it "works in parallel" do
+		in_em do
+			expect_op(:get, [:foo, 42], "towels")
+			expect_op(:get, [:bar, "baz"], "wombat", 0.1)
+			op_count = 2
+
+			client.get(:foo, 42) do |v|
+				expect(v).to eq("towels")
+				op_count -= 1
+			end
+
+			client.get(:bar, "baz") do |v|
+				expect(v).to eq("wombat")
+				op_count -= 1
+			end
+
+			EM.add_periodic_timer(0.0001) do
+				EM.stop if op_count == 0
+			end
+		end
+	end
+
+	it "works with out-of-order responses" do
+		in_em do
+			expect_op(:get, [:foo, 42], "towels", 0.1)
+			expect_op(:get, [:bar, "baz"], "wombat")
+			op_count = 2
+
+			client.get(:foo, 42) do |v|
+				expect(v).to eq("towels")
+				op_count -= 1
+			end
+
+			client.get(:bar, "baz") do |v|
+				expect(v).to eq("wombat")
+				op_count -= 1
+			end
+
+			EM.add_periodic_timer(0.0001) do
+				EM.stop if op_count == 0
+			end
+		end
+	end
+end

data/spec/search_spec.rb

@@ -0,0 +1,48 @@
+require_relative './spec_helper'
+
+describe "#search" do
+	let(:client) { EM::HyperDex::Client.new }
+
+	it "works when standalone" do
+		expect(mock_client).
+		  to receive(:search).
+		  with(:foo, 42).
+		  and_return(mock_iter = double(HyperDex::Client::Iterator))
+
+		resultset = %w{alpha beta gamma delta}
+
+		expect(mock_iter).
+		  to receive(:next).
+		  with(no_args).
+		  and_return(*(resultset + [nil]))
+
+		client.search(:foo, 42).each do |v|
+			expect(v).to eq(resultset.shift)
+		end.errback do
+			# Derpy way of saying "this should not happen"
+			expect(false).to be(true)
+		end
+
+		expect(resultset).to be_empty
+	end
+
+	it "works inside EM" do
+		resultset = %w{alpha beta gamma delta}
+		in_em do
+			expect_iter(:search, [:foo, 42], resultset)
+
+			df = client.search(:foo, 42).each do |v|
+				expect(v).to eq(resultset.shift)
+			end.callback do
+				EM.stop
+			end.errback do
+				# This should not happen
+				expect(false).to be(true)
+			end
+
+			expect(df).to be_a(EM::HyperDex::Client::EnumerableDeferrable)
+		end
+
+		expect(resultset).to be_empty
+	end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,98 @@
+require 'spork'
+
+Spork.prefork do
+	require 'bundler'
+	Bundler.setup(:default, :test)
+	require 'rspec/core'
+	require 'rspec/mocks'
+
+	require 'pry'
+
+	module EventMachineTestHelper
+		def in_em(timeout = 1)
+			Timeout::timeout(timeout) do
+				::EM.run do
+					yield
+				end
+			end
+		rescue Timeout::Error
+			EM.stop
+			raise RuntimeError,
+			      "EM didn't finish before the timeout"
+		end
+
+		def expect_op(op, args, rv, response_delay = 0.0001)
+			expect(mock_client).
+			  to receive("async_#{op}".to_sym).
+			  with(*args).
+			  and_return(mock_op = double(HyperDex::Client::Deferred))
+
+			expect(mock_op).
+			  to receive(:wait).
+			  with(no_args).
+			  and_return(rv)
+
+			::EM.add_timer(response_delay) do
+				expect(mock_client).
+				  to receive(:loop).
+				  with(0).
+				  and_return(mock_op)
+
+				client.__send__(:handle_response)
+			end
+		end
+
+		def expect_iter(op, args, results, response_delay = 0.0001)
+			expect(mock_client).
+			  to receive(op).
+			  with(*args).
+			  and_return(mock_iter = double(HyperDex::Client::Iterator))
+
+			expect(mock_iter).
+			  to receive(:next).
+			  with(no_args).
+			  and_return(*(results + [nil]))
+
+			(results.length + 1).times do |i|
+				::EM.add_timer(response_delay * (i+1)) do
+					expect(mock_client).
+					  to receive(:loop).
+					  with(0).
+					  and_return(mock_iter)
+
+					client.__send__(:handle_response)
+				end
+			end
+		end
+
+		def mock_client(host = 'localhost', port = 1982)
+			@mock_client ||= begin
+				expect(HyperDex::Client::Client).
+				  to receive(:new).
+				  with(host, port).
+				  and_return(mock = double(HyperDex::Client::Client))
+
+				allow(mock).
+				  to receive(:poll_fd).
+				  with(no_args).
+				  and_return(0)
+				mock
+			end
+		end
+	end
+
+	RSpec.configure do |config|
+		config.fail_fast = true
+#		config.full_backtrace = true
+
+		config.include EventMachineTestHelper
+
+		config.expect_with :rspec do |c|
+			c.syntax = :expect
+		end
+	end
+end
+
+Spork.each_run do
+	require 'em-hyperdex-client'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: em-hyperdex-client
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-21 00:00:00.000000000 Z
+date: 2014-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: eventmachine
@@ -50,7 +50,10 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.4.4.3
+        version: 1.4.5.pre
+    - - <
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -58,7 +61,10 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.4.4.3
+        version: 1.4.5.pre
+    - - <
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -219,6 +225,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.7'
 description: 
 email: 
 executables: []
@@ -227,6 +249,7 @@ extra_rdoc_files:
 - README.md
 files:
 - .gitignore
+- .yardopts
 - Gemfile
 - Guardfile
 - LICENCE
@@ -234,6 +257,9 @@ files:
 - Rakefile
 - em-hyperdex-client.gemspec
 - lib/em-hyperdex-client.rb
+- spec/get_spec.rb
+- spec/search_spec.rb
+- spec/spec_helper.rb
 homepage: http://github.com/mpalmer/em-hyperdex-client
 licenses: []
 post_install_message: 
@@ -248,7 +274,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1903398093042256464
+      hash: -1612000962635766686
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -257,7 +283,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1903398093042256464
+      hash: -1612000962635766686
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -265,3 +291,4 @@ signing_key:
 specification_version: 3
 summary: EventMachine bindings for HyperDex
 test_files: []
+has_rdoc: