amqp 0.7.5 → 0.8.0.beta1

data/lib/amqp/deprecated/fork.rb

@@ -0,0 +1,15 @@
+require "amqp/ext/em"
+
+module AMQP
+  # @deprecated
+  # @api public
+  def self.fork(workers)
+    EM.fork(workers) do
+      # clean up globals in the fork
+      Thread.current[:mq] = nil
+      AMQP.instance_variable_set('@conn', nil)
+
+      yield
+    end
+  end  
+end

data/lib/amqp/deprecated/logger.rb

@@ -0,0 +1,99 @@
+# encoding: utf-8
+
+module AMQP
+  class Logger
+    def initialize(*args, &block)
+      opts = args.pop if args.last.is_a? Hash
+      opts ||= {}
+
+      printer(block) if block
+
+      @prop = opts
+      @tags = ([:timestamp] + args).uniq
+    end
+
+    attr_reader :prop
+    alias :base :prop
+
+    def log(severity, *args)
+      opts = args.pop if args.last.is_a? Hash and args.size != 1
+      opts ||= {}
+      opts = @prop.clone.update(opts)
+
+      data = args.shift
+
+      data = {:type => :exception,
+              :name => data.class.to_s.intern,
+              :backtrace => data.backtrace,
+              :message => data.message} if data.is_a? Exception
+
+      (@tags + args).each do |tag|
+        tag = tag.to_sym
+        case tag
+        when :timestamp
+          opts.update :timestamp => Time.now
+        when :hostname
+          @hostname ||= { :hostname => `hostname`.strip }
+          opts.update @hostname
+        when :process
+          @process_id ||= { :process_id => Process.pid,
+                            :process_name => $0,
+                            :process_parent_id => Process.ppid,
+                            :thread_id => Thread.current.object_id }
+          opts.update :process => @process_id
+        else
+          (opts[:tags] ||= []) << tag
+        end
+      end
+
+      opts.update(:severity => severity,
+                  :msg => data)
+
+      print(opts)
+      unless Logger.disabled?
+        AMQP::Channel.new.fanout('logging', :durable => true).publish Marshal.dump(opts)
+      end
+
+      opts
+    end
+    alias :method_missing :log
+
+    def print(data = nil, &block)
+      if block
+        @printer = block
+      elsif data.is_a? Proc
+        @printer = data
+      elsif data
+        (pr = @printer || self.class.printer) and pr.call(data)
+      else
+        @printer
+      end
+    end
+    alias :printer :print
+
+    def self.printer &block
+      @printer = block if block
+      @printer
+    end
+
+    def self.disabled?
+      !!@disabled
+    end
+
+    def self.enable
+      @disabled = false
+    end
+
+    def self.disable
+      @disabled = true
+    end
+  end
+end
+
+
+require "amqp/deprecated/mq"
+class MQ
+  # @note This class will be removed before 1.0 release.
+  # @deprecated  
+  class Logger < ::AMQP::Logger; end
+end

data/lib/amqp/deprecated/mq.rb

@@ -0,0 +1,20 @@
+# Alias for AMQP::Channel.
+#
+# @note This class will be removed before 1.0 release.
+# @deprecated
+class MQ < AMQP::Channel; end
+
+
+class MQ
+  # Alias for AMQP::Exchange.
+  #
+  # @note This class will be removed before 1.0 release.
+  # @deprecated
+  class Exchange < ::AMQP::Exchange; end
+
+  # Alias for AMQP::Queue.
+  #
+  # @note This class will be removed before 1.0 release.
+  # @deprecated
+  class Queue < ::AMQP::Queue; end
+end

data/lib/amqp/deprecated/rpc.rb

