Class: Concurrent::Promise

Inherits:
Object
  • Object
show all
Includes:
Obligation, UsesGlobalThreadPool
Defined in:
lib/concurrent/promise.rb

Defined Under Namespace

Classes: Rescuer

Instance Attribute Summary

Attributes included from Obligation

#reason, #state

Instance Method Summary collapse

Methods included from UsesGlobalThreadPool

included

Methods included from Obligation

#fulfilled?, #pending?, #rejected?, #value

Methods included from Dereferenceable

#set_deref_options, #value

Constructor Details

#initialize(*args, &block) ⇒ Promise

Creates a new promise object. “A promise represents the eventual value returned from the single completion of an operation.” Promises can be chained in a tree structure where each promise has zero or more children. Promises are resolved asynchronously in the order they are added to the tree. Parents are guaranteed to be resolved before their children. The result of each promise is passed to each of its children upon resolution. When a promise is rejected all its children will be summarily rejected. A promise that is neither resolved or rejected is pending.

Parameters:

  • args (Array) —

    zero or more arguments for the block

  • block (Proc) —

    the block to call when attempting fulfillment

See Also:



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/concurrent/promise.rb', line 27

def initialize(*args, &block)
  if args.first.is_a?(Promise)
    @parent = args.first
  else
    @parent = nil
    @chain = [self]
  end

  @lock = Mutex.new
  @handler = block || Proc.new{|result| result }
  @state = :pending
  @value = nil
  @reason = nil
  @rescued = false
  @children = []
  @rescuers = []

  realize(*args) if root?
end

Instance Method Details

#rescue(clazz = nil, &block) ⇒ self Also known as: catch, on_error

Add a rescue handler to be run if the promise is rejected (via raised exception). Multiple rescue handlers may be added to a Promise. Rescue blocks will be checked in order and the first one with a matching Exception class will be processed. The block argument will be the exception that caused the rejection.

Parameters:

  • clazz (Class) (defaults to: nil) —

    The class of exception to rescue

  • block (Proc) —

    the block to call if the rescue is matched

Returns:

  • (self) —

    so that additional chaining can occur



79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/concurrent/promise.rb', line 79

def rescue(clazz = nil, &block)
  return self if fulfilled? || rescued? || block.nil?
  @lock.synchronize do
    rescuer = Rescuer.new(clazz, block)
    if pending?
      @rescuers << rescuer
    else
      try_rescue(reason, rescuer)
    end
  end
  return self
end

#rescued? ⇒ Boolean

Returns:

  • (Boolean) 


47
48
49
 
# File 'lib/concurrent/promise.rb', line 47

def rescued?
  return @rescued
end

#then(&block) ⇒ Promise

Create a new child Promise. The block argument for the child will be the result of fulfilling its parent. If the child will immediately be rejected if the parent has already been rejected.

Parameters:

  • block (Proc) —

    the block to call when attempting fulfillment

Returns:



58
59
60
61
62
63
64
65
66
67
 
# File 'lib/concurrent/promise.rb', line 58

def then(&block)
  child = @lock.synchronize do
    block = Proc.new{|result| result } if block.nil?
    @children << Promise.new(self, &block)
    @children.last.on_reject(@reason) if rejected?
    push(@children.last)
    @children.last
  end
  return child
end