tmm1-amqp 0.5.9 → 0.6.0

data/examples/mq/simple-ack.rb

@@ -0,0 +1,46 @@
+$:.unshift File.dirname(__FILE__) + '/../../lib'
+require 'mq'
+require 'pp'
+
+# For ack to work appropriatly you must shutdown AMQP gracefully,
+# otherwise all items in your queue will be returned
+Signal.trap('INT') { AMQP.stop{ EM.stop } }
+Signal.trap('TERM'){ AMQP.stop{ EM.stop } }
+
+EM.run do
+  MQ.queue('awesome').publish('Totally rad 1')
+  MQ.queue('awesome').publish('Totally rad 2')
+  MQ.queue('awesome').publish('Totally rad 3')
+
+  i = 0
+
+  # Stopping after the second item was acked will keep the 3rd item in the queue
+  MQ.queue('awesome').subscribe(:ack => true) do |h,m|
+    if (i+=1) == 3
+      puts 'Shutting down...'
+      AMQP.stop{ EM.stop }
+    end
+
+    if AMQP.closing?
+      puts "#{m} (ignored, redelivered later)"
+    else
+      puts m
+      h.ack
+    end
+  end
+end
+
+__END__
+
+Totally rad 1
+Totally rad 2
+Shutting down...
+Totally rad 3 (ignored, redelivered later)
+
+When restarted:
+
+Totally rad 3
+Totally rad 1
+Shutting down...
+Totally rad 2 (ignored, redelivered later)
+Totally rad 3 (ignored, redelivered later)

data/examples/mq/simple-get.rb

@@ -0,0 +1,43 @@
+$:.unshift File.dirname(__FILE__) + '/../../lib'
+require 'mq'
+require 'pp'
+
+Signal.trap('INT') { AMQP.stop{ EM.stop } }
+Signal.trap('TERM'){ AMQP.stop{ EM.stop } }
+
+AMQP.start do
+  queue = MQ.queue('awesome')
+
+  queue.publish('Totally rad 1')
+  queue.publish('Totally rad 2')
+  EM.add_timer(5){ queue.publish('Totally rad 3') }
+
+  queue.pop{ |msg|
+    unless msg
+      # queue was empty
+      p [Time.now, :queue_empty!]
+
+      # try again in 1 second
+      EM.add_timer(1){ queue.pop }
+    else
+      # process this message
+      p [Time.now, msg]
+
+      # get the next message in the queue
+      queue.pop
+    end
+  }
+end
+
+__END__
+
+[Wed Oct 15 15:24:30 -0700 2008, "Totally rad 1"]
+[Wed Oct 15 15:24:30 -0700 2008, "Totally rad 2"]
+[Wed Oct 15 15:24:30 -0700 2008, :queue_empty!]
+[Wed Oct 15 15:24:31 -0700 2008, :queue_empty!]
+[Wed Oct 15 15:24:32 -0700 2008, :queue_empty!]
+[Wed Oct 15 15:24:33 -0700 2008, :queue_empty!]
+[Wed Oct 15 15:24:34 -0700 2008, :queue_empty!]
+[Wed Oct 15 15:24:35 -0700 2008, "Totally rad 3"]
+[Wed Oct 15 15:24:35 -0700 2008, :queue_empty!]
+[Wed Oct 15 15:24:36 -0700 2008, :queue_empty!]

data/examples/mq/simple.rb

@@ -5,7 +5,7 @@ require 'pp'
 EM.run do
 
   # connect to the amqp server
-  connection = AMQP.connect(:host => 'dev.rabbitmq.com', :logging => false)
+  connection = AMQP.connect(:host => 'localhost', :logging => false)
   
   # open a channel on the AMQP connection
   channel = MQ.new(connection)

data/lib/amqp.rb

@@ -15,6 +15,7 @@ module AMQP
     @logging = false
     attr_accessor :logging
     attr_reader :conn, :closing
+    alias :closing? :closing
     alias :connection :conn
   end
 
@@ -41,6 +42,41 @@ module AMQP
     }
   end
 