@@ -0,0 +1,168 @@
+# encoding: utf-8
+
+module AMQP
+  if defined?(BasicObject)
+    # @private
+    class BlankSlate < BasicObject; end
+  else
+    # @private
+    class BlankSlate
+      instance_methods.each { |m| undef_method m unless m =~ /^__/ }
+    end
+  end
+
+
+  # Basic RPC (remote procedure call) facility.
+  #
+  # Needs more detail and explanation.
+  #
+  #  EM.run do
+  #    server = AMQP::Channel.new.rpc('hash table node', Hash)
+  #
+  #    client = AMQP::Channel.new.rpc('hash table node')
+  #    client[:now] = Time.now
+  #    client[:one] = 1
+  #
+  #    client.values do |res|
+  #      p 'client', :values => res
+  #    end
+  #
+  #    client.keys do |res|
+  #      p 'client', :keys => res
+  #      EM.stop_event_loop
+  #    end
+  #  end
+  #
+  #
+  # @note This class will be removed before 1.0 release.
+  # @deprecated
+  class RPC < ::AMQP::BlankSlate
+
+    #
+    # API
+    #
+
+
+    attr_reader :name
+
+    # Takes a channel, queue and optional object.
+    #
+    # The optional object may be a class name, module name or object
+    # instance. When given a class or module name, the object is instantiated
+    # during this setup. The passed queue is automatically subscribed to so
+    # it passes all messages (and their arguments) to the object.
+    #
+    # Marshalling and unmarshalling the objects is handled internally. This
+    # marshalling is subject to the same restrictions as defined in the
+    # {http://ruby-doc.org/core/classes/Marshal.html Marshal} standard
+    # library. See that documentation for further reference.
+    #
+    # When the optional object is not passed, the returned rpc reference is
+    # used to send messages and arguments to the queue. See #method_missing
+    # which does all of the heavy lifting with the proxy. Some client
+    # elsewhere must call this method *with* the optional block so that
+    # there is a valid destination. Failure to do so will just enqueue
+    # marshalled messages that are never consumed.
+    #
+    def initialize(channel, queue, obj = nil)
+      @name    = queue
+      @channel = channel
+      @channel.register_rpc(self)
+
+      if @obj = normalize(obj)
+        @delegate = Server.new(channel, queue, @obj)
+      else
+        @delegate = Client.new(channel, queue)
+      end
+    end
+
+
+    def client?
+      @obj.nil?
+    end
+
+    def server?
+      !client?
+    end
+
+
+    def method_missing(selector, *args, &block)
+      @delegate.__send__(selector, *args, &block)
+    end
+
+
+    # @private
+    class Client
+      attr_accessor :identifier
+
+      def initialize(channel, server_queue_name)
+        @channel           = channel
+        @exchange          = AMQP::Exchange.default(@channel)
+        @server_queue_name = server_queue_name
+
+        @handlers          = Hash.new
+        @queue             = channel.queue("__amqp_gem_rpc_client_#{rand(1_000_000)}", :auto_delete => true)
+
+        @queue.subscribe do |header, payload|
+          *response_args = Marshal.load(payload)
+          handler        = @handlers[header.message_id]
+
+          handler.call(*response_args)
+        end
+      end
+
+      def method_missing(selector, *args, &block)
+        @channel.once_open do
+          message_id   = "message_identifier_#{rand(1_000_000)}"
+
+          if block
+            @handlers[message_id] = block
+            @exchange.publish(Marshal.dump([selector, *args]), :routing_key => @server_queue_name, :reply_to => @queue.name, :message_id => message_id)
+          else
+            @exchange.publish(Marshal.dump([selector, *args]), :routing_key => @server_queue_name, :message_id => message_id)
+          end
+        end
+      end
+    end # Client
+
+    # @private
+    class Server
+      def initialize(channel, queue_name, impl)
+        @channel  = channel
+        @exchange = AMQP::Exchange.default(@channel)
+        @queue    = @channel.queue(queue_name)
+        @impl     = impl
+
+        @handlers     = Hash.new
+        @id           = "client_identifier_#{rand(1_000_000)}"
+
+        @queue.subscribe(:ack => true) do |header, payload|
+          selector, *args = Marshal.load(payload)
+          result = @impl.__send__(selector, *args)
+
+          respond_to(header, result) if header.to_hash[:reply_to]
+          header.ack
+        end
+      end
+
+      def respond_to(header, result)
+        @exchange.publish(Marshal.dump(result), :message_id => header.message_id, :routing_key => header.reply_to)
+      end
+    end # Server
+
+
+
+    protected
+
+    def normalize(input)
+      case input
+      when ::Class
+        input.new
+      when ::Module
+        (::Class.new do include(obj) end).new
+      else
+        input
+      end
+    end
+  end # RPC
+end # AMQP

data/lib/amqp/exchange.rb

@@ -1,13 +1,43 @@
 # encoding: utf-8
 
+require "amq/client/exchange"
+
 module AMQP
-  # An Exchange acts as an ingress point for all published messages. An
+
+  # h2. What are AMQP exchanges?
+  #
+  # AMQP exchange is where AMQP clients send messages. AMQP
   # exchange may also be described as a router or a matcher. Every
   # published message is received by an exchange which, depending on its
-  # type (described below), determines how to deliver the message.
+  # type and message attributes, determines how to deliver the message.
+  #
+  #
+  # h2. Exchange types
+  #
+  # There are 4 supported exchange types: direct, fanout, topic and headers.
+  #
+  # As part of the standard, the server _must_ predeclare the direct exchange
+  # 'amq.direct' and the fanout exchange 'amq.fanout'. All exchange names
+  # starting with 'amq.' are reserved: attempts to declare an exchange using
+  # 'amq.' as the name will raise an AMQP::Error and fail.
   #
-  # It determines the next delivery hop by examining the bindings associated
-  # with the exchange.
+  # Note that durability of exchanges and durability of messages published to exchanges
+  # are different concepts. Sending messages to durable exchanges does not make
+  # messages themselves persistent.
+  #
+  #
+  # h2. AMQP bindings
+  #
+  # Closely related to exchange is a concept of bindings. A binding is
+  # the relationship between an exchange and a message queue that tells
+  # the exchange how to route messages. Bindings are set up by
+  # AMQP applications (usually the app owning and using the message queue
+  # sets up bindings for it). Exchange may be bound to none, 1 or more than 1
+  # queue.
+  #
+  #
+  # Defines, intializes and returns an Exchange to act as an ingress
+  # point for all published messages.
   #
   # There are three (3) supported Exchange types: direct, fanout and topic.
   #
@@ -17,222 +47,292 @@ module AMQP
   # 'amq.' as the name will raise an AMQP::Error and fail. In practice these
   # default exchanges are never used directly by client code.
   #
