module EventMachine::Deferrable

comments under the new method #timeout.
if a Deferrable was timed out and then an attempt was made to succeed it. See the
within a callback or errback, but more seriously it would cause spurious errors
behavior would invalidate the idiom of resetting arguments by setting status from
to raise an exception is status is set more than once on a Deferrable. The latter
triggering its errbacks! That is clearly undesirable, but it's just as undesirable
to "succeed" a Deferrable (triggering its callbacks), and then immediately "fail" it,
which only allows status to be set once. Prior to making this change, it was possible
handlers. This gets us a little closer to the behavior of Twisted's "deferred,"
Changed 15Sep07: after processing callbacks or errbacks, CLEAR the other set of

versions.
by Kirk Haines, to work around the memory leak bug that still exists in many Ruby
Changed @callbacks and @errbacks from push/shift to unshift/pop, per suggestion

that will be sent to subsequent callbacks down the chain.
means that a callback can call #set_deferred_status and change the parameters
once. It also has the magic effect of permitting recursive calls, which
This is valid because by definition callbacks are executed no more than
We're shifting callbacks off and discarding them as we execute them.
--

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

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

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

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

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

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

def set_deferred_status status, *args
  cancel_timeout
  @errbacks ||= nil
  @callbacks ||= nil
  @deferred_status = status
  @deferred_args = args
  case @deferred_status
  when :succeeded
    if @callbacks
      while cb = @callbacks.pop
        cb.call(*@deferred_args)
      end
    end
    @errbacks.clear if @errbacks
  when :failed
    if @errbacks
      while eb = @errbacks.pop
        eb.call(*@deferred_args)
      end
    end
    @callbacks.clear if @callbacks
  end
end