em-promise 1.0.3 → 1.1.0

data/README.textile

@@ -8,11 +8,10 @@ From the perspective of dealing with error handling, deferred and promise apis a
 
 <pre><code class="ruby">
 require 'rubygems'
-require 'eventmachine'
 require 'em-promise'
 
 def asyncGreet(name)
-	deferred = EM::Defer.new
+	deferred = EM::Q.defer
 	
 	EM::Timer.new(5) do
 		EM.defer do
@@ -26,13 +25,16 @@ end
 
 EventMachine.run do
 
-	promise = asyncGreet('Robin Hood')
-	promise.then(proc { |greeting|
+	asyncGreet('Robin Hood').then(proc { |greeting|
 		p "Success: #{greeting}"
 	}, proc { |reason|
 		p "Failed: #{reason}"
 	})
 	
+	asyncGreet('The Dude').then do |greeting|
+		p "Jeff '#{greeting}' Lebowski"
+	end
+	
 end
 
 </code></pre>
@@ -40,4 +42,5 @@ end
 
 h2. Start using it now
 
-@gem install em-promise@
+# Read the "Documentation":http://rubydoc.info/gems/em-promise/EventMachine/Q
+# Then @gem install em-promise@

data/lib/em-promise.rb

@@ -1,3 +1,3 @@
 require 'eventmachine'
 
-require 'em-promise/defer.rb'
+require 'em-promise/q.rb'

data/lib/em-promise/{defer.rb → q.rb}

@@ -1,28 +1,46 @@
 
 
 module EventMachine
-	#
-	# Creates a 'Deferred' object which represents a task which will finish in the future.
-	#
-	class Defer
+	
+	
+	class Q
+		private_class_method :new
+		
 		
+		# @abstract
 		class Promise
+			private_class_method :new
 		end
 		
+		
+		#
+		# A new promise instance is created when a deferred instance is created and can be
+		# retrieved by calling deferred.promise
+		#
 		class DeferredPromise < Promise
+			public_class_method :new
+			
 			def initialize(defer)
+				raise ArgumentError unless defer.is_a?(Deferred)
+				super()
+				
 				@defer = defer
 			end
 			
-			
+			#
+			# regardless of when the promise was or will be resolved / rejected, calls one of
+			# the success or error callbacks asynchronously as soon as the result is available.
+			# The callbacks are called with a single argument, the result or rejection reason.
+			#
+			# @param [Proc, Proc, &blk] callbacks success, error, success_block
 			def then(callback = nil, errback = nil, &blk)
-				result = Defer.new
+				result = Q.defer
 				
 				callback ||= blk
 				
-				wrappedCallback = proc { |value|
+				wrappedCallback = proc { |val|
 					begin
-						result.resolve(callback.nil? ? value : callback.call(value))
+						result.resolve(callback.nil? ? val : callback.call(val))
 					rescue => e
 						warn "\nUnhandled exception: #{e.message}\n#{e.backtrace.join("\n")}\n"
 						result.reject(e);
@@ -31,7 +49,7 @@ module EventMachine
 				
 				wrappedErrback = proc { |reason|
 					begin
-						result.resolve(errback.nil? ? Defer.reject(reason) : errback.call(reason))
+						result.resolve(errback.nil? ? Q.reject(reason) : errback.call(reason))
 					rescue => e
 						warn "Unhandled exception: #{e.message}\n#{e.backtrace.join("\n")}\n"
 						result.reject(e);
@@ -39,8 +57,8 @@ module EventMachine
 				}
 				
 				#
-				# Schedule as we are touching arrays
-				# => Everything else is locally scoped
+				# Schedule as we are touching shared state
+				#	Everything else is locally scoped
 				#
 				EM.schedule do
 					pending_array = pending
@@ -56,7 +74,7 @@ module EventMachine
 			end
 			
 			
-			protected
+			private
 			
 			
 			def pending
@@ -69,21 +87,26 @@ module EventMachine
 		end
 		
 		
+		
 		class ResolvedPromise < Promise
+			public_class_method :new
+			
 			def initialize(response, error = false)
 				raise ArgumentError if error && response.is_a?(Promise)
+				super()
+				
 				@error = error
 				@response = response
 			end
 			
 			def then(callback = nil, errback = nil, &blk)
-				result = Defer.new
+				result = Q.defer
 				
 				callback ||= blk
 				
 				EM.next_tick {
 					if @error
-						result.resolve(errback.nil? ? Defer.reject(@response) : errback.call(@response))
+						result.resolve(errback.nil? ? Q.reject(@response) : errback.call(@response))
 					else
 						result.resolve(callback.nil? ? @response : callback.call(@response))
 					end
@@ -94,36 +117,13 @@ module EventMachine
 		end
 		
 		
-		def initialize
-			@pending = []
-			@value = nil
-		end
-		
-		
-		def resolve(val = nil)
-			EM.schedule do
-				if !!@pending
-					callbacks = @pending
-					@pending = nil
-					@value = ref(val)
-					
-					if callbacks.length > 0
-						callbacks.each do |callback|
-							@value.then(callback[0], callback[1])
-						end
-					end
-				end
-			end
-		end
-		
-		
-		def reject(reason = nil)
-			resolve(Defer.reject(reason))
-		end
-		
 		
-		def promise
-			DeferredPromise.new( self )
+		#
+		# Creates a Deferred object which represents a task which will finish in the future.
+		#
+		# @return [Deferred] Returns a new instance of Deferred
+		def self.defer
+			return Deferred.new
 		end
 		
 		
@@ -143,7 +143,7 @@ module EventMachine
 		#   #!/usr/bin/env ruby
 		#
 		#   require 'rubygems' # or use Bundler.setup
-		#   require 'eventmachine'
+		#   require 'em-promise'
 		#
 		#   promiseB = promiseA.then(lambda {|result|
 		#     # success: do something and resolve promiseB with the old or a new result
@@ -155,10 +155,11 @@ module EventMachine
 		#       # handle the error and recover
 		#       return newPromiseOrValue
 		#     end
-		#     return Defer.reject(reason)
+		#     return Q.reject(reason)
 		#   })
 		#
 		# @param [Object] reason constant, message, exception or an object representing the rejection reason.
+		# @return [Promise] Returns a promise that was already resolved as rejected with the reason
 		def self.reject(reason = nil)
 			return ResolvedPromise.new( reason, true )	# A resolved failed promise
 		end
@@ -168,12 +169,12 @@ module EventMachine
 		# promises are resolved.
 		#
 		# @param [Promise] a number of promises that will be combined into a single promise
-		# @returns [Promise] Returns a single promise that will be resolved with an array of values,
+		# @return [Promise] Returns a single promise that will be resolved with an array of values,
 		#   each value corresponding to the promise at the same index in the `promises` array. If any of
 		#   the promises is resolved with a rejection, this resulting promise will be resolved with the
 		#   same rejection.
 		def self.all(*promises)
-			deferred = Defer.new
+			deferred = Q.defer
 			counter = promises.length
 			results = []
 			
@@ -198,19 +199,79 @@ module EventMachine
 			end
 			
 			return deferred.promise
-		end
+		end		
 		
 		
-		protected
+		private
 		
 		
 		def self.ref(value)
 			return value if value.is_a?(Promise)
 			return ResolvedPromise.new( value )			# A resolved success promise
 		end
+	end
+	
+	
+	#
+	# The purpose of the deferred object is to expose the associated Promise instance as well
+	# as APIs that can be used for signalling the successful or unsuccessful completion of a task.
+	#
+	class Q::Deferred < Q
+		public_class_method :new
+		private_class_method :defer
+		private_class_method :reject
+		private_class_method :all
+		
+		def initialize
+			super()
+			
+			@pending = []
+			@value = nil
+		end
+		
+		#
+		# resolves the derived promise with the value. If the value is a rejection constructed via
+		# Q.reject, the promise will be rejected instead.
+		#
+		# @param [Object] val constant, message or an object representing the result.
+		def resolve(val = nil)
+			EM.schedule do
+				if not @pending.nil?
+					callbacks = @pending
+					@pending = nil
+					@value = ref(val)
+					
+					if callbacks.length > 0
+						callbacks.each do |callback|
+							@value.then(callback[0], callback[1])
+						end
+					end
+				end
+			end
+		end
+		
+		#
+		# rejects the derived promise with the reason. This is equivalent to resolving it with a rejection
+		# constructed via Q.reject.
+		#
+		# @param [Object] reason constant, message, exception or an object representing the rejection reason.
+		def reject(reason = nil)
+			resolve(Q.reject(reason))
+		end
+		
+		#
+		# Creates a promise object associated with this deferred
+		#
+		def promise
+			DeferredPromise.new( self )
+		end
+		
+		
+		private
+		
 		
 		def ref(value)
-			Defer.ref(value)
+			Deferred.ref(value)		# Defined in Q (DRY)
 		end
 	end
 

data/lib/em-promise/version.rb

@@ -1,5 +1,5 @@
 module EventMachine
 	class Defer
-		VERSION = "1.0.3"
+		VERSION = "1.1.0"
 	end
 end

data/spec/defer_spec.rb

@@ -4,10 +4,10 @@ require 'bundler/setup'
 require 'em-promise'
 
 
-describe EventMachine::Defer do
+describe EventMachine::Q do
 	
 	before :each do
-		@deferred = EM::Defer.new
+		@deferred = EM::Q.defer
 		@promise = @deferred.promise
 		@log = []
 		@default_fail = proc { |reason|
@@ -86,7 +86,7 @@ describe EventMachine::Defer do
 		
 		
 		it "should allow deferred resolution with a new promise" do
-			deferred2 = EM::Defer.new
+			deferred2 = EM::Q.defer
 			EventMachine.run {
 				@promise.then(proc {|result|
 					result.should == :foo
@@ -190,7 +190,7 @@ describe EventMachine::Defer do
 		
 		
 		it "should not defer rejection with a new promise" do
-			deferred2 = EM::Defer.new
+			deferred2 = EM::Q.defer
 			EventMachine.run {
 				@promise.then(@default_fail, @default_fail)
 				begin
@@ -205,7 +205,7 @@ describe EventMachine::Defer do
 	end
 	
 	
-	describe EventMachine::Defer::Promise do
+	describe EventMachine::Q::Promise do
 		
 		describe 'then' do
 			
@@ -314,7 +314,7 @@ describe EventMachine::Defer do
 					})
 					@promise.then(@default_fail, proc {|result|
 						@log << result
-						EM::Defer.reject('some reason')
+						EM::Q.reject('some reason')
 					})
 					@promise.then(@default_fail, proc {|result|
 						@log << result
@@ -393,7 +393,7 @@ describe EventMachine::Defer do
 		
 		it "should package a string into a rejected promise" do
 			EventMachine.run {
-				rejectedPromise = EM::Defer.reject('not gonna happen')
+				rejectedPromise = EM::Q.reject('not gonna happen')
 				
 				@promise.then(nil, proc {|reason|
 					@log << reason
@@ -411,7 +411,7 @@ describe EventMachine::Defer do
 		
 		it "should return a promise that forwards callbacks if the callbacks are missing" do
 			EventMachine.run {
-				rejectedPromise = EM::Defer.reject('not gonna happen')
+				rejectedPromise = EM::Q.reject('not gonna happen')
 				
 				@promise.then(nil, proc {|reason|
 					@log << reason
@@ -436,7 +436,7 @@ describe EventMachine::Defer do
 		
 		it "should resolve all of nothing" do
 			EventMachine.run {
-				EM::Defer.all().then(proc {|result|
+				EM::Q.all.then(proc {|result|
 					@log << result
 				}, @default_fail)
 				
@@ -449,10 +449,10 @@ describe EventMachine::Defer do
 		
 		it "should take an array of promises and return a promise for an array of results" do
 			EventMachine.run {
-				deferred1 = EM::Defer.new
-				deferred2 = EM::Defer.new
+				deferred1 = EM::Q.defer
+				deferred2 = EM::Q.defer
 				
-				EM::Defer.all(@promise, deferred1.promise, deferred2.promise).then(proc {|result|
+				EM::Q.all(@promise, deferred1.promise, deferred2.promise).then(proc {|result|
 					result.should == [:foo, :bar, :baz]
 					EM.stop
 				}, @default_fail)
@@ -466,10 +466,10 @@ describe EventMachine::Defer do
 		
 		it "should reject the derived promise if at least one of the promises in the array is rejected" do
 			EventMachine.run {
-				deferred1 = EM::Defer.new
-				deferred2 = EM::Defer.new
+				deferred1 = EM::Q.defer
+				deferred2 = EM::Q.defer
 				
-				EM::Defer.all(@promise, deferred1.promise, deferred2.promise).then(@default_fail, proc {|reason|
+				EM::Q.all(@promise, deferred1.promise, deferred2.promise).then(@default_fail, proc {|reason|
 					reason.should == :baz
 					EM.stop
 				})

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: em-promise
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-12 00:00:00.000000000 Z
+date: 2012-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: eventmachine
@@ -50,7 +50,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/em-promise/defer.rb
+- lib/em-promise/q.rb
 - lib/em-promise/version.rb
 - lib/em-promise.rb
 - MIT-LICENSE