-  # These predececlared exchanges are used when the client code declares
-  # an exchange without a name. In these cases the library will use
-  # the default exchange for publishing the messages.
   #
-  class Exchange
+  # h2. Direct exchanges
+  #
+  # Direct exchanges are useful for 1:1 communication scenarios.
+  # Queues are bound to direct exchanges with a parameter called "routing key". When messages
+  # arrive to a direct exchange, broker takes that message's routing key (if any), finds a queue bound
+  # to the exchange with the same routing key and routes message there.
+  #
+  # Because very often queues are bound with the same routing key as queue's name, AMQP 0.9.1 has
+  # a pre-declared direct exchange known as default exchange. Default exchange is a bit special: broker
+  # automatically binds all the queues (in the same virtual host) to it with routing key equal to
+  # queue names. In other words, messages delivered to default exchange are routed to queues when
+  # message routing key equals queue name. Default exchange name is an empty string.
+  #
+  #
+  #
+  # h2. Fanout exchanges
+  #
+  # Fanout exchanges are useful for 1:n and n:m communication where one or more producer
+  # feeds multiple consumers. messages published
+  # to a fanout exchange are delivered to queues that are bound to that exchange name (unconditionally).
+  # Each queue gets it's own copy of the message.
+  #
+  #
+  #
+  # h2. Topic exchanges
+  #
+  # Topic exchanges are used for 1:n and n:m communication scenarios.
+  # Exchange of this type uses the routing key
+  # to determine which queues to deliver the message. Wildcard matching
+  # is allowed. The topic must be declared using dot notation to separate
+  # each subtopic.
+  #
+  # As part of the AMQP standard, each server _should_ predeclare a topic
+  # exchange called 'amq.topic'.
+  #
+  # The classic example is delivering market data. When publishing market
+  # data for stocks, we may subdivide the stream based on 2
+  # characteristics: nation code and trading symbol. The topic tree for
+  # Apple may look like stock.us.aapl. NASDAQ updates may use topic stocks.us.nasdaq,
+  # while DAX may use stock.de.dax.
+  #
+  # When publishing data to the exchange, bound queues subscribing to the
+  # exchange indicate which data interests them by passing a routing key
+  # for matching against the published routing key.
+  #
+  #
+  # h2. Headers exchanges
+  #
+  # As part of the AMQP standard, each server _should_ predeclare a headers
+  # exchange named 'amq.match'.
+  #
+  # When publishing data to the exchange, bound queues subscribing to the
+  # exchange indicate which data interests them by passing arguments
+  # for matching against the headers in published messages. The
+  # form of the matching can be controlled by the 'x-match' argument, which
+  # may be 'any' or 'all'. If unspecified, it defaults to "all".
+  #
+  # A value of 'all' for 'x-match' implies that all values must match (i.e.
+  # it does an AND of the headers ), while a value of 'any' implies that
+  # at least one should match (ie. it does an OR).
+  #
+  #
+  # h2. Exchange durability and persistence of messages.
+  #
+  # AMQP separates concept of durability of entities (queues, exchanges) from messages persistence.
+  # Exchanges can be durable or transient. Durable exchanges survive broker restart, transient exchanges don't (they
+  # have to be redeclared when broker comes back online). Not all scenarios and use cases mandate exchanges to be
+  # durable.
+  #
+  # The concept of messages persistence is separate: messages may be published as persistent. That makes
+  # AMQP broker persist them to disk. If the server is restarted, the system ensures that received persistent messages
+  # are not lost. Simply publishing message to a durable exchange or the fact that queue(s) they are routed to
+  # is durable doesn't make messages persistent: it all depends on persistence mode of the messages itself.
+  # Publishing messages as persistent affects performance (just like with data stores, durability comes at a certain cost
+  # in performance and vise versa). Pass :persistent => true to {Exchange#publish} to publish your message as persistent.
+  #
+  # Note that *only durable queues can be bound to durable exchanges*.
+  #
+  #
+  # h2. RabbitMQ extensions.
+  #
+  # AMQP gem supports several RabbitMQ extensions taht extend Exchange functionality.
+  # Learn more in {file:docs/VendorSpecificExtensions.textile}
+  #
+  #
+  # h2. Key methods
+  #
+  # Key methods of Exchange class are
+  #
+  # * {Exchange#publish}
+  # * {Exchange#delete}
+  # * {Exchange.default}
+  #
+  #
+  # @note Please make sure you read a section on exchanges durability vs. messages
+  #       persistence.
+  #
+  # @see http://www.rabbitmq.com/faq.html#managing-concepts-exchanges Exchanges explained in the RabbitMQ FAQ
+  # @see http://www.rabbitmq.com/faq.html#Binding-and-Routing Bindings and routing explained in the RabbitMQ FAQ
+  # @see Channel#default_exchange
+  # @see Channel#direct
+  # @see Channel#fanout
+  # @see Channel#topic
+  # @see Channel#headers
+  # @see Queue
+  # @see http://bit.ly/hw2ELX AMQP 0.9.1 specification (Section 2.1.1)
+  # @see http://bit.ly/hw2ELX AMQP 0.9.1 specification (Section 2.1.5)
+  # @see http://bit.ly/hw2ELX AMQP 0.9.1 specification (Section 3.1.3)
+  class Exchange < AMQ::Client::Exchange
 
     #
     # API
     #
 
