amqp 0.8.0.rc2 → 0.8.0.rc3

data/lib/amqp/connection.rb

@@ -75,15 +75,16 @@ module AMQP
     @connection.closing?
   end
 
-
+  # @return [Boolean] Current global logging value
   # @api public
   def self.logging
     self.settings[:logging]
   end
 
+  # @return [Boolean] Sets current global logging value
   # @api public
   def self.logging=(value)
-    self.settings[:logging] = !! value
+    self.settings[:logging] = !!value
   end
 
   # Default connection. When you do not pass connection instance to methods like
@@ -94,6 +95,7 @@ module AMQP
     @connection
   end
 
+  # Sets global connection object.
   # @api public
   def self.connection=(value)
     @connection = value
@@ -144,7 +146,7 @@ module AMQP
   #       # ...
   #     end
   #   end
-  #  
+  #
   #
   # @overload connect(connection_string, options = {})
   #   Used to pass connection parameters as a connection string
@@ -161,7 +163,7 @@ module AMQP
   # @option connection_options_or_string [String]  :username ("guest") Username to use. Also can be specified as :user.
   # @option connection_options_or_string [String]  :password ("guest") Password to use. Also can be specified as :pass.
   # @option connection_options_or_string [Hash]  :ssl TLS (SSL) parameters to use.
-  # @option connection_options_or_string [#call]  :on_possible_authentication_failure A callable object that will be run if authentication fails (see Authentication failure section)  
+  # @option connection_options_or_string [#call]  :on_possible_authentication_failure A callable object that will be run if authentication fails (see Authentication failure section)
   #
   #
   # h2. Handling authentication failures
@@ -175,18 +177,15 @@ module AMQP
   # with :on_possible_authentication_failure option.
   #
   # @note This method assumes that EventMachine even loop is already running. If it is not the case or you are not sure, we recommend you use {AMQP.start} instead. It takes exactly the same parameters.
+  # @return [AMQP::Session]
   # @api public
   def self.connect(connection_options_or_string = {}, other_options = {}, &block)
     Client.connect(connection_options_or_string, other_options, &block)
   end
 
-  # @return [Hash] If default connection is set up, returns settings it was set up with. Otherwise, returns default settings.
+  # @return [Hash] Default AMQP connection settings. This hash may be modified.
   # @api public
   def self.settings
-    if @connection
-      @connection.settings
-    else
-      AMQ::Client::Settings.default
-    end
+    @settings ||= AMQ::Client::Settings.default
   end
 end # AMQP

data/lib/amqp/deprecated/fork.rb

@@ -2,7 +2,7 @@ require "amqp/ext/em"
 
 module AMQP
   # @deprecated
-  # @api public
+  # @private
   def self.fork(workers)
     EM.fork(workers) do
       # clean up globals in the fork
@@ -11,5 +11,5 @@ module AMQP
 
       yield
     end
-  end  
-end
+  end
+end

data/lib/amqp/deprecated/logger.rb

@@ -1,6 +1,7 @@
 # encoding: utf-8
 
 module AMQP
+  # @private
   class Logger
     def initialize(*args, &block)
       opts = args.pop if args.last.is_a? Hash

data/lib/amqp/deprecated/mq.rb

@@ -17,4 +17,26 @@ class MQ
   # @note This class will be removed before 1.0 release.
   # @deprecated
   class Queue < ::AMQP::Queue; end
-end
+
+
+  #
+  # Backwards compatibility with 0.6.x
+  #
+
+  # unique identifier
+  def MQ.id
+    Thread.current[:mq_id] ||= "#{`hostname`.strip}-#{Process.pid}-#{Thread.current.object_id}"
+  end
+
+  # @private
+  def MQ.default
+    # TODO: 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

data/lib/amqp/deprecated/rpc.rb

@@ -36,6 +36,7 @@ module AMQP
   #
   # @note This class will be removed before 1.0 release.
   # @deprecated
+  # @private
   class RPC < ::AMQP::BlankSlate
 
     #

data/lib/amqp/exceptions.rb

@@ -1,18 +1,60 @@
 # encoding: utf-8
 
 module AMQP
-  # Raised whenever an illegal operation is attempted.
-  class Error < StandardError; end
+  # Base class for AMQP connection lifecycle exceptions.
+  # @api public
+  class Error < StandardError
+    # An exception in one of the underlying libraries that caused this
+    # exception to be re-thrown. May be nil.
+    attr_reader :cause
+  end
 
