amqp 0.8.0.rc13 → 0.8.0.rc14

data/lib/amqp/int_allocator.rb

@@ -0,0 +1,96 @@
+# encoding: utf-8
+
+require "amqp/bit_set"
+
+module AMQP
+  # Simple bitset-based integer allocator, heavily inspired by com.rabbitmq.utility.IntAllocator class
+  # in the RabbitMQ Java client.
+  #
+  # Unlike monotonically incrementing identifier, this allocator is suitable for very long running programs
+  # that aggressively allocate and release channels.
+  class IntAllocator
+
+    #
+    # API
+    #
+
+    # @return [Integer] Number of integers in the allocation range
+    attr_reader :number_of_bits
+    # @return [Integer] Upper boundary of the integer range available for allocation
+    attr_reader :hi
+    # @return [Integer] Lower boundary of the integer range available for allocation
+    attr_reader :lo
+
+    # @param [Integer] lo    Lower boundary of the integer range available for allocation
+    # @param [Integer] hi    Upper boundary of the integer range available for allocation
+    # @raise [ArgumentError] if upper boundary is not greater than the lower one
+    def initialize(lo, hi)
+      raise ArgumentError.new "upper boundary must be greater than the lower one (given: hi = #{hi}, lo = #{lo})" unless hi > lo
+
+      @hi = hi
+      @lo = lo
+
+      @number_of_bits = hi - lo
+      @range          = Range.new(1, @number_of_bits)
+      @free_set       = BitSet.new(@number_of_bits)
+    end # initialize(hi, lo)
+
+    # Attempts to allocate next available integer. If allocation succeeds, allocated value is returned.
+    # Otherwise, nil is returned.
+    #
+    # Current implementation of this method is O(n), where n is number of bits in the range available for
+    # allocation.
+    #
+    # @return [Integer] Allocated integer if allocation succeeded. nil otherwise.
+    def allocate
+      if n = find_unallocated_position
+        @free_set.set(n)
+
+        n
+      else
+        -1
+      end
+    end # allocate
+
+    # Releases previously allocated integer. If integer provided as argument was not previously allocated,
+    # this method has no effect.
+    #
+    # @return [NilClass] nil
+    def free(reservation)
+      @free_set.unset(reservation)
+    end # free(reservation)
+    alias release free
+
+    # @return [Boolean] true if provided argument was previously allocated, false otherwise
+    def allocated?(reservation)
+      @free_set.get(reservation)
+    end # allocated?(reservation)
+
+    # Releases the whole allocation range
+    def reset
+      @free_set.clear
+    end # reset
+
+
+
+    protected
+
+    # This implementation is significantly less efficient
+    # that what the RabbitMQ Java client has (based on java.lang.Long#nextSetBit and
+    # java.lang.Long.numberOfTrailingZeros, and thus binary search over bits).
+    # But for channel id generation, this is a good enough implementation.
+    #
+    # @private
+    def find_unallocated_position
+      r = nil
+      @range.each do |i|
+        if !@free_set.get(i)
+          r = i
+          break;
+        end
+      end
+
+      r
+    end # find_unallocated_position
+  end # IntAllocator
+end # AMQP

data/lib/amqp/logger.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 $stdout.puts <<-MESSAGE
 -------------------------------------------------------------------------------------
 DEPRECATION WARNING!

data/lib/amqp/queue.rb

@@ -1,6 +1,7 @@
 # encoding: utf-8
 
 require "amq/client/queue"
+require "amqp/consumer"
 
 module AMQP
   # h2. What are AMQP queues?
@@ -173,15 +174,12 @@ module AMQP
       raise ArgumentError.new("queue name must not be nil; if you want broker to generate queue name for you, pass an empty string") if name.nil?
 
       @channel  = channel
-      name      = AMQ::Protocol::EMPTY_STRING if name.nil?
       @name     = name unless name.empty?
       @server_named = name.empty?
       @opts         = self.class.add_default_options(name, opts, block)
 
       raise ArgumentError.new("server-named queues (name = '') declaration with :nowait => true makes no sense. If you are not sure what that means, simply drop :nowait => true from opts.") if @server_named && @opts[:nowait]
 
-      @bindings     = Hash.new
-
       # a deferrable that we use to delay operations until this queue is actually declared.
       # one reason for this is to support a case when a server-named queue is immediately bound.
       # it's crazy, but 0.7.x supports it, so... MK.