+    DEFAULT_CONTENT_TYPE = "application/octet-stream".freeze
 
-    # The default exchange.
-    # Every queue is bind to this (direct) exchange by default.
-    # You can't remove it or bind there queue explicitly.
-
-    # Do NOT confuse with amq.direct: it's only a normal direct
-    # exchange and the only special thing about it is that it's
-    # predefined in the system, so you can use it straightaway.
 
-    # Example:
-    # AMQP::Channel.new.queue("tasks")
-    # AMQP::Channel::Exchange.default.publish("make clean", routing_key: "tasks")
-
-    # For more info see section 2.1.2.4 Automatic Mode of the AMQP 0.9.1 spec.
+    # The default exchange. Default exchange is a direct exchange that is predefined.
+    # It cannot be removed. Every queue is bind to this (direct) exchange by default with
+    # the following routing semantics: messages will be routed to the queue withe same
+    # same name as message's routing key. In other words, if a message is published with
+    # a routing key of "weather.usa.ca.sandiego" and there is a queue Q with this name,
+    # that message will be routed to Q.
+    #
+    # @param [AMQP::Channel] channel Channel to use. If not given, new AMQP channel
+    #                                will be opened on the default AMQP connection (accessible as AMQP.connection).
+    #
+    # @example Publishing a messages to the tasks queue
+    #   channel     = AMQP::Channel.new(connection)
+    #   tasks_queue = channel.queue("tasks")
+    #   AMQP::Exchange.default(channel).publish("make clean", routing_key => "tasks")
+    #
+    # @see Exchange
+    # @see http://bit.ly/hw2ELX AMQP 0.9.1 specification (Section 2.1.2.4)
+    # @note Do not confuse default exchange with amq.direct: amq.direct is a pre-defined direct
+    #       exchange that doesn't have any special routing semantics.
+    # @return [Exchange] An instance that corresponds to the default exchange (of type direct).
+    # @api public
     def self.default(channel = nil)
-      self.new(channel || AMQP::Channel.new, :direct, "", :no_declare => true)
+      self.new(channel || AMQP::Channel.new, :direct, AMQ::Protocol::EMPTY_STRING, :no_declare => true)
     end
 
-    def self.add_default_options(type, name, opts, block)
-      { :exchange => name, :type => type, :nowait => block.nil? }.merge(opts)
+
+    # @return [String]
+    attr_reader :name
+
+    # Type of this exchange (one of: :direct, :fanout, :topic, :headers).
+    # @return [Symbol]
+    attr_reader :type
+
+    # @return [Symbol]
+    # @api plugin
+    attr_reader :status
+
+    # Options hash this exchange instance was instantiated with
+    # @return [Hash]
+    attr_accessor :opts
+
+    # @return [#call] A callback that is executed once declaration notification (exchange.declare-ok)
+    #                 from the broker arrives.
+    attr_accessor :on_declare
+
+    # @return [String]
+    attr_reader :default_routing_key
+    alias key default_routing_key
+
+    # Compatibility alias for #on_declare.
+    #
+    # @api public
+    # @deprecated
+    # @return [#call]
+    def callback
+      @on_declare
     end
 