+
+  # All the exceptions below are new in 0.8.0. Previous versions
+  # used AMQP::Error for everything. We have to carry this baggage but
+  # there is a way out: simply subclass AMQP::Error and provide a backwards-compatible
+  # way of attaching root cause exception (like AMQ::Client::TCPConnectionFailed) instance
+  # to it.
+  #
+  # In other words: AMQP::Error is here to stay for a long time. MK.
+
+
+
+  # Raised when initial TCP connection to the broker fails.
+  # @api public
+  class TCPConnectionFailed < Error
+
+    #
+    # API
+    #
+
+    # @return [Hash] connection settings that were used
+    attr_reader :settings
+
+    def initialize(settings, cause = nil)
+      @settings = settings
+      @cause    = cause
+
+      super("Could not estabilish TCP connection to #{@settings[:host]}:#{@settings[:port]}")
+    end # TCPConnectionFailed
+  end
+
+
+  # Raised when queue (or exchange) declaration fails because another queue with the same
+  # name but different attributes already exists in the channel object cache.
+  # @api public
   class IncompatibleOptionsError < Error
     def initialize(name, opts_1, opts_2)
       super("There is already an instance called #{name} with options #{opts_1.inspect}, you can't define the same instance with different options (#{opts_2.inspect})!")
     end
   end # IncompatibleOptionsError
 
+  # Raised on attempt to use a channel that was previously closed
+  # (either due to channel-level exception or intentionally via AMQP::Channel#close).
+  # @api public
   class ChannelClosedError < Error
     def initialize(instance)
-      super("The channel #{instance.channel} was closed, you can't use it anymore!")
+      super("Channel with id = #{instance.channel} is closed, you can't use it anymore!")
     end
   end # ChannelClosedError
 end # AMQP

data/lib/amqp/exchange.rb

@@ -12,18 +12,10 @@ module AMQP
   # 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.
-  #
-  # 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.
+  # Entities that forward messages to consumers (or consumers fetch messages
+  # from on demand) are called {Queue queues}. Exchanges are associated with
+  # queues via bindings. Roughly speaking, bindings determine messages placed
+  # in what exchange end up in what queues.
   #
   #
   # h2. AMQP bindings
@@ -36,16 +28,10 @@ module AMQP
   # 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.
+  # h2. Exchange types
   #
-  # 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.
+  # There are 4 supported exchange types: direct, fanout, topic and headers.
+  # Exchange type determines how exchange processes and routes messages.
   #
   #
   # h2. Direct exchanges
@@ -61,6 +47,11 @@ module AMQP
   # 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.
   #
+  # 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.
   #
   #
   # h2. Fanout exchanges
@@ -71,7 +62,6 @@ module AMQP
   # 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.
@@ -96,10 +86,7 @@ module AMQP
   #
   # 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
+  # When publishing data to exchange of type headers, 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
@@ -109,6 +96,19 @@ module AMQP
   # it does an AND of the headers ), while a value of 'any' implies that
   # at least one should match (ie. it does an OR).
   #
+  # As part of the AMQP standard, each server _should_ predeclare a headers
+  # exchange named 'amq.match'.
+  #
+  #
+  # h2. Key methods
+  #
+  # Key methods of Exchange class are
+  #
+  # * {Exchange#publish}
+  # * {Exchange#delete}
+  # * {Exchange.default}
+  #
+  #
   #
   # h2. Exchange durability and persistence of messages.
   #
@@ -124,7 +124,8 @@ module AMQP
   # 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*.
+  # Note that *only durable queues can be bound to durable exchanges*.  Learn more in our {file:docs/Durability.textile Durability guide}.
+  #
   #
   #
   # h2. RabbitMQ extensions.
@@ -133,14 +134,6 @@ module AMQP
   # 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.
@@ -517,6 +510,7 @@ module AMQP
 
     protected
 
+    # @private
     def self.add_default_options(type, name, opts, block)
       { :exchange => name, :type => type, :nowait => block.nil? }.merge(opts)
     end

data/lib/amqp/ext/em.rb

@@ -1,10 +1,3 @@
 # encoding: utf-8
 
-begin
-  require 'eventmachine'
-rescue LoadError
-  require 'rubygems'
-  require 'eventmachine'
-end
-
 require 'amqp/ext/emfork'

data/lib/amqp/ext/emfork.rb

@@ -1,5 +1,6 @@
 # encoding: utf-8
 
+# @private
 EMFORK = $0 == __FILE__
 
 if EMFORK
@@ -8,9 +9,8 @@ end
 
 require 'eventmachine'
 
-#:stopdoc:
-
 # helper to fork off EM reactors
