right_amqp 0.2.0

data/lib/right_amqp/mq/exchange.rb

@@ -0,0 +1,304 @@
+class MQ
+  # An Exchange acts as an ingress point for all published messages. An
+  # 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.
+  #
+  # It determines the next delivery hop by examining the bindings associated
+  # with the exchange.
+  #
+  # 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 MQ: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
+    include AMQP
+
+    # 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 MQ: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 = MQ::Exchange.new(MQ.new, :direct, 'foo')
+    #
+    #  # or, the exchange can use the default name (amq.direct) and perform
+    #  # routing comparisons using the :key
+    #  exchange = MQ::Exchange.new(MQ.new, :direct, "", :key => 'foo')
+    #  exchange.publish('some data') # will be delivered to queue bound to 'foo'
+    #
+    #  queue = MQ::Queue.new(MQ.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 = MQ::Exchange.new(MQ.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 = MQ::Queue.new(MQ.new, 'every second')
+    #    amq.bind(MQ.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
+    #    MQ.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 = MQ::Exchange.new(MQ.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
+    #    MQ.queue('us stocks').bind(exch, :key => 'stock.us.*').subscribe do |price|
+    #      puts "us stock price [#{price}]"
+    #    end
+    #
+    #    # match against multiple dot-separated items
+    #    MQ.queue('all stocks').bind(exch, :key => 'stock.#').subscribe do |price|
+    #      puts "all stocks: price [#{price}]"
+    #    end
+    #
+    #    # require exact match
+    #    MQ.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.
+    #
+    # == 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.
+    #
+    # * :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.
+    #
+    # == Exceptions
+    # Doing any of these activities are illegal and will raise MQ:Error.
+    # * redeclare an already-declared exchange to a different type
+    # * :passive => true and the exchange does not exist (NOT_FOUND)
+    #
+    def initialize mq, type, name, opts = {}
+      @mq = mq
+      @type, @name, @opts = type, name, opts
+      @mq.exchanges[@name = name] ||= self
+      @key = opts[:key]
+      
+      unless name == "amq.#{type}" or name == '' or opts[:no_declare]
+        @mq.callback{
+          @mq.send Protocol::Exchange::Declare.new({ :exchange => name,
+                                                     :type => type,
+                                                     :nowait => true }.merge(opts))
+        }
+      end
+    end
+    attr_reader :name, :type, :key
+
+    # 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.
+    #
+    #  exchange = MQ.direct('name', :key => 'foo.bar')
+    #  exchange.publish("some data")
+    #
+    # The method takes several hash key options which modify the behavior or 
+    # lifecycle of the message.
+    #
+    # * :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)
+    #
+    # 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.
+    #
+    # * :immediate => true | false (default 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.
+    #
+    #  * :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.
+    #
+    # For high-performance and low-latency, set :persistent => false so the
+    # message stays in memory and is never persisted to non-volatile (slow)
+    # storage.
+    #
+    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, { :content_type => 'application/octet-stream',
+                                                     :delivery_mode => (opts[:persistent] ? 2 : 1),
+                                                     :priority => 0 }.merge(opts))
+
+        out << Frame::Body.new(data)
+
+        @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 MQ::Error due to a channel close exception.
+    #
+    #  exchange = MQ.direct('name', :key => 'foo.bar')
+    #  exchange.delete
+    #
+    # == Options
+    # * :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.
+    #
+    #  exchange.delete(:nowait => false)
+    #
+    # * :if_unused => true | false (default false)
+    # If set, the server will only delete the exchange if it has no queue
+    # bindings. If the exchange has queue bindings the server does not
+    # delete it but raises a channel exception instead (MQ:Error).
+    #    
+    def delete opts = {}
+      @mq.callback{
+        @mq.send Protocol::Exchange::Delete.new({ :exchange => name,
+                                                  :nowait => true }.merge(opts))
+        @mq.exchanges.delete name
+      }
+      nil
+    end
+
+    def reset
+      @deferred_status = nil
+      initialize @mq, @type, @name, @opts
+    end
+  end
+end

