Module: EventMachine::Deferrable

### Home Classes Methods

### In Files

- lib/em/deferrable.rb
- lib/em/future.rb

### Methods

- ::future
- #callback
- #cancel_callback
- #cancel_errback
- #cancel_timeout
- #errback
- #fail
- #set_deferred_failure
- #set_deferred_status
- #set_deferred_success
- #succeed
- #timeout

### Files

- ChangeLog
- DEFERRABLES
- EPOLL
- INSTALL
- KEYBOARD
- LEGAL
- LIGHTWEIGHT_CONCURRENCY
- PURE_RUBY
- RELEASE_NOTES
- SMTP
- SPAWNED_PROCESSES
- TODO

### Class/Module Index

Quicksearch

- EventMachine
- EventMachine
- EventMachine::Channel
- EventMachine::Completion
- EventMachine::Connection
- EventMachine::DNS
- EventMachine::DNS::Request
- EventMachine::DNS::RequestIdAlreadyUsed
- EventMachine::DNS::Resolver
- EventMachine::DNS::Socket
- EventMachine::DatagramObject
- EventMachine::DefaultDeferrable
- EventMachine::Deferrable
- EventMachine::DeferrableChildProcess
- EventMachine::Error
- EventMachine::EvmaKeyboard
- EventMachine::EvmaTCPClient
- EventMachine::EvmaTCPServer
- EventMachine::EvmaUDPSocket
- EventMachine::EvmaUNIXClient
- EventMachine::EvmaUNIXServer
- EventMachine::FileNotFoundException
- EventMachine::FileStreamer
- EventMachine::FileWatch
- EventMachine::Iterator
- EventMachine::LoopbreakReader
- EventMachine::PeriodicTimer
- EventMachine::Pool
- EventMachine::ProcessWatch
- EventMachine::Protocols
- EventMachine::Protocols
- EventMachine::Protocols::HeaderAndContentProtocol
- EventMachine::Protocols::HttpClient
- EventMachine::Protocols::HttpClient2
- EventMachine::Protocols::HttpClient2::Request
- EventMachine::Protocols::LineAndTextProtocol
- EventMachine::Protocols::LineProtocol
- EventMachine::Protocols::LineText2
- EventMachine::Protocols::Memcache
- EventMachine::Protocols::Memcache::ParserError
- EventMachine::Protocols::ObjectProtocol
- EventMachine::Protocols::Postgres3
- EventMachine::Protocols::SASLauth
- EventMachine::Protocols::SASLauthclient
- EventMachine::Protocols::SmtpClient
- EventMachine::Protocols::SmtpServer
- EventMachine::Protocols::Socks4
- EventMachine::Protocols::Stomp
- EventMachine::Protocols::Stomp::Message
- EventMachine::Protocols::TcpConnectTester
- EventMachine::Queue
- EventMachine::Reactor
- EventMachine::Selectable
- EventMachine::SpawnedProcess
- EventMachine::StreamObject
- EventMachine::SystemCmd
- EventMachine::ThreadedResource
- EventMachine::TickLoop
- EventMachine::Timer
- EventMachine::UuidGenerator
- EventMachine::YieldBlockFromSpawnedProcess
- Object
- Object::EM
- Object::P
- BufferedTokenizer
- IO
- StringIO
- TestConnection

No matching classes.

# 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
    def self.future arg, cb=nil, eb=nil, &blk
      arg = arg.call if arg.respond_to?(:call)

      if arg.respond_to?(:set_deferred_status)
        if cb || eb
          arg.callback(&cb) if cb
          arg.errback(&eb) if eb
        else
          arg.callback(&blk) if blk
        end
      end

      arg
    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 set_deferred_status 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 set_deferred_status call.

    # File lib/em/deferrable.rb, line 44
    def callback &block
      return unless block
      @deferred_status ||= :unknown
      if @deferred_status == :succeeded
        block.call(*@deferred_args)
      elsif @deferred_status != :failed
        @callbacks ||= []
        @callbacks.unshift block # << block
      end
      self
    end

cancel_callback(block) click to toggle source

Cancels an outstanding callback to &block if any. Undoes the action of callback.

    # File lib/em/deferrable.rb, line 58
    def cancel_callback block
      @callbacks ||= []
      @callbacks.delete block
    end

cancel_errback(block) click to toggle source

Cancels an outstanding errback to &block if any. Undoes the action of errback.

    # File lib/em/deferrable.rb, line 84
    def cancel_errback block
      @errbacks ||= []
      @errbacks.delete block
    end

cancel_timeout() click to toggle source

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

    # File lib/em/deferrable.rb, line 179
    def cancel_timeout
      @deferred_timeout ||= nil
      if @deferred_timeout
        @deferred_timeout.cancel
        @deferred_timeout = nil
      end
    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 set_deferred_status for more information.

    # File lib/em/deferrable.rb, line 70
    def errback &block
      return unless block
      @deferred_status ||= :unknown
      if @deferred_status == :failed
        block.call(*@deferred_args)
      elsif @deferred_status != :succeeded
        @errbacks ||= []
        @errbacks.unshift block # << block
      end
      self
    end

fail(*args) click to toggle source

Sugar for set_deferred_status(:failed, ...)

    # File lib/em/deferrable.rb, line 197
    def fail *args
      set_deferred_status :failed, *args
    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 callback method (if any) will be executed BEFORE the set_deferred_status method returns. All of the blocks passed to the object using errback will be discarded.

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

If you pass any arguments to set_deferred_status 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 set_deferred_status, otherwise Ruby will raise an ArgumentError.

    # File lib/em/deferrable.rb, line 141
    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

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 190
    def succeed *args
      set_deferred_status :succeeded, *args
    end

Also aliased as: set_deferred_success
timeout(seconds, *args) 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 170
    def timeout seconds, *args
      cancel_timeout
      me = self
      @deferred_timeout = EventMachine::Timer.new(seconds) {me.fail(*args)}
      self
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.