@@ -218,6 +216,15 @@ module AMQP
       end
     end
 
+    # Defines a callback that will be executed once queue is declared. More than one callback can be defined.
+    # if queue is already declared, given callback is executed immediately.
+    #
+    # @api public
+    def once_declared(&block)
+      @declaration_deferrable.callback(&block)
+    end # once_declared(&block)
+
+
     # @return [Boolean] true if this queue is server-named
     def server_named?
       @server_named
@@ -274,12 +281,6 @@ module AMQP
     # @api public
     # @see Queue#unbind
     def bind(exchange, opts = {}, &block)
-      @status             = :unbound
-      # amq-client's Queue already does exchange.respond_to?(:name) ? exchange.name : exchange
-      # for us
-      exchange            = exchange
-      @bindings[exchange] = opts
-
       if self.server_named?
         @channel.once_open do
           @declaration_deferrable.callback do
@@ -296,6 +297,44 @@ module AMQP
     end
 
 
+    # @group Error Handling and Recovery
+
+    # Used by automatic recovery machinery.
+    # @private
+    # @api plugin
+    def rebind(&block)
+      @bindings.each { |b| self.bind(b[:exchange], b) }
+    end
+
+    # Called by associated connection object when AMQP connection has been re-established
+    # (for example, after a network failure).
+    #
+    # @api plugin
+    def auto_recover
+      self.exec_callback_yielding_self(:before_recovery)
+
+      if self.server_named?
+        old_name = @name.dup
+        @name    = AMQ::Protocol::EMPTY_STRING
+
+        @channel.queues.delete(old_name)
+      end
+
+      self.redeclare do
+        @declaration_deferrable.succeed
+        self.rebind
+
+        @consumers.each { |tag, consumer| consumer.auto_recover }
+
+        self.exec_callback_yielding_self(:after_recovery)
+      end
+    end # auto_recover
+
+    # @endgroup
+
+
+
+
     # Remove the binding between the queue and exchange. The queue will
     # not receive any more messages until it is bound to another
     # exchange.
@@ -390,44 +429,18 @@ module AMQP
     # application where synchronous functionality is more important than
     # performance.
     #
-    # If provided block takes one argument, it is passed message payload every time {Queue#pop} is called.
+    # If queue is empty, `payload` callback argument will be nil, otherwise arguments
+    # are identical to those of {AMQP::Queue#subscribe} callback.
     #
-    # @example Use of callback with a single argument
+    # @example Fetching messages off AMQP queue on demand
     #
-    #  EM.run do
-    #    exchange = AMQP::Channel.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 = AMQP::Channel.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.
-    #
-    # @example Use of callback with two arguments
-    #
-    #  EM.run do
-    #    exchange = AMQP::Channel.direct("foo queue")
-    #    EM.add_periodic_timer(1) do
-    #      exchange.publish("random number #{rand(1000)}")
-    #    end
-    #
-    #    queue = AMQP::Channel.queue('foo queue')
-    #    queue.pop do |header, body|
-    #      p header
-    #      puts "received payload [#{body}]"
-    #    end
-    #
-    #    EM.add_periodic_timer(1) { queue.pop }
-    #  end
+    #   queue.pop do |metadata, payload|
+    #     if payload
+    #       puts "Fetched a message: #{payload.inspect}, content_type: #{metadata.content_type}. Shutting down..."
+    #     else
+    #       puts "No messages in the queue"
+    #     end
+    #   end
     #
     # @option opts [Boolean] :ack (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
@@ -479,6 +492,12 @@ module AMQP
     # exchange matches a message to this queue.
     #
     #
+    # Attempts to {Queue#subscribe} multiple times to the same exchange will raise an
+    # Exception. If you need more than one consumer per queue, use {AMQP::Consumer} instead.
+    # {file:docs/Queues.textile Documentation guide on queues} explains this and other topics
+    # in great detail.
+    #
+    #
     # @example Use of callback with a single argument
     #
     #  EventMachine.run do
@@ -492,8 +511,7 @@ module AMQP
     #  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.
+    # be passed in for processing.
     #
     # @example Use of callback with two arguments
     #
@@ -548,6 +566,120 @@ module AMQP
     #                     :timestamp   => Time.now.to_i)
     #  end
     #
