Module: Libuv::Q

Included in:
Deferred
Defined in:
lib/libuv/q.rb

Defined Under Namespace

Classes: Deferred, DeferredPromise, Promise, ResolvedPromise

Class Method Summary collapse

Class Method Details

.all(loop, *promises) ⇒ Promise

Combines multiple promises into a single promise that is resolved when all of the input promises are resolved.

Parameters:

  • Promises (*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, 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.



325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
 
# File 'lib/libuv/q.rb', line 325

def all(loop, *promises)
	deferred = Q.defer(loop)
	counter = promises.length
	results = []
	
	if counter > 0
		promises.each_index do |index|
			ref(loop, promises[index]).then(proc {|result|
				if results[index].nil?
					results[index] = result
					counter -= 1
					deferred.resolve(results) if counter <= 0
				end
				result
			}, proc {|reason|
				if results[index].nil?
					deferred.reject(reason)
				end
				Q.reject(@loop, reason)	# Don't modify result
			})
		end
	else
		deferred.resolve(results)
	end
	
	return deferred.promise
end

.any(loop, *promises) ⇒ Promise

Combines multiple promises into a single promise that is resolved when any of the input promises are resolved.

Parameters:

  • Promises (*Promise) —

    a number of promises that will be combined into a single promise

Returns:

  • (Promise) —

    Returns a single promise



360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
 
# File 'lib/libuv/q.rb', line 360

def any(loop, *promises)
	deferred = Q.defer(loop)
	if promises.length > 0
		promises.each_index do |index|
			ref(loop, promises[index]).then(proc {|result|
				deferred.resolve(true)
				result
			}, proc {|reason|
				deferred.reject(false)
				Q.reject(@loop, reason)	# Don't modify result
			})
		end
	else
		deferred.resolve(true)
	end
end

.defer(loop) ⇒ Deferred

Creates a Deferred object which represents a task which will finish in the future.

Returns:

  • (Deferred) —

    Returns a new instance of Deferred



274
275
276
 
# File 'lib/libuv/q.rb', line 274

def defer(loop)
	return Deferred.new(loop)
end

.finally(loop, *promises) ⇒ Promise

Combines multiple promises into a single promise that is resolved when all of the input promises are resolved or rejected.

Parameters:

  • Promises (*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, each [result, wasResolved] value pair corresponding to a at the same index in the promises array.



385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
 
# File 'lib/libuv/q.rb', line 385

def self.finally(loop, *promises)
	deferred = Q.defer(loop)
	counter = promises.length
	results = []
	
	if counter > 0
		promises.each_index do |index|
			ref(loop, promises[index]).then(proc {|result|
				if results[index].nil?
					results[index] = [result, false]
					counter -= 1
					deferred.resolve(results) if counter <= 0
				end
				result
			}, proc {|reason|
				if results[index].nil?
					results[index] = [reason, false]
					counter -= 1
					deferred.resolve(results) if counter <= 0
				end
				Q.reject(@loop, reason)	# Don't modify result
			})
		end
	else
		deferred.resolve(results)
	end
	
	return deferred.promise
end

.reject(loop, reason = nil) ⇒ Promise

Creates a promise that is resolved as rejected with the specified reason. This api should be used to forward rejection in a chain of promises. If you are dealing with the last promise in a promise chain, you don't need to worry about it.

When comparing deferreds/promises to the familiar behaviour of try/catch/throw, think of reject as the raise keyword in Ruby. This also means that if you "catch" an error via a promise error callback and you want to forward the error to the promise derived from the current promise, you have to "rethrow" the error by returning a rejection constructed via reject.

Examples:

handling rejections

#!/usr/bin/env ruby

require 'rubygems' # or use Bundler.setup
require 'em-promise'

promiseB = promiseA.then(lambda {|reason|
  # error: handle the error if possible and resolve promiseB with newPromiseOrValue,
  #        otherwise forward the rejection to promiseB
  if canHandle(reason)
    # handle the error and recover
    return newPromiseOrValue
  end
  return Q.reject(loop, reason)
}, lambda {|result|
  # success: do something and resolve promiseB with the old or a new result
  return result
})

Parameters:

  • reason (Object) (defaults to: nil) —

    constant, message, exception or an object representing the rejection reason.

Returns:

  • (Promise) —

    Returns a promise that was already resolved as rejected with the reason



312
313
314
 
# File 'lib/libuv/q.rb', line 312

def reject(loop, reason = nil)
	return ResolvedPromise.new(loop, reason, true)	# A resolved failed promise
end