-    # Defines, intializes and returns an Exchange to act as an ingress
-    # point for all published messages.
-    #
-    # There are three (3) supported Exchange types: direct, fanout and topic.
-    #
-    # As part of the standard, the server _must_ predeclare the direct exchange
-    # 'amq.direct' and the fanout exchange 'amq.fanout' (all exchange names
-    # starting with 'amq.' are reserved). Attempts to declare an exchange using
-    # 'amq.' as the name will raise an AMQP::Error and fail. In practice these
-    # default exchanges are never used directly by client code.
-    #
-    # == Direct
-    # A direct exchange is useful for 1:1 communication between a publisher and
-    # subscriber. Messages are routed to the queue with a binding that shares
-    # the same name as the exchange. Alternately, the messages are routed to
-    # the bound queue that shares the same name as the routing key used for
-    # defining the exchange. This exchange type does not honor the :key option
-    # when defining a new instance with a name. It _will_ honor the :key option
-    # if the exchange name is the empty string. This is because an exchange
-    # defined with the empty string uses the default pre-declared exchange
-    # called 'amq.direct'. In this case it needs to use :key to do its matching.
-    #
-    #  # exchange is named 'foo'
-    #  exchange = AMQP::Channel::Exchange.new(AMQP::Channel.new, :direct, 'foo')
-    #
-    #  # or, the exchange can use the default name (amq.direct) and perform
-    #  # routing comparisons using the :key
-    #  exchange = AMQP::Channel::Exchange.new(AMQP::Channel.new, :direct, "", :key => 'foo')
-    #  exchange.publish('some data') # will be delivered to queue bound to 'foo'
-    #
-    #  queue = AMQP::Channel::Queue.new(AMQP::Channel.new, 'foo')
-    #  # can receive data since the queue name and the exchange key match exactly
-    #  queue.pop { |data| puts "received data [#{data}]" }
-    #
-    # == Fanout
-    # A fanout exchange is useful for 1:N communication where one publisher
-    # feeds multiple subscribers. Like direct exchanges, messages published
-    # to a fanout exchange are delivered to queues whose name matches the
-    # exchange name (or are bound to that exchange name). Each queue gets
-    # its own copy of the message.
-    #
-    # Like the direct exchange type, this exchange type does not honor the
-    # :key option when defining a new instance with a name. It _will_ honor
-    # the :key option if the exchange name is the empty string. Fanout exchanges
-    # defined with the empty string as the name use the default 'amq.fanout'.
-    # In this case it needs to use :key to do its matching.
-    #
-    #  EM.run do
-    #    clock = AMQP::Channel::Exchange.new(AMQP::Channel.new, :fanout, 'clock')
-    #    EM.add_periodic_timer(1) do
-    #      puts "\npublishing #{time = Time.now}"
-    #      clock.publish(Marshal.dump(time))
-    #    end
-    #
-    #    # one way of defining a queue
-    #    amq = AMQP::Channel::Queue.new(AMQP::Channel.new, 'every second')
-    #    amq.bind(AMQP::Channel.fanout('clock')).subscribe do |time|
-    #      puts "every second received #{Marshal.load(time)}"
-    #    end
-    #
-    #    # defining a queue using the convenience method
-    #    # note the string passed to #bind
-    #    AMQP::Channel.queue('every 5 seconds').bind('clock').subscribe do |time|
-    #      time = Marshal.load(time)
-    #      puts "every 5 seconds received #{time}" if time.strftime('%S').to_i%5 == 0
-    #    end
-    #  end
-    #
-    # == Topic
-    # A topic exchange allows for messages to be published to an exchange
-    # tagged with a specific routing key. The Exchange uses the routing key
-    # to determine which queues to deliver the message. Wildcard matching
-    # is allowed. The topic must be declared using dot notation to separate
-    # each subtopic.
-    #
-    # This is the only exchange type to honor the :key parameter.
-    #
-    # As part of the AMQP standard, each server _should_ predeclare a topic
-    # exchange called 'amq.topic' (this is not required by the standard).
-    #
-    # The classic example is delivering market data. When publishing market
-    # data for stocks, we may subdivide the stream based on 2
-    # characteristics: nation code and trading symbol. The topic tree for
-    # Apple Computer would look like:
-    #  'stock.us.aapl'
-    # For a foreign stock, it may look like:
-    #  'stock.de.dax'
-    #
-    # When publishing data to the exchange, bound queues subscribing to the
-    # exchange indicate which data interests them by passing a routing key
-    # for matching against the published routing key.
-    #
-    #  EM.run do
-    #    exch = AMQP::Channel::Exchange.new(AMQP::Channel.new, :topic, "stocks")
-    #    keys = ['stock.us.aapl', 'stock.de.dax']
-    #
-    #    EM.add_periodic_timer(1) do # every second
-    #      puts
-    #      exch.publish(10+rand(10), :routing_key => keys[rand(2)])
-    #    end
-    #
-    #    # match against one dot-separated item
-    #    AMQP::Channel.queue('us stocks').bind(exch, :key => 'stock.us.*').subscribe do |price|
-    #      puts "us stock price [#{price}]"
-    #    end
-    #
-    #    # match against multiple dot-separated items
-    #    AMQP::Channel.queue('all stocks').bind(exch, :key => 'stock.#').subscribe do |price|
-    #      puts "all stocks: price [#{price}]"
-    #    end
-    #
-    #    # require exact match
-    #    AMQP::Channel.queue('only dax').bind(exch, :key => 'stock.de.dax').subscribe do |price|
-    #      puts "dax price [#{price}]"
-    #    end
-    #  end
-    #
-    # For matching, the '*' (asterisk) wildcard matches against one
-    # dot-separated item only. The '#' wildcard (hash or pound symbol)
-    # matches against 0 or more dot-separated items. If none of these
-    # symbols are used, the exchange performs a comparison looking for an
-    # exact match.
+
+
+    # See {Exchange Exchange class documentation} for introduction, information about exchange types,
+    # what uses cases they are good for and so on.
     #
-    # == Options
-    # * :passive => true | false (default false)
-    # If set, the server will not create the exchange if it does not
-    # already exist. The client can use this to check whether an exchange
-    # exists without modifying  the server state.
-    #
-    # * :durable => true | false (default false)
-    # If set when creating a new exchange, the exchange will be marked as
-    # durable.  Durable exchanges remain active when a server restarts.
-    # Non-durable exchanges (transient exchanges) are purged if/when a
-    # server restarts.
-    #
-    # A transient exchange (the default) is stored in memory-only
-    # therefore it is a good choice for high-performance and low-latency
-    # message publishing.
-    #
-    # Durable exchanges cause all messages to be written to non-volatile
-    # backing store (i.e. disk) prior to routing to any bound queues.
-    #
-    # * :auto_delete => true | false (default false)
-    # If set, the exchange is deleted when all queues have finished
-    # using it. The server waits for a short period of time before
-    # determining the exchange is unused to give time to the client code
-    # to bind a queue to it.
-    #
-    # If the exchange has been previously declared, this option is ignored
-    # on subsequent declarations.
-    #
-    # * :internal => true | false (default false)
-    # If set, the exchange may not be used directly by publishers, but
-    # only when bound to other exchanges. Internal exchanges are used to
-    # construct wiring that is not visible to applications.
+    # h2. Predeclared exchanges
     #