+  # Must be called to startup the connection to the AMQP server.
+  #
+  # The method takes several arguments and an optional block.
+  #
+  # This takes any option that is also accepted by EventMachine::connect.
+  # Additionally, there are several AMQP-specific options.
+  #
+  # * :user => String (default 'guest')
+  # The username as defined by the AMQP server.
+  # * :pass => String (default 'guest')
+  # The password for the associated :user as defined by the AMQP server.
+  # * :vhost => String (default '/')
+  # The virtual host as defined by the AMQP server.
+  # * :timeout => Numeric (default nil)
+  # Measured in seconds.
+  # * :logging => true | false (default false)
+  # Toggle the extremely verbose logging of all protocol communications
+  # between the client and the server. Extremely useful for debugging.
+  #
+  #  AMQP.start do
+  #    # default is to connect to localhost:5672
+  #
+  #    # define queues, exchanges and bindings here.
+  #    # also define all subscriptions and/or publishers
+  #    # here.
+  #
+  #    # this block never exits unless EM.stop_event_loop
+  #    # is called.
+  #  end
+  #
+  # Most code will use the MQ api. Any calls to MQ.direct / MQ.fanout /
+  # MQ.topic / MQ.queue will implicitly call #start. In those cases,
+  # it is sufficient to put your code inside of an EventMachine.run
+  # block. See the code examples in MQ for details.
+  #
   def self.start *args, &blk
     EM.run{
       @conn ||= connect *args
@@ -54,13 +90,13 @@ module AMQP
   end
   
   def self.stop
-    if @conn
-      puts "Shutting down..."
+    if @conn and not @closing
       @closing = true
       @conn.close{
         yield if block_given?
         @conn = nil
+        @closing = false
       }
     end
   end
-end
+end

data/lib/amqp/buffer.rb

@@ -1,5 +1,5 @@
 if [].map.respond_to? :with_index
-  class Array
+  class Array #:nodoc:
     def enum_with_index
       each.with_index
     end
@@ -9,7 +9,7 @@ else
 end
 
 module AMQP
-  class Buffer
+  class Buffer #:nodoc: all
     class Overflow < StandardError; end
     class InvalidType < StandardError; end
     

data/lib/amqp/client.rb

@@ -36,7 +36,8 @@ module AMQP
           succeed(self)
 
         when Protocol::Connection::Close
-          raise Error, "#{method.reply_text} in #{Protocol.classes[method.class_id].methods[method.method_id]}"
+          # raise Error, "#{method.reply_text} in #{Protocol.classes[method.class_id].methods[method.method_id]}"
+          STDERR.puts "#{method.reply_text} in #{Protocol.classes[method.class_id].methods[method.method_id]}"
 
         when Protocol::Connection::CloseOk
           @on_disconnect.call if @on_disconnect
@@ -61,7 +62,7 @@ module AMQP
       @settings = opts
       extend AMQP.client
 
-      @on_disconnect = proc{ raise Error, "Could not connect to server #{opts[:host]}:#{opts[:port]}" }
+      @on_disconnect ||= proc{ raise Error, "Could not connect to server #{opts[:host]}:#{opts[:port]}" }
 
       timeout @settings[:timeout] if @settings[:timeout]
       errback{ @on_disconnect.call }
@@ -69,7 +70,11 @@ module AMQP
 
     def connection_completed
       log 'connected'
-      @on_disconnect = proc{ raise Error, 'Disconnected from server' }
+      # @on_disconnect = proc{ raise Error, 'Disconnected from server' }
+      unless @closing
+        @on_disconnect = method(:reconnect)
+        @reconnecting = false
+      end
       @buf = Buffer.new
       send_data HEADER
       send_data [1, 1, VERSION_MAJOR, VERSION_MINOR].pack('C4')
@@ -115,13 +120,21 @@ module AMQP
       send_data data.to_s
     end
 
+    #:stopdoc:
     # def send_data data
     #   log 'send_data', data
     #   super
     # end
+    #:startdoc:
 
     def close &on_disconnect
-      @on_disconnect = on_disconnect if on_disconnect
+      if on_disconnect
+        @closing = true
+        @on_disconnect = proc{
+          on_disconnect.call
+          @closing = false
+        }
+      end
 
       callback{ |c|
         if c.channels.any?
@@ -136,7 +149,29 @@ module AMQP
         end
       }
     end
-  
+
+    def reconnect force = false
+      if @reconnecting and not force
+        # wait 1 second after first reconnect attempt, in between each subsequent attempt
+        EM.add_timer(1){ reconnect(true) }
+        return
+      end
+
+      unless @reconnecting
+        @deferred_status = nil
+        initialize(@settings)
+
+        mqs = @channels
+        @channels = {}
+        mqs.each{ |_,mq| mq.reset } if mqs
+
+        @reconnecting = true
+      end
+
+      log 'reconnecting'
+      EM.reconnect @settings[:host], @settings[:port], self
+    end
+
     def self.connect opts = {}
       opts = AMQP.settings.merge(opts)
       EM.connect opts[:host], opts[:port], self, opts

data/lib/amqp/frame.rb

@@ -3,7 +3,7 @@ require 'amqp/buffer'
 require 'amqp/protocol'
 
 module AMQP
-  class Frame
+  class Frame #:nodoc: all
     def initialize payload = nil, channel = 0
       @channel, @payload = channel, payload
     end

data/lib/amqp/protocol.rb

@@ -3,6 +3,7 @@ require 'amqp/buffer'
 
 module AMQP
   module Protocol
+    #:stopdoc:
     class Class::Method
       def initialize *args
         opts = args.pop if args.last.is_a? Hash
@@ -64,6 +65,29 @@ module AMQP
       end
     end
 
+    #:startdoc:
+    #
+    # Contains a properties hash that holds some potentially interesting 
+    # information.
+    # * :delivery_mode
+    # 1 equals transient.
+    # 2 equals persistent. Unconsumed persistent messages will survive
+    # a server restart when they are stored in a durable queue.
+    # * :redelivered
+    # True or False
+    # * :routing_key
+    # The routing string used for matching this message to this queue.
+    # * :priority
+    # An integer in the range of 0 to 9 inclusive.
+    # * :content_type
+    # Always "application/octet-stream" (byte stream)
+    # * :exchange
+    # The source exchange which published this message.
+    # * :message_count
+    # The number of unconsumed messages contained in the queue.
+    # * :delivery_tag
+    # A monotonically increasing integer. This number should not be trusted
+    # as a sequence number. There is no guarantee it won't get reset.
     class Header
       def initialize *args
         opts = args.pop if args.last.is_a? Hash
@@ -132,6 +156,7 @@ module AMQP
       class_id, method_id = buf.read(:short, :short)
       classes[class_id].methods[method_id].new(buf)
     end
+    #:stopdoc:
   end
 end
 

data/lib/amqp/spec.rb

@@ -1,6 +1,7 @@
 
-# this file was autogenerated on Fri Aug 01 15:08:30 -0700 2008
-# using amqp-0.8.json    (mtime: Fri Aug 01 15:08:22 -0700 2008)
+#:stopdoc:
+# this file was autogenerated on Sat Jan 03 14:05:57 -0600 2009
+# using amqp-0.8.json    (mtime: Sat Jan 03 08:58:13 -0600 2009)
 #
 # DO NOT EDIT! (edit protocol/codegen.rb instead, and run `rake codegen`)
 

data/lib/ext/blankslate.rb

@@ -1,7 +1,7 @@
 unless defined?(BlankSlate)
   class BlankSlate < BasicObject; end if defined?(BasicObject)
 
-  class BlankSlate
+  class BlankSlate #:nodoc:
     instance_methods.each { |m| undef_method m unless m =~ /^__/ }
   end
 end

data/lib/ext/em.rb

@@ -5,6 +5,8 @@ rescue LoadError
   require 'eventmachine'
 end
 
+#:stopdoc:
+
 if EM::VERSION < '0.12.2'
     
   def EventMachine::run blk=nil, tail=nil, &block

data/lib/ext/emfork.rb

@@ -6,6 +6,8 @@ end
 
 require 'eventmachine'
 
+#:stopdoc:
+
 # helper to fork off EM reactors
 def EM.fork num = 1, &blk
   unless @forks

data/lib/mq.rb

@@ -1,8 +1,11 @@
+#:main: README
+#
+
 $:.unshift File.expand_path(File.dirname(File.expand_path(__FILE__)))
 require 'amqp'
 
 class MQ
-  %w[ exchange queue rpc ].each do |file|
+  %w[ exchange queue rpc header ].each do |file|
     require "mq/#{file}"
   end
 
@@ -11,13 +14,127 @@ class MQ
     attr_accessor :logging
   end
 
+  # Raised whenever an illegal operation is attempted.
   class Error < StandardError; end
 end
 
+# The top-level class for building AMQP clients. This class contains several
+# convenience methods for working with queues and exchanges. Many calls
+# delegate/forward to subclasses, but this is the preferred API. The subclass
+# API is subject to change while this high-level API will likely remain
+# unchanged as the library evolves. All code examples will be written using
+# the MQ API.
+#
+# Below is a somewhat complex example that demonstrates several capabilities
+# of the library. The example starts a clock using a +fanout+ exchange which
+# is used for 1 to many communications. Each consumer generates a queue to
+# receive messages and do some operation (in this case, print the time).
+# One consumer prints messages every second while the second consumer prints
+# messages every 2 seconds. After 5 seconds has elapsed, the 1 second
+# consumer is deleted.
+# 
+# Of interest is the relationship of EventMachine to the process. All MQ
+# operations must occur within the context of an EM.run block. We start
+# EventMachine in its own thread with an empty block; all subsequent calls
+# to the MQ API add their blocks to the EM.run block. This demonstrates how
+# the library could be used to build up and tear down communications outside
+# the context of an EventMachine block and/or integrate the library with
+# other synchronous operations. See the EventMachine documentation for
+# more information.
+#
+#   require 'rubygems'
+#   require 'mq'
+#  
+#   thr = Thread.new { EM.run }
+#  
+#   # turns on extreme logging
+#   #AMQP.logging = true
+#  
+#   def log *args
+#     p args
+#   end
+#  
+#   def publisher
+#     clock = MQ.fanout('clock')
+#     EM.add_periodic_timer(1) do
+#       puts
+#  
+#       log :publishing, time = Time.now
+#       clock.publish(Marshal.dump(time))
+#     end
+#   end
+#  
+#   def one_second_consumer
+#     MQ.queue('every second').bind(MQ.fanout('clock')).subscribe do |time|
+#       log 'every second', :received, Marshal.load(time)
+#     end
+#   end
+#  
+#   def two_second_consumer
+#     MQ.queue('every 2 seconds').bind('clock').subscribe do |time|
+#       time = Marshal.load(time)
+#       log 'every 2 seconds', :received, time if time.sec % 2 == 0
+#     end
+#   end
+#  
+#   def delete_one_second
+#     EM.add_timer(5) do
+#       # delete the 'every second' queue
+#       log 'Deleting [every second] queue'
+#       MQ.queue('every second').delete
+#     end
+#   end
+#  
+#   publisher
+#   one_second_consumer
+#   two_second_consumer
+#   delete_one_second
+#   thr.join
+#  
+#  __END__
+#  
+#  [:publishing, Tue Jan 06 22:46:14 -0600 2009]
+#  ["every second", :received, Tue Jan 06 22:46:14 -0600 2009]
+#  ["every 2 seconds", :received, Tue Jan 06 22:46:14 -0600 2009]
+#  
+#  [:publishing, Tue Jan 06 22:46:16 -0600 2009]
+#  ["every second", :received, Tue Jan 06 22:46:16 -0600 2009]
+#  ["every 2 seconds", :received, Tue Jan 06 22:46:16 -0600 2009]
+#  
+#  [:publishing, Tue Jan 06 22:46:17 -0600 2009]
+#  ["every second", :received, Tue Jan 06 22:46:17 -0600 2009]
+#  
+#  [:publishing, Tue Jan 06 22:46:18 -0600 2009]
+#  ["every second", :received, Tue Jan 06 22:46:18 -0600 2009]
+#  ["every 2 seconds", :received, Tue Jan 06 22:46:18 -0600 2009]
+#  ["Deleting [every second] queue"]
+#  
+#  [:publishing, Tue Jan 06 22:46:19 -0600 2009]
+#  
+#  [:publishing, Tue Jan 06 22:46:20 -0600 2009]
+#  ["every 2 seconds", :received, Tue Jan 06 22:46:20 -0600 2009]
+#
 class MQ
   include AMQP
   include EM::Deferrable
 
+  # Returns a new channel. A channel is a bidirectional virtual
+  # connection between the client and the AMQP server. Elsewhere in the
+  # library the channel is referred to in parameter lists as +mq+.
+  #
+  # Optionally takes the result from calling AMQP::connect.
+  #
+  # Rarely called directly by client code. This is implicitly called
+  # by most instance methods. See #method_missing.
+  #
+  #  EM.run do
+  #    channel = MQ.new
+  #  end
+  #
+  #  EM.run do
+  #    channel = MQ.new AMQP::connect
+  #  end
+  #
   def initialize connection = nil
     raise 'MQ can only be used from within EM.run{}' unless EM.reactor_running?
 
@@ -30,6 +147,15 @@ class MQ
   end
   attr_reader :channel
   
+  # May raise a MQ::Error exception when the frame payload contains a
+  # Protocol::Channel::Close object. 
+  #
+  # This usually occurs when a client attempts to perform an illegal
+  # operation. A short, and incomplete, list of potential illegal operations
+  # follows:
+  # * publish a message to a deleted exchange (NOT_FOUND)
+  # * declare an exchange using the reserved 'amq.' naming structure (ACCESS_REFUSED)
+  #
   def process_frame frame
     log :received, frame
 
@@ -117,18 +243,387 @@ class MQ
     }
   end
 