+    # @example Using object as consumer (message handler), take one
+    #
+    #   class Consumer
+    #
+    #     #
+    #     # API
+    #     #
+    #
+    #     def initialize(channel, queue_name = AMQ::Protocol::EMPTY_STRING)
+    #       @queue_name = queue_name
+    #
+    #       @channel    = channel
+    #       # Consumer#handle_channel_exception will handle channel
+    #       # exceptions. Keep in mind that you can only register one error handler,
+    #       # so the last one registered "wins".
+    #       @channel.on_error(&method(:handle_channel_exception))
+    #     end # initialize
+    #
+    #     def start
+    #       @queue = @channel.queue(@queue_name, :exclusive => true)
+    #       # #handle_message method will be handling messages routed to @queue
+    #       @queue.subscribe(&method(:handle_message))
+    #     end # start
+    #
+    #
+    #
+    #     #
+    #     # Implementation
+    #     #
+    #
+    #     def handle_message(metadata, payload)
+    #       puts "Received a message: #{payload}, content_type = #{metadata.content_type}"
+    #     end # handle_message(metadata, payload)
+    #
+    #     def handle_channel_exception(channel, channel_close)
+    #       puts "Oops... a channel-level exception: code = #{channel_close.reply_code}, message = #{channel_close.reply_text}"
+    #     end # handle_channel_exception(channel, channel_close)
+    #   end
+    #
+    #
+    # @example Using object as consumer (message handler), take two: aggregatied handler
+    #   class Consumer
+    #
+    #     #
+    #     # API
+    #     #
+    #
+    #     def handle_message(metadata, payload)
+    #       puts "Received a message: #{payload}, content_type = #{metadata.content_type}"
+    #     end # handle_message(metadata, payload)
+    #   end
+    #
+    #
+    #   class Worker
+    #
+    #     #
+    #     # API
+    #     #
+    #
+    #
+    #     def initialize(channel, queue_name = AMQ::Protocol::EMPTY_STRING, consumer = Consumer.new)
+    #       @queue_name = queue_name
+    #
+    #       @channel    = channel
+    #       @channel.on_error(&method(:handle_channel_exception))
+    #
+    #       @consumer   = consumer
+    #     end # initialize
+    #
+    #     def start
+    #       @queue = @channel.queue(@queue_name, :exclusive => true)
+    #       @queue.subscribe(&@consumer.method(:handle_message))
+    #     end # start
+    #
+    #
+    #
+    #     #
+    #     # Implementation
+    #     #
+    #
+    #     def handle_channel_exception(channel, channel_close)
+    #       puts "Oops... a channel-level exception: code = #{channel_close.reply_code}, message = #{channel_close.reply_text}"
+    #     end # handle_channel_exception(channel, channel_close)
+    #   end
+    #
+    # @example Unit-testing objects that are used as consumers, RSpec style
+    #
+    #   require "ostruct"
+    #   require "json"
+    #
+    #   # RSpec example
+    #   describe Consumer do
+    #     describe "when a new message arrives" do
+    #       subject { described_class.new }
+    #
+    #       let(:metadata) do
+    #         o = OpenStruct.new
+    #
+    #         o.content_type = "application/json"
+    #         o
+    #       end
+    #       let(:payload)  { JSON.encode({ :command => "reload_config" }) }
+    #
+    #       it "does some useful work" do
+    #         # check preconditions here if necessary
+    #
+    #         subject.handle_message(metadata, payload)
+    #
+    #         # add your code expectations here
+    #       end
+    #     end
+    #   end
+    #
+    #
     #
     # @option opts [Boolean ]:ack (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
@@ -580,51 +712,61 @@ module AMQP
     #
     # @see file:docs/Queues.textile Documentation guide on queues
     # @see #unsubscribe
+    # @see AMQP::Consumer
     def subscribe(opts = {}, &block)
-      raise Error, 'already subscribed to the queue' if @consumer_tag
-
-      # having initial value for @consumer_tag makes a lot of obscure issues
-      # go away. It is set to real value once we receive consume-ok (it is handled by
-      # AMQ::Client::Queue we inherit from).
-      @consumer_tag = "for now"
+      raise RuntimeError.new("This queue already has default consumer. Please instantiate AMQP::Consumer directly to register additional consumers.") if @default_consumer
 
       opts[:nowait] = false if (@on_confirm_subscribe = opts[:confirm])
 