-    # * :nowait => true | false (default true)
-    # If set, the server will not respond to the method. The client should
-    # not wait for a reply method.  If the server could not complete the
-    # method it will raise a channel or connection exception.
+    # If exchange name corresponds to one of those predeclared by AMQP 0.9.1 specification (empty string, amq.direct, amq.fanout, amq.topic, amq.match),
+    # declaration command won't be sent to the broker (because the only possible reply from the broker is to reject it, predefined entities cannot be changed).
+    # Callback, if any, will be executed immediately.
+    #
+    #
+    #
+    # @example Instantiating a fanout exchange using constructor
+    #
+    #   AMQP.connect do |connection|
+    #     AMQP::Channel.new(connection) do |channel|
+    #       AMQP::Exchange.new(channel, :fanout, "search.index.updates") do |exchange, declare_ok|
+    #         # by now exchange is ready and waiting
+    #       end
+    #     end
+    #   end
+    #
+    #
+    # @example Instantiating a direct exchange using {Channel#direct}
+    #
+    #   AMQP.connect do |connection|
+    #     AMQP::Channel.new(connection) do |channel|
+    #       channel.direct("email.replies_listener") do |exchange, declare_ok|
+    #         # by now exchange is ready and waiting
+    #       end
+    #     end
+    #   end
+    #
+    #
+    # @param [Channel] channel AMQP channel this exchange is associated with
+    # @param [Symbol]  type    Exchange type
+    # @param [String]  name    Exchange name
     #
-    # * :no_declare => true | false (default false)
-    # If set, the exchange will not be declared to the
-    # AMQP broker at instantiation-time. This allows the AMQP
-    # client to send messages to exchanges that were
-    # already declared by someone else, e.g. if the client
-    # does not have sufficient privilege to declare (create)
-    # an exchange. Use with caution, as binding to an exchange
-    # with the no-declare option causes your system to become
-    # sensitive to the ordering of clients' actions!
-    #
-    # == Exceptions
-    # Doing any of these activities are illegal and will raise exceptions:
-    #
-    # * redeclare an already-declared exchange to a different type (raises AMQP::Channel::IncompatibleOptionsError)
-    # * :passive => true and the exchange does not exist (NOT_FOUND)
-    #
-    def initialize(mq, type, name, opts = {}, &block)
-      @mq = mq
-      @type, @opts = type, opts
-      @opts = self.class.add_default_options(type, name, opts, block)
-      @key = opts[:key]
-      @name = name unless name.empty?
-      @status = :unknown
+    #
+    # @option opts [Boolean] :passive (false)  If set, the server will not create the exchange if it does not
+    #                                          already exist. The client can use this to check whether an exchange
+    #                                          exists without modifying the server state.
+    #
+    # @option opts [Boolean] :durable (false)  If set when creating a new exchange, the exchange will be marked as
+    #                                          durable. Durable exchanges and their bindings are recreated upon a server
+    #                                          restart (information about them is persisted). Non-durable (transient) exchanges
+    #                                          do not survive if/when a server restarts (information about them is stored exclusively
+    #                                          in RAM).
+    #
+    #
+    # @option opts [Boolean] :auto_delete  (false)  If set, the exchange is deleted when all queues have finished
+    #                                               using it. The server waits for a short period of time before
+    #                                               determining the exchange is unused to give time to the client code
+    #                                               to bind a queue to it.
+    #
+    # @option opts [Boolean] :internal (false)      If set, the exchange may not be used directly by publishers, but
+    #                                               only when bound to other exchanges. Internal exchanges are used to
+    #                                               construct wiring that is not visible to applications. *This is a RabbitMQ-specific
+    #                                               extension.*
+    #
+    # @option opts [Boolean] :nowait (true)         If set, the server will not respond to the method. The client should
+    #                                               not wait for a reply method.  If the server could not complete the
+    #                                               method it will raise a channel or connection exception.
+    #
+    # @option opts [Boolean] :no_declare (true)     If set, exchange declaration command won't be sent to the broker. Allows to forcefully
+    #                                               avoid declaration. We recommend that only experienced developers consider this option.
+    #
+    # @option opts [String] :default_routing_key (nil)  Default routing key that will be used by {Exchange#publish} when no routing key is not passed explicitly.
+    #                                                   It is perfectly fine for applications to always specify routing key to {Exchange#publish}.
+    #
+    #
+    # @raise [AMQP::Error] Raised when exchange is redeclared with parameters different from original declaration.
+    # @raise [AMQP::Error] Raised when exchange is declared with :passive => true and the exchange does not exist.
+    #
+    # @yield [exchange, declare_ok] Yields successfully declared exchange instance and AMQP method (exchange.declare-ok) instance. The latter is optional.
+    # @yieldparam [Exchange] exchange Exchange that is successfully declared and is ready to be used.
+    # @yieldparam [AMQP::Protocol::Exchange::DeclareOk] declare_ok AMQP exchange.declare-ok) instance.
+    #
+    # @see Channel#default_exchange
+    # @see Channel#direct
+    # @see Channel#fanout
+    # @see Channel#topic
+    # @see Channel#headers
+    # @see Queue
+    # @see http://bit.ly/hw2ELX AMQP 0.9.1 specification (Section 3.1.3)
+    #
+    # @return [Exchange]
+    # @api public
+    def initialize(channel, type, name, opts = {}, &block)
+      @channel             = channel
+      @type                = type
+      @opts                = self.class.add_default_options(type, name, opts, block)
+      @default_routing_key = opts[:routing_key] || opts[:key]
+      @name                = name unless name.empty?
+
+      @status                  = :unknown
+      @default_publish_options = (opts.delete(:default_publish_options) || {
+                                    :routing_key  => AMQ::Protocol::EMPTY_STRING,
+                                    :mandatory    => false,
+                                    :immediate    => false
+                                  }).freeze
+
+      @default_headers = (opts.delete(:default_headers) || {
+                            :content_type => DEFAULT_CONTENT_TYPE,
+                            :persistent   => false,
+                            :priority     => 0
+                          }).freeze
+
+      super(channel.connection, channel, name, type)
 
       # The AMQP 0.8 specification (as well as 0.9.1) in 1.1.4.2 mentiones
       # that Exchange.Declare-Ok confirms the name of the exchange (because
