bunny 0.9.0.pre6 → 0.9.0.pre7

data/lib/bunny/session.rb

@@ -15,21 +15,28 @@ require "amq/protocol/client"
 require "amq/settings"
 
 module Bunny
+  # Represents AMQP 0.9.1 connection (connection to RabbitMQ).
+  # @see http://rubybunny.info/articles/connecting.html Connecting to RabbitMQ guide
   class Session
 
+    # Default host used for connection
     DEFAULT_HOST      = "127.0.0.1"
+    # Default virtual host used for connection
     DEFAULT_VHOST     = "/"
+    # Default username used for connection
     DEFAULT_USER      = "guest"
+    # Default password used for connection
     DEFAULT_PASSWORD  = "guest"
-    # the same value as RabbitMQ 3.0 uses. MK.
+    # Default heartbeat interval, the same value as RabbitMQ 3.0 uses.
     DEFAULT_HEARTBEAT = 600
-    # 128K
+    # @private
     DEFAULT_FRAME_MAX = 131072
 
     # backwards compatibility
+    # @private
     CONNECT_TIMEOUT   = Transport::DEFAULT_CONNECTION_TIMEOUT
 
-
+    # RabbitMQ client metadata
     DEFAULT_CLIENT_PROPERTIES = {
       :capabilities => {
         :publisher_confirms         => true,
@@ -40,7 +47,7 @@ module Bunny
       :product      => "Bunny",
       :platform     => ::RUBY_DESCRIPTION,
       :version      => Bunny::VERSION,
-      :information  => "http://github.com/ruby-amqp/bunny",
+      :information  => "http://rubybunny.info",
     }
 
     DEFAULT_LOCALE = "en_GB"
@@ -50,7 +57,7 @@ module Bunny
     # API
     #
 
-    attr_reader :status, :host, :port, :heartbeat, :user, :pass, :vhost, :frame_max
+    attr_reader :status, :host, :port, :heartbeat, :user, :pass, :vhost, :frame_max, :threaded
     attr_reader :server_capabilities, :server_properties, :server_authentication_mechanisms, :server_locales
     attr_reader :default_channel
     attr_reader :channel_id_allocator
@@ -59,6 +66,21 @@ module Bunny
     attr_reader :mechanism
 
 
+    # @param [String, Hash] connection_string_or_opts Connection string or a hash of connection options
+    # @param [Hash] optz Extra options not related to connection
+    #
+    # @option connection_string_or_opts [String] :host ("127.0.0.1") Hostname or IP address to connect to
+    # @option connection_string_or_opts [Integer] :port (5672) Port RabbitMQ listens on
+    # @option connection_string_or_opts [String] :username ("guest") Username
+    # @option connection_string_or_opts [String] :password ("guest") Password
+    # @option connection_string_or_opts [String] :vhost ("/") Virtual host to use
+    # @option connection_string_or_opts [Integer] :heartbeat (600) Heartbeat interval. 0 means no heartbeat.
+    #
+    # @option optz [String] :auth_mechanism ("PLAIN") Authentication mechanism, PLAIN or EXTERNAL
+    # @option optz [String] :locale ("PLAIN") Locale RabbitMQ should use
+    #
+    # @see http://rubybunny.info/articles/connecting.html Connecting to RabbitMQ guide
+    # @api public
     def initialize(connection_string_or_opts = Hash.new, optz = Hash.new)
       opts = case (ENV["RABBITMQ_URL"] || connection_string_or_opts)
              when nil then
@@ -77,6 +99,7 @@ module Bunny
       @vhost           = self.vhost_from(opts)
       @logfile         = opts[:logfile]
       @logging         = opts[:logging] || false
+      @threaded        = opts.fetch(:threaded, true)
 
       @status             = :not_connected
 
@@ -95,21 +118,29 @@ module Bunny
       @continuations       = ::Queue.new
     end
 
+    # @return [String] RabbitMQ hostname (or IP address) used
     def hostname;     self.host;  end
+    # @return [String] Username used
     def username;     self.user;  end
+    # @return [String] Password used
     def password;     self.pass;  end
+    # @return [String] Virtual host used
     def virtual_host; self.vhost; end
 
+    # @return [Boolean] true if this connection uses TLS (SSL)
     def uses_tls?
       @transport.uses_tls?
     end
     alias tls? uses_tls?
 
+    # @return [Boolean] true if this connection uses TLS (SSL)
     def uses_ssl?
       @transport.uses_ssl?
     end
     alias ssl? uses_ssl?
 
+    # Starts connection process
+    # @api public
     def start
       @continuations = ::Queue.new
       @status        = :connecting
@@ -120,12 +151,20 @@ module Bunny
       self.open_connection
 
       @event_loop = nil
-      self.start_main_loop
+      self.start_main_loop if @threaded
 
       @default_channel = self.create_channel
     end
 
+    def read_write_timeout
+      @transport.read_write_timeout
+    end
 
+    # Opens a new channel and returns it. This method will block the calling
+    # thread until the response is received and the channel is guaranteed to be
+    # opened (this operation is very fast and inexpensive).
+    #
+    # @return [Bunny::Channel] Newly opened channel
     def create_channel(n = nil)
       if n && (ch = @channels[n])
         ch
@@ -137,11 +176,12 @@ module Bunny
     end
     alias channel create_channel
 
+    # Closes the connection. This involves closing all of its channels.
     def close
       if @transport.open?
         close_all_channels
 
-        Bunny::Timer.timeout(@disconnect_timeout, ClientTimeout) do
+        Bunny::Timer.timeout(@transport.disconnect_timeout, ClientTimeout) do
           self.close_connection(false)
         end
       end
@@ -166,7 +206,7 @@ module Bunny
     end
 
     def open?
-      status == :open || status == :connected
+      (status == :open || status == :connected) && @transport.open?
     end
     alias connected? open?
 
@@ -174,26 +214,32 @@ module Bunny
     # Backwards compatibility
     #
 
+    # @private
     def queue(*args)
       @default_channel.queue(*args)
     end
 
+    # @private
     def direct(*args)
       @default_channel.direct(*args)
     end
 
+    # @private
     def fanout(*args)
       @default_channel.fanout(*args)
     end
 
+    # @private
     def topic(*args)
       @default_channel.topic(*args)
     end
 
+    # @private
     def headers(*args)
       @default_channel.headers(*args)
     end
 
+    # @private
     def exchange(*args)
       @default_channel.exchange(*args)
     end
@@ -203,35 +249,38 @@ module Bunny
     # Implementation
     #
 
-
+    # @private
     def open_channel(ch)
       n = ch.number
       self.register_channel(ch)
 
       @transport.send_frame(AMQ::Protocol::Channel::Open.encode(n, AMQ::Protocol::EMPTY_STRING))
-      @last_channel_open_ok = @continuations.pop
+      @last_channel_open_ok = wait_on_continuations
       raise_if_continuation_resulted_in_a_connection_error!
 
       @last_channel_open_ok
     end
 
+    # @private
     def close_channel(ch)
       n = ch.number
 
       @transport.send_frame(AMQ::Protocol::Channel::Close.encode(n, 200, "Goodbye", 0, 0))
-      @last_channel_close_ok = @continuations.pop
+      @last_channel_close_ok = wait_on_continuations
       raise_if_continuation_resulted_in_a_connection_error!
 
       self.unregister_channel(ch)
       @last_channel_close_ok
     end
 
+    # @private
     def close_all_channels
       @channels.reject {|n, ch| n == 0 || !ch.open? }.each do |_, ch|
-        Bunny::Timer.timeout(@disconnect_timeout, ClientTimeout) { ch.close }
+        Bunny::Timer.timeout(@transport.disconnect_timeout, ClientTimeout) { ch.close }
       end
     end
 
+    # @private
     def close_connection(sync = true)
       @transport.send_frame(AMQ::Protocol::Connection::Close.encode(200, "Goodbye", 0, 0))
 
@@ -239,10 +288,11 @@ module Bunny
       @status   = :not_connected
 
       if sync
-        @last_connection_close_ok = @continuations.pop
+        @last_connection_close_ok = wait_on_continuations
       end
     end
 
+    # @private
     def handle_frame(ch_number, method)
       # puts "Session#handle_frame on #{ch_number}: #{method.inspect}"
       case method
@@ -252,17 +302,17 @@ module Bunny
         @continuations.push(method)
       when AMQ::Protocol::Connection::Close then
         @last_connection_error = instantiate_connection_level_exception(method)
-        @contunuations.push(method)
+        @continuations.push(method)
       when AMQ::Protocol::Connection::CloseOk then
         @last_connection_close_ok = method
         begin
           @continuations.clear
 
-          @event_loop.stop
+          event_loop.stop
           @event_loop = nil
 
           @transport.close
-        rescue Exception => e
+        rescue StandardError => e
           puts e.class.name
           puts e.message
           puts e.backtrace
@@ -280,10 +330,15 @@ module Bunny
       when AMQ::Protocol::Basic::GetEmpty then
         @channels[ch_number].handle_basic_get_empty(method)
       else
-        @channels[ch_number].handle_method(method)
+        if ch = @channels[ch_number]
+          ch.handle_method(method)
+        else
+          # TODO: log a warning
+        end
       end
     end
 
+    # @private
     def raise_if_continuation_resulted_in_a_connection_error!
       raise @last_connection_error if @last_connection_error
     end
@@ -303,7 +358,10 @@ module Bunny
       end
     end
 
+    # @private
     def handle_network_failure(exception)
+      raise NetworkErrorWrapper.new(exception) unless @threaded
+
       if !recovering_from_network_failure?
         @recovering_from_network_failure = true
         if recoverable_network_failure?(exception)
@@ -320,15 +378,18 @@ module Bunny
       end
     end
 
+    # @private
     def recoverable_network_failure?(exception)
       # TODO: investigate if we can be a bit smarter here. MK.
       true
     end
 
+    # @private
     def recovering_from_network_failure?
       @recovering_from_network_failure
     end
 
+    # @private
     def recover_from_network_failure
       begin
         # puts "About to start recovery..."
@@ -346,6 +407,7 @@ module Bunny
       end
     end
 
+    # @private
     def recover_channels
       # default channel is reopened right after connection
       # negotiation is completed, so make sure we do not try to open
@@ -357,10 +419,12 @@ module Bunny
       end
     end
 
+    # @private
     def send_raw(*args)
       @transport.write(*args)
     end
 
+    # @private
     def instantiate_connection_level_exception(frame)
       case frame
       when AMQ::Protocol::Connection::Close then
@@ -379,10 +443,12 @@ module Bunny
       end
     end
 
+    # @private
     def hostname_from(options)
       options[:host] || options[:hostname] || DEFAULT_HOST
     end
 
+    # @private
     def port_from(options)
       fallback = if options[:tls] || options[:ssl]
                    AMQ::Protocol::TLS_PORT
@@ -393,36 +459,44 @@ module Bunny
       options.fetch(:port, fallback)
     end
 
+    # @private
     def vhost_from(options)
       options[:virtual_host] || options[:vhost] || DEFAULT_VHOST
     end
 
+    # @private
     def username_from(options)
       options[:username] || options[:user] || DEFAULT_USER
     end
 
+    # @private
     def password_from(options)
       options[:password] || options[:pass] || options [:pwd] || DEFAULT_PASSWORD
     end
 
+    # @private
     def heartbeat_from(options)
       options[:heartbeat] || options[:heartbeat_interval] || options[:requested_heartbeat] || DEFAULT_HEARTBEAT
     end
 
+    # @private
     def next_channel_id
       @channel_id_allocator.next_channel_id
     end
 
+    # @private
     def release_channel_id(i)
       @channel_id_allocator.release_channel_id(i)
     end
 
+    # @private
     def register_channel(ch)
       @channel_mutex.synchronize do
         @channels[ch.number] = ch
       end
     end
 
+    # @private
     def unregister_channel(ch)
       @channel_mutex.synchronize do
         n = ch.number
@@ -432,11 +506,17 @@ module Bunny
       end
     end
 
+    # @private
     def start_main_loop
-      @event_loop = MainLoop.new(@transport, self)
-      @event_loop.start
+      event_loop.start
     end
 
+    # @private
+    def event_loop
+      @event_loop ||= MainLoop.new(@transport, self)
+    end
+
+    # @private
     def signal_activity!
       @heartbeat_sender.signal_activity! if @heartbeat_sender
     end
@@ -458,7 +538,7 @@ module Bunny
     # Sends multiple frames, one by one. For thread safety this method takes a channel
     # object and synchronizes on it.
     #
-    # @api public
+    # @api private
     def send_frameset(frames, channel)
       # some developers end up sharing channels between threads and when multiple
       # threads publish on the same channel aggressively, at some point frames will be
@@ -473,6 +553,7 @@ module Bunny
 
     protected
 
+    # @api private
     def init_connection
       self.send_preamble
 
@@ -487,6 +568,7 @@ module Bunny
       @status = :connected
     end
 
+    # @api private
     def open_connection
       @transport.send_frame(AMQ::Protocol::Connection::StartOk.encode(@client_properties, @mechanism, self.encode_credentials(username, password), @locale))
 
@@ -539,6 +621,7 @@ module Bunny
       raise "could not open connection: server did not respond with connection.open-ok" unless connection_open_ok.is_a?(AMQ::Protocol::Connection::OpenOk)
     end
 
+    # @api private
     def negotiate_value(client_value, server_value)
       if client_value == 0 || server_value == 0
         [client_value, server_value].max
@@ -547,37 +630,48 @@ module Bunny
       end
     end
 
+    # @api private
     def initialize_heartbeat_sender
       # puts "Initializing heartbeat sender..."
       @heartbeat_sender = HeartbeatSender.new(@transport)
       @heartbeat_sender.start(@heartbeat)
     end
 
+    # @api private
     def maybe_shutdown_heartbeat_sender
       @heartbeat_sender.stop if @heartbeat_sender
     end
 
-
+    # @api private
     def initialize_transport
       @transport = Transport.new(self, @host, @port, @opts)
     end
 
     # Sends AMQ protocol header (also known as preamble).
+    # @api private
     def send_preamble
       @transport.send_raw(AMQ::Protocol::PREAMBLE)
     end
 
 
-
-
-    # @api plugin
+    # @api private
     def encode_credentials(username, password)
       @credentials_encoder.encode_credentials(username, password)
     end # encode_credentials(username, password)
 
+    # @api private
     def credentials_encoder_for(mechanism)
       Authentication::CredentialsEncoder.for_session(self)
     end
+
+    # @api private
+    def wait_on_continuations
+      unless @threaded
+        event_loop.run_once until @continuations.length > 0
+      end
+
+      @continuations.pop
+    end
   end # Session
 
   # backwards compatibility