-  %w[ direct topic fanout ].each do |type|
-    class_eval %[
-      def #{type} name = 'amq.#{type}', opts = {}
-        exchanges[name] ||= Exchange.new(self, :#{type}, name, opts)
-      end
-    ]
+  # Defines, intializes and returns an Exchange to act as an ingress
+  # point for all published messages.
+  #
+  # == 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.
+  # Allocating this exchange without a name _or_ with the empty string
+  # will use the internal 'amq.direct' exchange.
+  #
+  # Any published message, regardless of its persistence setting, is thrown
+  # away by the exchange when there are no queues bound to it.
+  #
+  #  # exchange is named 'foo'
+  #  exchange = MQ.direct('foo')
+  #
+  #  # or, the exchange can use the default name (amq.direct) and perform
+  #  # routing comparisons using the :key
+  #  exchange = MQ.direct("", :key => 'foo')
+  #  exchange.publish('some data') # will be delivered to queue bound to 'foo'
+  #
+  #  queue = MQ.queue('foo')
+  #  # can receive data since the queue name and the exchange key match exactly
+  #  queue.pop { |data| puts "received data [#{data}]" }
+  #
+  # == 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. The
+  # exchange and all bindings will be lost on a server restart.
+  # It makes no sense to publish a persistent message to a transient
+  # exchange.
+  #
+  # Durable exchanges and their bindings are recreated upon a server 
+  # restart. Any published messages not routed to a bound queue are lost.
+  #
+  # * :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 direct name = 'amq.direct', opts = {}
+    exchanges[name] ||= Exchange.new(self, :direct, name, opts)
+  end
+
+  # Defines, intializes and returns an Exchange to act as an ingress
+  # point for all published messages.
+  #
+  # == 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.
+  #
+  # Any published message, regardless of its persistence setting, is thrown
+  # away by the exchange when there are no queues bound to it.
+  #
+  # 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.
+  # Allocating this exchange without a name _or_ with the empty string
+  # will use the internal 'amq.fanout' exchange.
+  #
+  #  EM.run do
+  #    clock = MQ.fanout('clock')
+  #    EM.add_periodic_timer(1) do
+  #      puts "\npublishing #{time = Time.now}"
+  #      clock.publish(Marshal.dump(time))
+  #    end
+  #
+  #    amq = MQ.queue('every second')
+  #    amq.bind(MQ.fanout('clock')).subscribe do |time|
+  #      puts "every second received #{Marshal.load(time)}"
+  #    end
+  #
+  #    # 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
+  #
+  # == 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. The
+  # exchange and all bindings will be lost on a server restart.
+  # It makes no sense to publish a persistent message to a transient
+  # exchange.
+  #
+  # Durable exchanges and their bindings are recreated upon a server 
+  # restart. Any published messages not routed to a bound queue are lost.
+  #
+  # * :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 fanout name = 'amq.fanout', opts = {}
+    exchanges[name] ||= Exchange.new(self, :fanout, name, opts)
   end
 
+  # Defines, intializes and returns an Exchange to act as an ingress
+  # point for all published messages.
+  #
+  # == 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+ hash key for all
+  # cases.
+  #
+  # Any published message, regardless of its persistence setting, is thrown
+  # away by the exchange when there are no queues bound to it.
+  #
+  # As part of the AMQP standard, each server _should_ predeclare a topic 
+  # exchange called 'amq.topic' (this is not required by the standard).
+  # Allocating this exchange without a name _or_ with the empty string
+  # will use the internal 'amq.topic' exchange.
+  #
+  # 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.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. The
+  # exchange and all bindings will be lost on a server restart.
+  # It makes no sense to publish a persistent message to a transient
+  # exchange.
+  #
+  # Durable exchanges and their bindings are recreated upon a server 
+  # restart. Any published messages not routed to a bound queue are lost.
+  #
+  # * :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 topic name = 'amq.topic', opts = {}
+    exchanges[name] ||= Exchange.new(self, :topic, name, opts)
+  end
+    
+  # 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).
+  #
+  # It is not supported to create a queue without a name; some string
+  # (even the empty string) must be passed in the +name+ parameter.
+  #
+  # == 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).
+  #
+  # Again, note the durability property on a queue has no influence on
+  # the persistence of published messages. A durable queue containing
+  # transient messages will flush those messages on a restart.
+  #
+  # 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.
+  #
+  # Any remaining messages in the queue will be purged when the queue
+  # is deleted regardless of the message's persistence setting.
+  #
+  # * :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 queue name, opts = {}
     queues[name] ||= Queue.new(self, name, opts)
   end
 
+  # 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
+  # Marshal[http://ruby-doc.org/core/classes/Marshal.html] 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.
+  #
+  #  EM.run do
+  #    server = MQ.rpc('hash table node', Hash)
+  #
+  #    client = MQ.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
+  #
   def rpc name, obj = nil
     rpcs[name] ||= RPC.new(self, name, obj)
   end
@@ -144,8 +639,8 @@ class MQ
     end
   end
 
-  # error callback
-
+  # Define a message and callback block to be executed on all
+  # errors.
   def self.error msg = nil, &blk
     if blk
       @error_callback = blk
@@ -154,12 +649,16 @@ class MQ
     end
   end
 
-  # keep track of proxy objects
-  
+  # Returns a hash of all the exchange proxy objects.
+  #
+  # Not typically called by client code.
   def exchanges
     @exchanges ||= {}
   end
 
+  # Returns a hash of all the queue proxy objects.
+  #
+  # Not typically called by client code.
   def queues
     @queues ||= {}
   end
@@ -172,18 +671,38 @@ class MQ
     end
   end
 
+  # Returns a hash of all rpc proxy objects.
+  #
+  # Not typically called by client code.
   def rpcs
     @rcps ||= {}
   end
 
-  # queue objects keyed on their consumer tags
-
+  # Queue objects keyed on their consumer tags.
+  #
+  # Not typically called by client code.
   def consumers
     @consumers ||= {}
   end
 
+  def reset
+    @deferred_status = nil
+    @channel = nil
+    initialize @connection
+
+    @consumers = {}
+
+    exs = @exchanges
+    @exchanges = {}
+    exs.each{ |_,e| e.reset } if exs
+
+    qus = @queues
+    @queues = {}
+    qus.each{ |_,q| q.reset } if qus
+  end
+
   private
-  
+
   def log *args
     return unless MQ.logging
     pp args
@@ -194,21 +713,23 @@ class MQ
   alias :conn :connection
 end
 
-# convenience wrapper (read: HACK) for thread-local MQ object
+#-- convenience wrapper (read: HACK) for thread-local MQ object
 
 class MQ
   def MQ.default
-    # XXX clear this when connection is closed
+    #-- XXX clear this when connection is closed
     Thread.current[:mq] ||= MQ.new
   end
 
+  # Allows for calls to all MQ instance methods. This implicitly calls
+  # MQ.new so that a new channel is allocated for subsequent operations.
   def MQ.method_missing meth, *args, &blk
     MQ.default.__send__(meth, *args, &blk)
   end
 end
 
-# unique identifier
 class MQ
+  # unique identifier
   def MQ.id
     Thread.current[:mq_id] ||= "#{`hostname`.strip}-#{Process.pid}-#{Thread.current.object_id}"
   end