@@ -244,98 +344,118 @@ module AMQP
       # or nameless exchange), so if we'd send Exchange.Declare(exchange=""),
       # then RabbitMQ interpret it as if we'd try to redefine this default
       # exchange so it'd produce an error.
-      unless name == "amq.#{type}" or name == '' or opts[:no_declare]
-        @status = :unfinished
-        @mq.callback {
-          @mq.send Protocol::Exchange::Declare.new(@opts)
-        }
+      unless name == "amq.#{type}" or name.empty? or opts[:no_declare]
+        @status = :opening
+
+        shim = Proc.new do |exchange, declare_ok|
+          case block.arity
+          when 1 then block.call(exchange)
+          else
+            block.call(exchange, declare_ok)
+          end
+        end
+
+        unless @opts[:no_declare]
+          @channel.once_open do
+            self.declare(passive = @opts[:passive], durable = @opts[:durable], exclusive = @opts[:exclusive], auto_delete = @opts[:auto_delete], nowait = @opts[:nowait], nil, &shim)
+          end
+        end
       else
         # Call the callback immediately, as given exchange is already
         # declared.
-        @status = :finished
+        @status = :opened
         block.call(self) if block
       end
 
-      self.callback = block
+      @on_declare = block
     end
 
-    attr_reader :name, :type, :key, :status
-    attr_accessor :opts, :callback
-
+    # @return [Channel]
+    # @api public
     def channel
-      @mq
-    end # channel
+      @channel
+    end
 
-    # This method publishes a staged file message to a specific exchange.
-    # The file message will be routed to queues as defined by the exchange
-    # configuration and distributed to any active consumers when the
-    # transaction, if any, is committed.
+    # Publishes message to the exchange. The message will be routed to queues by the exchange
+    # and distributed to any active consumers. Routing logic is determined by exchange type and
+    # configuration as well as  message attributes (like :routing_key).
     #
-    #  exchange = AMQP::Channel.direct('name', :key => 'foo.bar')
-    #  exchange.publish("some data")
+    # h2. Data serialization
     #
-    # The method takes several hash key options which modify the behavior or
-    # lifecycle of the message.
+    # Note that this method calls #to_s on payload argument value. You are encouraged to take care of
+    # data serialization before publishing (using JSON, Thrift, Protocol Buffers or other serialization library).
+    # Note that because AMQP is a binary protocol, text formats like JSON lose lose their strong point of being easy
+    # to inspect data as it travels across network.
     #
-    # * :routing_key => 'string'
     #
-    # Specifies the routing key for the message.  The routing key is
-    # used for routing messages depending on the exchange configuration.
     #
-    # * :mandatory => true | false (default false)
+    # h2. Event loop blocking
     #
-    # This flag tells the server how to react if the message cannot be
-    # routed to a queue.  If this flag is set, the server will return an
-    # unroutable message with a Return method.  If this flag is zero, the
-    # server silently drops the message.
+    # To minimize blocking of EventMachine event loop, this method performs network I/O on the next event loop tick.
     #
-    # * :immediate => true | false (default false)
+    # @param  [#to_s] payload  Message payload (content). Note that this method calls #to_s on payload argument value.
+    #                          You are encouraged to take care of data serialization before publishing (using JSON, Thrift,
+    #                          Protocol Buffers or other serialization library).
     #
-    # This flag tells the server how to react if the message cannot be
-    # routed to a queue consumer immediately.  If this flag is set, the
-    # server will return an undeliverable message with a Return method.
-    # If this flag is zero, the server will queue the message, but with
-    # no guarantee that it will ever be consumed.
+    # @option options [String] :routing_key (nil)  Specifies message routing key. Routing key determines
+    #                                      what queues messages are delivered to (exact routing algorithms vary
+    #                                      between exchange types).
     #
-    #  * :persistent
-    # True or False. When true, this message will remain in the queue until
-    # it is consumed (if the queue is durable). When false, the message is
-    # lost if the server restarts and the queue is recreated.
+    # @option options [Boolean] :mandatory (false) This flag tells the server how to react if the message cannot be
+    #                                      routed to a queue. If message is mandatory, the server will return
+    #                                      unroutable message back to the client with basic.return AMQPmethod.
+    #                                      If message is not mandatory, the server silently drops the message.
     #