+# @private
 def EM.fork num = 1, &blk
   unless @forks
     trap('CHLD') {
@@ -47,6 +47,7 @@ def EM.fork num = 1, &blk
   end
 end
 
+# @private
 def EM.forks
   @forks ? @forks.keys : []
 end

data/lib/amqp/header.rb

@@ -38,6 +38,8 @@ module AMQP
       @channel.reject(@method.delivery_tag, opts.fetch(:requeue, false))
     end
 
+    # @return [Hash] AMQP message header w/o method-specific information.
+    # @api public
     def to_hash
       @header
     end # to_hash
@@ -46,6 +48,8 @@ module AMQP
       (@header && args.empty? && blk.nil? && @header.has_key?(meth)) || @method.respond_to?(meth)
     end
 
+    # Returns AMQP message attributes.
+    # @api public
     def method_missing(meth, *args, &blk)
       if @header && args.empty? && blk.nil? && @header.has_key?(meth)
         @header[meth]

data/lib/amqp/queue.rb

@@ -10,27 +10,83 @@ module AMQP
   # to queues and finally queues deliver them to consumer applications (or consumer
   # applications fetch messages as needed).
   #
+  # Note that unlike some other messaging protocols/systems, messages are not delivered directly
+  # to queues. They are delivered to exchanges that route messages to queues using rules
+  # knows as *bindings*.
+  #
   #
   # h2. Concept of bindings
   #
+  # Binding is an association between a queue and an exchange.
   # Queues must be bound to at least one exchange in order to receive messages from publishers.
   # Learn more about bindings in {Exchange Exchange class documentation}.
   #
   #
+  # h2. Key methods
+  #
+  # Key methods of Queue class are
+  #
+  # * {Queue#bind}
+  # * {Queue#subscribe}
+  # * {Queue#pop}
+  # * {Queue#delete}
+  # * {Queue#purge}
+  # * {Queue#unbind}
+  #
+  #
   # h2. Queue names. Server-named queues. Predefined queues.
   #
-  # 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 AMQP::Error (ACCESS_REFUSED).
+  # Every queue has a name that identifies it. Queue names often contain several segments separated by a dot (.), similarly to how URI
+  # path segments are separated by a slash (/), although it may be almost any string, with some limitations (see below).
+  # Applications may pick queue names or ask broker to generate a name for them. To do so, pass *empty string* as queue name argument.
+  #
+  # Here is an example:
+  #
+  # @example Declaring a server-named queue using AMQP::Queue constructor
+  #   AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  #     AMQP::Channel.new do |channel, open_ok|
+  #       AMQP::Queue.new(channel, "", :auto_delete => true) do |queue, declare_ok|
+  #         puts "#{queue.name} is ready to go. AMQP method: #{declare_ok.inspect}"
+  #
+  #         connection.close {
+  #           EM.stop { exit }
+  #         }
+  #       end
+  #     end
+  #   end
+  #
+  # <script src="https://gist.github.com/939596.js?file=gistfile1.rb"></script>
+  #
+  # If you want to declare a queue with a particular name, for example, "images.resize", pass it to Queue class constructor:
+  #
+  # @example Declaring a server-named queue using AMQP::Queue constructor
+  #   AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+  #     AMQP::Channel.new do |channel, open_ok|
+  #       AMQP::Queue.new(channel, "images.resize", :auto_delete => true) do |queue, declare_ok|
+  #         puts "#{queue.name} is ready to go."
+  #
+  #         connection.close {
+  #           EM.stop { exit }
+  #         }
+  #       end
+  #     end
+  #   end
+  #
+  # <script src="https://gist.github.com/939600.js?file=gistfile1.rb"></script>
+  #
+  # Queue names starting with 'amq.' are reserved for internal use by the broker. Attempts to declare queue with a name that violates this
+  # rule will result in AMQP::IncompatibleOptionsError to be thrown (when
+  # queue is re-declared on the same channel object) or channel-level exception (when originally queue
+  # was declared on one channel and re-declaration with different attributes happens on another channel).
+  # Learn more in {file:docs/Queues.textile Queues guide} and {file:docs/ErrorHandling.textile Error Handling guide}.
+  #
   #
-  # When a queue is created without a name, the server will generate a
-  # unique name internally (not currently supported in this library).
   #
   # h2. Queue life-cycles. When use of server-named queues is optimal and when it isn't.
   #
   # To quote AMQP 0.9.1 spec, there are two common message queue life-cycles:
   #
-  #	 * Durable message queues that are shared by many consumers and have an independent existence: i.e. they
+  #  * Durable message queues that are shared by many consumers and have an independent existence: i.e. they
   #    will continue to exist and collect messages whether or not there are consumers to receive them.
   #  * Temporary message queues that are private to one consumer and are tied to that consumer. When the
   #    consumer disconnects, the message queue is deleted.
@@ -78,7 +134,7 @@ module AMQP
   # 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*.
+  # Note that *only durable queues can be bound to durable exchanges*. Learn more in our {file:docs/Durability.textile Durability guide}.
   #
   #
   # h2. Message ordering
@@ -86,16 +142,11 @@ module AMQP
   # RabbitMQ FAQ explains {http://www.rabbitmq.com/faq.html#message-ordering ordering of messages in AMQP queues}
   #
   #
-  # h2. Key methods
+  # h2. Error handling
   #
-  # Key methods of Queue class are
-  #
-  # * {Queue#bind}
-  # * {Queue#subscribe}
-  # * {Queue#pop}
-  # * {Queue#delete}
-  # * {Queue#purge}
-  # * {Queue#unbind}
+  # When channel-level error occurs, queues associated with that channel are reset: internal state and callbacks
+  # are cleared. Recommended strategy is to open a new channel and re-declare all the entities you need.
+  # Learn more in {file:docs/ErrorHandling.textile Error Handling guide}.
   #
   #
   # @note Please make sure you read a section on queue durability vs. messages
@@ -112,11 +163,8 @@ module AMQP
 
     # Name of this queue
     attr_reader :name
-    attr_reader :sync_bind
     # Options this queue object was instantiated with
     attr_accessor :opts
-    attr_accessor :on_declare
-    attr_accessor :on_bind
 
 
 
@@ -163,8 +211,14 @@ module AMQP
       @channel  = channel
       name      = AMQ::Protocol::EMPTY_STRING if name.nil?
       @name     = name unless name.empty?
-      @opts     = self.class.add_default_options(name, opts, block)
-      @bindings = Hash.new
+      @server_named = name.empty?
+      @opts         = self.class.add_default_options(name, opts, block)
+      @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.
+      @declaration_deferrable = AMQ::Client::EventMachineClient::Deferrable.new
 
       if @opts[:nowait]
         @status = :opened
@@ -176,6 +230,8 @@ module AMQP
       super(channel.connection, channel, name)
 
       shim = Proc.new do |q, declare_ok|
+        @declaration_deferrable.succeed
+
         case block.arity
         when 1 then block.call(q)
         else
@@ -187,11 +243,19 @@ module AMQP
         if block
           self.declare(@opts[:passive], @opts[:durable], @opts[:exclusive], @opts[:auto_delete], @opts[:nowait], @opts[:arguments], &shim)
         else
-          self.declare(@opts[:passive], @opts[:durable], @opts[:exclusive], @opts[:auto_delete], @opts[:nowait], @opts[:arguments])
+          injected_callback = Proc.new { @declaration_deferrable.succeed }
+          # we cannot pass :nowait as true here, AMQ::Client::Queue will (rightfully) raise an exception because
+          # it has no idea about crazy edge cases we are trying to support for sake of backwards compatibility. MK.
+          self.declare(@opts[:passive], @opts[:durable], @opts[:exclusive], @opts[:auto_delete], false, @opts[:arguments], &injected_callback)
         end
       end
     end
 
+    # @return [Boolean] true if this queue is server-named
+    def server_named?
+      @server_named
+    end # server_named?
+
 
     # This method binds a queue to an exchange.  Until a queue is
     # bound it will not receive any messages.  In a classic messaging
@@ -234,14 +298,21 @@ module AMQP
     # @see Queue#unbind
     def bind(exchange, opts = {}, &block)
       @status             = :unbound
-      @sync_bind          = !opts[:nowait]
       # amq-client's Queue already does exchange.respond_to?(:name) ? exchange.name : exchange
       # for us
       exchange            = exchange
       @bindings[exchange] = opts
 
-      @channel.once_open do
-        super(exchange, (opts[:key] || opts[:routing_key] || AMQ::Protocol::EMPTY_STRING), (opts[:nowait] || block.nil?), opts[:arguments], &block)
+      if self.server_named?
+        @channel.once_open do
+          @declaration_deferrable.callback do
+            super(exchange, (opts[:key] || opts[:routing_key] || AMQ::Protocol::EMPTY_STRING), (opts[:nowait] || block.nil?), opts[:arguments], &block)
+          end
+        end
+      else
+        @channel.once_open do
+          super(exchange, (opts[:key] || opts[:routing_key] || AMQ::Protocol::EMPTY_STRING), (opts[:nowait] || block.nil?), opts[:arguments], &block)
+        end
       end
 
       self
@@ -599,14 +670,6 @@ module AMQP
       @on_declare
     end
 
-    # Compatibility alias for #on_bind.
-    #
-    # @api public
-    # @deprecated
-    def bind_callback
-      @on_bind
-    end
-