-      # We have to maintain this multiple arities jazz
-      # because older versions this gem are used in examples in at least 3
-      # books published by O'Reilly :(. MK.
-      delivery_shim = Proc.new { |method, headers, payload|
-        case block.arity
-        when 1 then
-          block.call(payload)
-        when 2 then
-          h = Header.new(@channel, method, headers.decode_payload)
-          block.call(h, payload)
-        else
-          h = Header.new(@channel, method, headers.decode_payload)
-          block.call(h, payload, method.consumer_tag, method.delivery_tag, method.redelivered, method.exchange, method.routing_key)
-        end
-      }
-
       @channel.once_open do
-        @consumer_tag = nil
-        # consumer_tag is set by AMQ::Client::Queue once we receive consume-ok, this takes a while.
-        self.consume(!opts[:ack], opts[:exclusive], (opts[:nowait] || block.nil?), opts[:no_local], nil, &opts[:confirm])
+        self.once_declared do
+          self.consume(!opts[:ack], opts[:exclusive], (opts[:nowait] || block.nil?), opts[:no_local], nil, &opts[:confirm])
+
+          self.on_delivery(&block)
+        end
       end
-      self.on_delivery(&delivery_shim)
 
       self
     end
 
+    # @return [String] Consumer tag of the default consumer associated with this queue (if any), or nil
+    # @note Default consumer is the one registered with the convenience {AMQP::Queue#subscribe} method. It has no special properties of any kind.
+    # @see Queue#subscribe
+    # @see AMQP::Consumer
+    # @api public
+    def consumer_tag
+      if @default_consumer
+        @default_consumer.consumer_tag
+      else
+        nil
+      end
+    end # consumer_tag
 
-    # Removes the subscription from the queue and cancels the consumer.
-    # New messages will not be received by this queue instance.
-    #
-    # Due to the asynchronous nature of the protocol, it is possible for
-    # "in flight" messages to be received after this call completes.
+    # @return [AMQP::Consumer] Default consumer associated with this queue (if any), or nil
+    # @note Default consumer is the one registered with the convenience {AMQP::Queue#subscribe} method. It has no special properties of any kind.
+    # @see Queue#subscribe
+    # @see AMQP::Consumer
+    # @api public
+    def default_consumer
+      @default_consumer
+    end
+
+
+    # @return [Class]
+    # @private
+    def self.consumer_class
+      AMQP::Consumer
+    end # self.consumer_class
+
+
+    # Removes the subscription from the queue and cancels the consumer. Once consumer is cancelled,
+    # messages will no longer be delivered to it, however, 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
     # {Queue#subscribe} or {Queue#pop} call.
     #
+    # Fetching messages with {AMQP::Queue#pop} is still possible even after consumer is cancelled.
+    #
     # 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.
@@ -642,9 +784,13 @@ module AMQP
     #
     # @api public
     def unsubscribe(opts = {}, &block)
-      # @consumer_tag is nillified for us by AMQ::Client::Queue, that is,
-      # our superclass. MK.
-      @channel.once_open { self.cancel(opts.fetch(:nowait, true), &block) }
+      @channel.once_open do
+        self.once_declared do
+          if @default_consumer
+            @default_consumer.cancel(opts.fetch(:nowait, true), &block); @default_consumer = nil
+          end
+        end
+      end
     end
 
     # Get the number of messages and active consumers (with active channel flow) on a queue.
@@ -670,16 +816,16 @@ module AMQP
 
 
     # Boolean check to see if the current queue has already subscribed
-    # to messages delivery.
+    # to messages delivery (has default consumer).
     #
     # Attempts to {Queue#subscribe} multiple times to the same exchange will raise an
-    # Exception. Only a single block at a time can be associated with any
-    # queue instance for processing incoming messages.
+    # Exception. If you need more than one consumer per queue, use {AMQP::Consumer} instead.
     #
     # @return [Boolean] true if there is a consumer tag associated with this Queue instance
     # @api public
+    # @deprecated
     def subscribed?
-      !!@consumer_tag
+      @default_consumer && @default_consumer.subscribed?
     end
 
 
@@ -688,7 +834,9 @@ module AMQP
     # @api public
     # @deprecated
     def callback
-      @on_declare
+      return nil if !subscribed?
+
+      @default_consumer.callback
     end
 
 
@@ -711,6 +859,14 @@ module AMQP
     end
 
 
+    # @private
+    # @api plugin
+    def handle_connection_interruption(method = nil)
+      super(method)
+
+      @declaration_deferrable = EventMachine::DefaultDeferrable.new
+    end
+
     protected
 
     # @private