data/lib/right_amqp/mq/header.rb

@@ -0,0 +1,33 @@
+class MQ
+  class Header
+    include AMQP
+
+    def initialize(mq, header_obj)
+      @mq = mq
+      @header = header_obj
+    end
+
+    # Acknowledges the receipt of this message with the server.
+    def ack
+      @mq.callback{
+        @mq.send Protocol::Basic::Ack.new(:delivery_tag => properties[:delivery_tag])
+      }
+    end
+
+    # Reject this message (XXX currently unimplemented in rabbitmq)
+    # * :requeue => true | false (default false)
+    def reject opts = {}
+      @mq.callback{
+        @mq.send Protocol::Basic::Reject.new(opts.merge(:delivery_tag => properties[:delivery_tag]))
+      }
+    end
+
+    def method_missing meth, *args, &blk
+      @header.send meth, *args, &blk
+    end
+
+    def inspect
+      @header.inspect
+    end
+  end
+end

data/lib/right_amqp/mq/logger.rb

@@ -0,0 +1,89 @@
+class MQ
+  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?
+        MQ.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

data/lib/right_amqp/mq/queue.rb

@@ -0,0 +1,456 @@
+class MQ
+  class Queue
+    include AMQP
+    
+    # Queues store and forward messages.  Queues can be configured in the server
+    # or created at runtime.  Queues must be attached to at least one exchange
+    # in order to receive messages from publishers.
+    #
+    # Like an Exchange, queue names starting with 'amq.' are reserved for
+    # internal use. Attempts to create queue names in violation of this
+    # reservation will raise MQ:Error (ACCESS_REFUSED).
+    #
+    # When a queue is created without a name, the server will generate a 
+    # unique name internally (not currently supported in this library).
+    #
+    # == 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 queue, the queue will be marked as
+    # durable.  Durable queues remain active when a server restarts.
+    # Non-durable queues (transient queues) are purged if/when a
+    # server restarts.  Note that durable queues do not necessarily
+    # hold persistent messages, although it does not make sense to
+    # send persistent messages to a transient queue (though it is
+    # allowed).
+    #
+    # If the queue has already been declared, any redeclaration will
+    # ignore this setting. A queue may only be declared durable the
+    # first time when it is created.
+    #
+    # * :exclusive => true | false (default false)
+    # Exclusive queues may only be consumed from by the current connection.
+    # Setting the 'exclusive' flag always implies 'auto-delete'. Only a
+    # single consumer is allowed to remove messages from this queue.
+    #
+    # The default is a shared queue. Multiple clients may consume messages
+    # from this queue.
+    #
+    # Attempting to redeclare an already-declared queue as :exclusive => true
+    # will raise MQ:Error.
+    #
+    # * :auto_delete = true | false (default false)
+    # If set, the queue is deleted when all consumers have finished
+    # using it. Last consumer can be cancelled either explicitly or because
+    # its channel is closed. If there was no consumer ever on the queue, it
+    # won't be deleted. 
+    #
+    # The server waits for a short period of time before
+    # determining the queue is unused to give time to the client code
+    # to bind an exchange to it.
+    #
+    # If the queue has been previously declared, this option is ignored
+    # on subsequent declarations.
+    #
+    # * :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.
+    #
+    def initialize mq, name, opts = {}
+      @mq = mq
+      @opts = opts
+      @bindings ||= {}
+      @mq.queues[@name = name] ||= self
+      unless opts[:no_declare]
+        @mq.callback{
+          @mq.send Protocol::Queue::Declare.new({ :queue => name,
+                                                  :nowait => true }.merge(opts))
+        }
+      end
+    end
+    attr_reader :name
+
+    # This method binds a queue to an exchange.  Until a queue is
+    # bound it will not receive any messages.  In a classic messaging
+    # model, store-and-forward queues are bound to a dest exchange
+    # and subscription queues are bound to a dest_wild exchange.
+    #
+    # A valid exchange name (or reference) must be passed as the first
+    # parameter. Both of these are valid:
+    #  exch = MQ.direct('foo exchange')
+    #  queue = MQ.queue('bar queue')
+    #  queue.bind('foo.exchange') # OR
+    #  queue.bind(exch)
+    #
+    # It is not valid to call #bind without the +exchange+ parameter.
+    #
+    # It is unnecessary to call #bind when the exchange name and queue
+    # name match exactly (for +direct+ and +fanout+ exchanges only).
+    # There is an implicit bind which will deliver the messages from
+    # the exchange to the queue.
+    #
+    # == Options
+    # * :key => 'some string'
+    # Specifies the routing key for the binding.  The routing key is
+    # used for routing messages depending on the exchange configuration.
+    # Not all exchanges use a routing key - refer to the specific
+    # exchange documentation.  If the routing key is empty and the queue
+    # name is empty, the routing key will be the current queue for the
+    # channel, which is the last declared queue.
+    #
+    # * :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.
+    #
+    def bind exchange, opts = {}
+      exchange = exchange.respond_to?(:name) ? exchange.name : exchange
+      @bindings[exchange] = opts
+
+      @mq.callback{
+        @mq.send Protocol::Queue::Bind.new({ :queue => name,
+                                             :exchange => exchange,
+                                             :routing_key => opts[:key],
+                                             :nowait => true }.merge(opts))
+      }
+      self
+    end
+
+    # Remove the binding between the queue and exchange. The queue will
+    # not receive any more messages until it is bound to another 
+    # exchange.
+    #
+    # Due to the asynchronous nature of the protocol, it is possible for
+    # "in flight" messages to be received after this call completes.
+    # Those messages will be serviced by the last block used in a
+    # #subscribe or #pop call.
+    #
+    # * :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.
+    #
+    def unbind exchange, opts = {}
+      exchange = exchange.respond_to?(:name) ? exchange.name : exchange
+      @bindings.delete exchange
+
+      @mq.callback{
+        @mq.send Protocol::Queue::Unbind.new({ :queue => name,
+                                               :exchange => exchange,
+                                               :routing_key => opts[:key],
+                                               :nowait => true }.merge(opts))
+      }
+      self
+    end
+
+    # This method deletes a queue.  When a queue is deleted any pending
+    # messages are sent to a dead-letter queue if this is defined in the
+    # server configuration, and all consumers on the queue are cancelled.
+    #
+    # == Options
+    # * :if_unused => true | false (default false)
+    # If set, the server will only delete the queue if it has no
+    # consumers. If the queue has consumers the server does does not
+    # delete it but raises a channel exception instead.
+    #
+    # * :if_empty => true | false (default false)
+    # If set, the server will only delete the queue if it has no
+    # messages. If the queue is not empty the server raises a channel
+    # exception.
+    #
+    # * :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.
+    #
+    def delete opts = {}
+      @mq.callback{
+        @mq.send Protocol::Queue::Delete.new({ :queue => name,
+                                               :nowait => true }.merge(opts))
+      }
+      @mq.queues.delete @name
+      nil
+    end
+
+    # Purge all messages from the queue.
+    #
+    def purge opts = {}
+      @mq.callback{
+        @mq.send Protocol::Queue::Purge.new({ :queue => name,
+                                              :nowait => true }.merge(opts))
+      }
+      nil
+    end
+
+    # This method provides a direct access to the messages in a queue
+    # using a synchronous dialogue that is designed for specific types of
+    # application where synchronous functionality is more important than
+    # performance.
+    #
+    # The provided block is passed a single message each time pop is called.
+    #
+    #  EM.run do
+    #    exchange = MQ.direct("foo queue")
+    #    EM.add_periodic_timer(1) do
+    #      exchange.publish("random number #{rand(1000)}")
+    #    end
+    #    
+    #    # note that #bind is never called; it is implicit because
+    #    # the exchange and queue names match
+    #    queue = MQ.queue('foo queue')
+    #    queue.pop { |body| puts "received payload [#{body}]" }
+    #
+    #    EM.add_periodic_timer(1) { queue.pop }
+    #  end
+    #
+    # If the block takes 2 parameters, both the +header+ and the +body+ will
+    # be passed in for processing. The header object is defined by
+    # AMQP::Protocol::Header.
+    #
+    #  EM.run do
+    #    exchange = MQ.direct("foo queue")
+    #    EM.add_periodic_timer(1) do
+    #      exchange.publish("random number #{rand(1000)}")
+    #    end
+    #    
+    #    queue = MQ.queue('foo queue')
+    #    queue.pop do |header, body| 
+    #      p header
+    #      puts "received payload [#{body}]"
+    #    end
+    #
+    #    EM.add_periodic_timer(1) { queue.pop }
+    #  end
+    #
+    # == Options
+    # * :ack => true | false (default false)
+    # If this field is set to false the server does not expect acknowledgments
+    # for messages.  That is, when a message is delivered to the client
+    # the server automatically and silently acknowledges it on behalf
+    # of the client.  This functionality increases performance but at
+    # the cost of reliability.  Messages can get lost if a client dies
+    # before it can deliver them to the application.
+    #
+    # * :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.
+    #
+    def pop opts = {}, &blk
+      if blk
+        @on_pop = blk
+        @on_pop_opts = opts
+      end
+
+      @mq.callback{
+        @mq.get_queue{ |q|
+          q.push(self)
+          @mq.send Protocol::Basic::Get.new({ :queue => name,
+                                              :consumer_tag => name,
+                                              :no_ack => !opts[:ack],
+                                              :nowait => true }.merge(opts))
+        }
+      }
+
+      self
+    end
+
+    # Subscribes to asynchronous message delivery.
+    #
+    # The provided block is passed a single message each time the
+    # exchange matches a message to this queue.
+    #
+    #  EM.run do
+    #    exchange = MQ.direct("foo queue")
+    #    EM.add_periodic_timer(1) do
+    #      exchange.publish("random number #{rand(1000)}")
+    #    end
+    #    
+    #    queue = MQ.queue('foo queue')
+    #    queue.subscribe { |body| puts "received payload [#{body}]" }
+    #  end
+    #
+    # If the block takes 2 parameters, both the +header+ and the +body+ will
+    # be passed in for processing. The header object is defined by
+    # AMQP::Protocol::Header.
+    #
+    #  EM.run do
+    #    exchange = MQ.direct("foo queue")
+    #    EM.add_periodic_timer(1) do
+    #      exchange.publish("random number #{rand(1000)}")
+    #    end
+    #    
+    #    # note that #bind is never called; it is implicit because
+    #    # the exchange and queue names match
+    #    queue = MQ.queue('foo queue')
+    #    queue.subscribe do |header, body| 
+    #      p header
+    #      puts "received payload [#{body}]"
+    #    end
+    #  end
+    #
+    # == Options
+    # * :ack => true | false (default false)
+    # If this field is set to false the server does not expect acknowledgments
+    # for messages.  That is, when a message is delivered to the client
+    # the server automatically and silently acknowledges it on behalf
+    # of the client.  This functionality increases performance but at
+    # the cost of reliability.  Messages can get lost if a client dies
+    # before it can deliver them to the application.
+    #
+    # * :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.
+    #
+    # * :confirm => proc (default nil)
+    # If set, this proc will be called when the server confirms subscription
+    # to the queue with a ConsumeOk message. Setting this option will
+    # automatically set :nowait => false. This is required for the server
+    # to send a confirmation.
+    #
+    def subscribe opts = {}, &blk
+      @consumer_tag = "#{name}-#{Kernel.rand(999_999_999_999)}"
+      @mq.consumers[@consumer_tag] = self
+
+      raise Error, 'already subscribed to the queue' if subscribed?
+
+      @on_msg = blk
+      @on_msg_opts = opts
+      opts[:nowait] = false if (@on_confirm_subscribe = opts[:confirm])
+
+      @mq.callback{
+        @mq.send Protocol::Basic::Consume.new({ :queue => name,
+                                                :consumer_tag => @consumer_tag,
+                                                :no_ack => !opts[:ack],
+                                                :nowait => true }.merge(opts))
+      }
+      self
+    end
+
+    # Removes the subscription from the queue and cancels the consumer.
+    # New messages will not be received by the queue. This call is similar
+    # in result to calling #unbind.
+    #
+    # Due to the asynchronous nature of the protocol, it is possible for
+    # "in flight" messages to be received after this call completes.
+    # Those messages will be serviced by the last block used in a
+    # #subscribe or #pop call.
+    #
+    # Additionally, if the queue was created with _autodelete_ set to 
+    # true, the server will delete the queue after its wait period
+    # has expired unless the queue is bound to an active exchange.
+    #
+    # The method accepts a block which will be executed when the 
+    # unsubscription request is acknowledged as complete by the server.
+    #
+    # * :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.
+    #
+    def unsubscribe opts = {}, &blk
+      @on_cancel = blk
+      @mq.callback{
+        @mq.send Protocol::Basic::Cancel.new({ :consumer_tag => @consumer_tag }.merge(opts))
+      }
+      self
+    end
+
+    def publish data, opts = {}
+      exchange.publish(data, opts)
+    end
+    
+    # Boolean check to see if the current queue has already been subscribed
+    # to an exchange. 
+    #
+    # Attempts to #subscribe multiple times to any exchange will raise an
+    # Exception. Only a single block at a time can be associated with any 
+    # one queue for processing incoming messages.
+    #
+    def subscribed?
+      !!@on_msg
+    end
+
+    # Passes the message to the block passed to pop or subscribe. 
+    #
+    # Performs an arity check on the block's parameters. If arity == 1, 
+    # pass only the message body. If arity != 1, pass the headers and
+    # the body to the block.
+    #
+    # See AMQP::Protocol::Header for the hash properties available from
+    # the headers parameter. See #pop or #subscribe for a code example.
+    #
+    def receive headers, body
+      headers = MQ::Header.new(@mq, headers)
+
+      if cb = (@on_msg || @on_pop)
+        cb.call *(cb.arity == 1 ? [body] : [headers, body])
+      end
+    end
+
+    # Get the number of messages and consumers on a queue.
+    #
+    #  MQ.queue('name').status{ |num_messages, num_consumers|
+    #   puts num_messages
+    #  }
+    #
+    def status opts = {}, &blk
+      @on_status = blk
+      @mq.callback{
+        @mq.send Protocol::Queue::Declare.new({ :queue => name,
+                                                :passive => true }.merge(opts))
+      }
+      self
+    end
+
+    def receive_status declare_ok
+      if @on_status
+        m, c = declare_ok.message_count, declare_ok.consumer_count
+        @on_status.call *(@on_status.arity == 1 ? [m] : [m, c])
+        @on_status = nil
+      end
+    end
+
+    def confirm_subscribe
+      @on_confirm_subscribe.call if @on_confirm_subscribe
+      @on_confirm_subscribe = nil
+    end
+
+    def cancelled
+      @on_cancel.call if @on_cancel
+      @on_cancel = @on_msg = nil
+      @mq.consumers.delete @consumer_tag
+      @consumer_tag = nil
+    end
+
+    def reset
+      @deferred_status = nil
+      initialize @mq, @name, @opts
+
+      binds = @bindings
+      @bindings = {}
+      binds.each{|ex,opts| bind(ex, opts) }
+
+      if blk = @on_msg
+        @on_msg = nil
+        subscribe @on_msg_opts, &blk
+      end
+
+      if @on_pop
+        pop @on_pop_opts, &@on_pop
+      end
+    end
+  
+    private
+    
+    def exchange
+      @exchange ||= Exchange.new(@mq, :direct, '', :key => name)
+    end
+  end
+end