-    # For high-performance and low-latency, set :persistent => false so the
-    # message stays in memory and is never persisted to non-volatile (slow)
-    # storage.
+    # @option options [Boolean] :immediate (false) This flag tells the server how to react if the message cannot be
+    #                                      routed to a queue consumer immediately.  If this flag is set, the
+    #                                      server will return an undeliverable message with a Return method.
+    #                                      If this flag is zero, the server will queue the message, but with
+    #                                      no guarantee that it will ever be consumed.
     #
-    #  * :content_type
-    # Content type you want to send the message with. It defaults to "application/octet-stream".
-    def publish(data, opts = {})
-      @mq.callback {
-        out = []
-
-        out << Protocol::Basic::Publish.new({ :exchange => name,
-                                              :routing_key => opts[:key] || @key }.merge(opts))
-
-        data = data.to_s
-
-        out << Protocol::Header.new(Protocol::Basic,
-                                    data.bytesize, { opts[:content_type] || :content_type => "application/octet-stream",
-                                                   :delivery_mode => (opts[:persistent] ? 2 : 1),
-                                                   :priority => 0 }.merge(opts))
+    # @option options [Boolean] :persistent (false) When true, this message will be persisted to disk and remain in the queue until
+    #                                       it is consumed. When false, the message is only kept in a transient store
+    #                                       and will lost in case of server restart.
+    #                                       When performance and latency are more important than durability, set :persistent => false.
+    #                                       If durability is more important, set :persistent => true.
+    #
+    # @option options [String] :content_type (application/octet-stream) Content-type of message payload.
+    #
+    #
+    # @example Publishing without routing key
+    #  exchange = channel.fanout('search.indexer')
+    #  # fanout exchanges deliver messages to bound queues unconditionally,
+    #  # so routing key is unnecessary here
+    #  exchange.publish("some data")
+    #
+    # @example Publishing with a routing key
+    #  exchange = channel.direct('search.indexer')
+    #  exchange.publish("some data", :routing_key => "search.index.updates")
+    #
+    # @return [Exchange] self
+    #
+    # @note Please make sure you read {Exchange Exchange class} documentation section on exchanges durability vs. messages
+    #       persistence.
+    # @api public
+    def publish(payload, options = {}, &block)
+      EM.next_tick do
+        opts    = @default_publish_options.merge(options)
 
-        out << Frame::Body.new(data)
+        @channel.once_open do
+          super(payload.to_s, opts[:key] || opts[:routing_key] || @default_routing_key, @default_headers.merge(options), opts[:mandatory], opts[:immediate], &block)
+        end
+      end
 
-        @mq.send *out
-      }
       self
     end
 
+
     # This method deletes an exchange.  When an exchange is deleted all queue
     # bindings on the exchange are cancelled.
     #
     # Further attempts to publish messages to a deleted exchange will raise
     # an AMQP::Channel::Error due to a channel close exception.
     #
-    #  exchange = AMQP::Channel.direct('name', :key => 'foo.bar')
+    #  exchange = AMQP::Channel.direct('name', :routing_key => 'foo.bar')
     #  exchange.delete
     #
     # == Options
@@ -351,43 +471,51 @@ module AMQP
     # bindings. If the exchange has queue bindings the server does not
     # delete it but raises a channel exception instead (AMQP::Error).
     #
-    def delete(opts = {})
-      @mq.callback {
-        @mq.send Protocol::Exchange::Delete.new({ :exchange => name,
-                                                  :nowait => true }.merge(opts))
-        @mq.exchanges.delete name
-      }
+    # @api public
+    def delete(opts = {}, &block)
+      @channel.once_open do
+        super(opts.fetch(:if_unused, false), opts.fetch(:nowait, false), &block)
+      end
+
+      # backwards compatibility
       nil
     end
 
-
+    # @return [Boolean] true if this exchange is durable
+    # @note Please make sure you read {Exchange Exchange class} documentation section on exchanges durability vs. messages
+    #       persistence.
+    # @api public
     def durable?
       !!@opts[:durable]
     end # durable?
 
+    # @return [Boolean] true if this exchange is transient (non-durable)
+    # @note Please make sure you read {Exchange Exchange class} documentation section on exchanges durability vs. messages
+    #       persistence.
+    # @api public
     def transient?
       !self.durable?
     end # transient?
+    alias temporary? transient?
 
+    # @return [Boolean] true if this exchange is automatically deleted when it is no longer used
+    # @api public
     def auto_deleted?
       !!@opts[:auto_delete]
     end # auto_deleted?
     alias auto_deletable? auto_deleted?
 
-
+    # Resets queue state. Useful for error handling.
+    # @api plugin
     def reset
-      @deferred_status = nil
-      initialize @mq, @type, @name, @opts
+      initialize(@channel, @type, @name, @opts)
     end
 
 
+    protected
 
-    #
-    # Implementation
-    #
-
-    def receive_response(response)
-      self.callback && self.callback.call(self)
-    end # receive_response
+    def self.add_default_options(type, name, opts, block)
+      { :exchange => name, :type => type, :nowait => block.nil? }.merge(opts)
+    end
   end # Exchange
 end # AMQP