EventMachine::Deferrable

Public Class Methods

future(arg, cb=nil, eb=nil, &blk) click to toggle source

A future is a sugaring of a typical deferrable usage.

    # File lib/em/future.rb, line 44
44:       def self.future arg, cb=nil, eb=nil, &blk
45:         arg = arg.call if arg.respond_to?(:call)
46: 
47:         if arg.respond_to?(:set_deferred_status)
48:           if cb || eb
49:             arg.callback(&cb) if cb
50:             arg.errback(&eb) if eb
51:           else
52:             arg.callback(&blk) if blk
53:           end
54:         end
55: 
56:         arg
57:       end

Public Instance Methods

callback(&block) click to toggle source

Specify a block to be executed if and when the Deferrable object receives a status of :succeeded. See # for more information.

Calling this method on a Deferrable object whose status is not yet known will cause the callback block to be stored on an internal list. If you call this method on a Deferrable whose status is :succeeded, the block will be executed immediately, receiving the parameters given to the prior # call.

    # File lib/em/deferrable.rb, line 43
43:     def callback &block
44:       return unless block
45:       @deferred_status ||= :unknown
46:       if @deferred_status == :succeeded
47:         block.call(*@deferred_args)
48:       elsif @deferred_status != :failed
49:         @callbacks ||= []
50:         @callbacks.unshift block # << block
51:       end
52:     end
cancel_timeout() click to toggle source

Cancels an outstanding timeout if any. Undoes the action of #.

     # File lib/em/deferrable.rb, line 161
161:     def cancel_timeout
162:       @deferred_timeout ||= nil
163:       if @deferred_timeout
164:         @deferred_timeout.cancel
165:         @deferred_timeout = nil
166:       end
167:     end
errback(&block) click to toggle source

Specify a block to be executed if and when the Deferrable object receives a status of :failed. See # for more information.

    # File lib/em/deferrable.rb, line 61
61:     def errback &block
62:       return unless block
63:       @deferred_status ||= :unknown
64:       if @deferred_status == :failed
65:         block.call(*@deferred_args)
66:       elsif @deferred_status != :succeeded
67:         @errbacks ||= []
68:         @errbacks.unshift block # << block
69:       end
70:     end
fail(*args) click to toggle source

Sugar for set_deferred_status(:failed, …)

     # File lib/em/deferrable.rb, line 179
179:     def fail *args
180:       set_deferred_status :failed, *args
181:     end
Also aliased as: set_deferred_failure
set_deferred_failure(*args) click to toggle source
Alias for: fail
set_deferred_status(status, *args) click to toggle source

Sets the “disposition” (status) of the Deferrable object. See also the large set of sugarings for this method. Note that if you call this method without arguments, no arguments will be passed to the callback/errback. If the user has coded these with arguments, then the user code will throw an argument exception. Implementors of deferrable classes must document the arguments they will supply to user callbacks.

OBSERVE SOMETHING VERY SPECIAL here: you may call this method even on the INSIDE of a callback. This is very useful when a previously-registered callback wants to change the parameters that will be passed to subsequently-registered ones.

You may give either :succeeded or :failed as the status argument.

If you pass :succeeded, then all of the blocks passed to the object using the # method (if any) will be executed BEFORE the # method returns. All of the blocks passed to the object using # will be discarded.

If you pass :failed, then all of the blocks passed to the object using the # method (if any) will be executed BEFORE the # method returns. All of the blocks passed to the object using # callback will be discarded.

If you pass any arguments to # in addition to the status argument, they will be passed as arguments to any callbacks or errbacks that are executed. It’s your responsibility to ensure that the argument lists specified in your callbacks and errbacks match the arguments given in calls to #, otherwise Ruby will raise an ArgumentError.

     # File lib/em/deferrable.rb, line 124
124:     def set_deferred_status status, *args
125:       cancel_timeout
126:       @errbacks ||= nil
127:       @callbacks ||= nil
128:       @deferred_status = status
129:       @deferred_args = args
130:       case @deferred_status
131:       when :succeeded
132:         if @callbacks
133:           while cb = @callbacks.pop
134:             cb.call(*@deferred_args)
135:           end
136:         end
137:         @errbacks.clear if @errbacks
138:       when :failed
139:         if @errbacks
140:           while eb = @errbacks.pop
141:             eb.call(*@deferred_args)
142:           end
143:         end
144:         @callbacks.clear if @callbacks
145:       end
146:     end
set_deferred_success(*args) click to toggle source
Alias for: succeed
succeed(*args) click to toggle source

Sugar for set_deferred_status(:succeeded, …)

     # File lib/em/deferrable.rb, line 172
172:     def succeed *args
173:       set_deferred_status :succeeded, *args
174:     end
Also aliased as: set_deferred_success
timeout(seconds) click to toggle source

Setting a timeout on a Deferrable causes it to go into the failed state after the Timeout expires (passing no arguments to the object’s errbacks). Setting the status at any time prior to a call to the expiration of the timeout will cause the timer to be cancelled.

     # File lib/em/deferrable.rb, line 153
153:     def timeout seconds
154:       cancel_timeout
155:       me = self
156:       @deferred_timeout = EventMachine::Timer.new(seconds) {me.fail}
157:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.