rabbitmq 0.2.5 → 1.0.0.pre.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c5796fdaa12581d2a80420b02b7d6c235197642e
-  data.tar.gz: c006f752eaa9462d1386f3bafc5152ae6f5b3b3d
+  metadata.gz: bbcea6833e05f45e3fad47a964344db56b8b35e4
+  data.tar.gz: df9d1eada5b15a428b2f40534c4b1ca19871545b
 SHA512:
-  metadata.gz: 4b31aa2b1696e3ae468fba9c8185a28cf43f2d2de1f04729d0fc5e2b85c6ac1dd5f4f3862d43b8f9fd479438a5e7701341f0ad8d3cd39268ee8a26be9eda093f
-  data.tar.gz: 4730ac639d299037acb7023bbf7d844e9c588241c7c6ec3778dbb7b6d8d4540691a59cc4831335adfddb4598ba3d77abd0ad81406af31529f8683eae2f0a3514
+  metadata.gz: 7c555f53f68264cdabc58c23bd4222d6771f33c6841a74efe28c448a653cb51dbbee3e5d8c12279c9c96ad82114a6473d1a91790c21d4b7e34d5123a8822bf82
+  data.tar.gz: 7a041a8493561c0b10eab3c7d7133047e67f404925ec5e17a2c22832cec92846ca0b05326397039c5f203c2400185466024921a1d1f6b52dcb22136506a0167b

data/README.md

@@ -1,6 +1,71 @@
 # rabbitmq
 
-[![Build Status](https://travis-ci.org/jemc/ruby-rabbitmq.png)](https://travis-ci.org/jemc/ruby-rabbitmq)
 [![Gem Version](https://badge.fury.io/rb/rabbitmq.png)](http://badge.fury.io/rb/rabbitmq)
+[![Build Status](https://circleci.com/gh/jemc/ruby-rabbitmq/tree/master.svg?style=svg)](https://circleci.com/gh/jemc/ruby-rabbitmq/tree/master)
 
-A Ruby RabbitMQ client library based on FFI bindings for librabbitmq.
+A Ruby RabbitMQ client library based on FFI bindings for librabbitmq.
+
+## Design Goals
+
+- Provide a minimal API for creating useful RabbitMQ applications in Ruby.
+- Use a minimal resource and execution path footprint.
+- No library-imposed background or watchdog threads.
+- Favor directness over convenience.
+- Use an existing protocol library (librabbitmq) instead of reinventing one.
+- Avoid making precluding assumptions about what a user needs.
+
+## Who should use this library?
+
+This library was born out dissatisfaction with some of the design decisions made by existing RabbitMQ client libraries for Ruby and the lack of flexibility those libraries afforded to their users in deciding how best to integrate RabbitMQ into their application. This library is for users who know what they want, know the patterns they need to use from RabbitMQ best practices, and want to proceed with a library that provides them the minimal platform they need without getting in their way.
+
+This library runs no background threads and leaves it up to the user to explicitly invoke the RabbitMQ event loop as a part of their application. This library aims to be easy to integrate with any sensible event processing framework or pattern, or to act as the main event loop driver itself. Users should know what kind of patterns they wish to use, and understand how they can use blocking calls, nonblocking calls, and/or timeouts to implement their application elegantly and efficiently.
+
+This library does not provide thread-safe client objects. Multithreaded applications should pass data between threads instead of sharing client objects between threads. Not supporting concurrent access to connection state is consistent with the underlying C library and allows for less obfuscation in the codebase and better efficiency, avoiding the costs of acquiring locks and passing through session changes. Users should be comfortable with code patterns that prevent unwanted sharing of the client objects, as doing so may cause catastrophic application failures like segmentation faults in the underlying C library.
+
+## Usage
+
+```bash
+gem install rabbitmq
+ruby examples/publish_500.rb
+ruby examples/consume_500.rb
+```
+
+```ruby
+# examples/publish_500.rb
+require 'rabbitmq'
+
+publisher = RabbitMQ::Client.new.start.channel
+queue     = "some_queue"
+exchange  = "" # default exchange
+publisher.queue_declare(queue)
+
+500.times do |i|
+  publisher.basic_publish("message #{i}", exchange, queue, persistent: true)
+end
+```
+
+```ruby
+# examples/consume_500.rb
+require 'rabbitmq'
+
+consumer = RabbitMQ::Client.new.start.channel
+consumer.basic_qos(prefetch_count: 500)
+consumer.basic_consume("some_queue")
+
+count = 0
+consumer.on :basic_deliver do |message|
+  puts message[:body]
+  if (count += 1) >= 500
+    consumer.basic_ack(message[:properties][:delivery_tag], multiple: true)
+    consumer.break!
+  end
+end
+
+consumer.run_loop!
+```
+
+## Contributing
+
+Performance and implementation improvements, bug fixes, and documentation expansions are always welcome! Create a patch or pull request with a focused approach that solves exactly one problem, and it's very likely to be pulled in.
+
+For new features, please file an issue ticket explaining the use case and why the new feature should be a part of this library rather than a part of a separate wrapper or convenience library. If a feature meets the design goals of the project and is not yet implemented (such as SSL support, or other missing primitives critical to certain applications), it's likely to be approved quickly.

data/lib/rabbitmq.rb

@@ -7,5 +7,5 @@ require_relative 'rabbitmq/ffi/error'
 
 require_relative 'rabbitmq/server_error'
 
-require_relative 'rabbitmq/connection'
+require_relative 'rabbitmq/client'
 require_relative 'rabbitmq/channel'

data/lib/rabbitmq/channel.rb

@@ -1,18 +1,35 @@
 
 module RabbitMQ
+  
+  # A {Channel} holds a connection to a RabbitMQ server and is associated
+  # with a specific channel id number for categorizing message flow.
+  # It also provides convenient wrapper methods for common uses of
+  # the underlying {Client}.
+  #
+  # A {Channel} is not threadsafe; both the {Channel} and its associated
+  # {Client} should not be shared between threads. If they are shared without
+  # appropriate locking mechanisms, the behavior is undefined and might result
+  # in catastrophic process failures like segmentation faults in the underlying
+  # C library. A {Channel} can be safely used in a multithreaded application by
+  # only passing control and message data between threads.
+  #
+  # To use a {Channel} effectively, it is necessary to understand the
+  # methods available in the underlying AMQP protocol. Please refer to
+  # the protocol documentation for more information about specific methods:
+  # http://www.rabbitmq.com/amqp-0-9-1-reference.html
+  #
   class Channel
     
-    attr_reader :connection
+    attr_reader :client
     attr_reader :id
     
-    # Don't create a {Channel} directly; call {Connection#channel} instead.
+    # Don't create a {Channel} directly; call {Client#channel} instead.
     # @api private
-    def initialize(connection, id, pre_allocated: false)
-      @connection = connection
-      @id         = id
-      connection.send(:allocate_channel, id) unless pre_allocated
-      
-      @finalizer = self.class.send :create_finalizer_for, @connection, @id
+    def initialize(client, conn, id, finalizer)
+      @client    = client
+      @conn      = conn
+      @id        = id
+      @finalizer = finalizer
       ObjectSpace.define_finalizer self, @finalizer
     end
     
@@ -20,7 +37,7 @@ module RabbitMQ
     # This will be called automatically by the object finalizer after
     # the object becomes unreachable by the VM and is garbage collected,
     # but you may want to call it explicitly if you plan to reuse the same
-    # channel if in another {Channel} instance explicitly.
+    # channel id in another {Channel} instance explicitly.
     #
     # @return [Channel] self.
     #
@@ -34,198 +51,217 @@ module RabbitMQ
       self
     end
     
-    # @see {Connection#on_event}
-    def on(*args, &block)
-      @connection.on_event(@id, *args, &block)
+    # @see {Client#send_request}
+    def send_request(*args)
+      @client.send_request(@id, *args)
     end
     
-    # @see {Connection#run_loop!}
-    def run_loop!(*args)
-      @connection.run_loop!(*args)
+    # @see {Client#fetch_response}
+    def fetch_response(*args)
+      @client.fetch_response(@id, *args)
     end
     
-    # @see {Connection#break!}
-    def break!
-      @connection.break!
+    # @see {Client#on_event}
+    def on_event(*args, &block)
+      @client.on_event(@id, *args, &block)
     end
+    alias_method :on, :on_event
     
-    # Create a finalizer not entangled with the {Channel} instance.
-    # @api private
-    def self.create_finalizer_for(connection, id)
-      Proc.new do
-        connection.send(:release_channel, id)
-      end
+    # @see {Client#clear_event_handler}
+    def clear_event_handler(*args)
+      @client.clear_event_handler(@id, *args)
     end
     
-    private def rpc(request_type, params=[{}], response_type)
-      @connection.send_request(@id, request_type, params.last || {})
-      if response_type
-        @connection.fetch_response(@id, response_type)
-      else
-        true
-      end
+    # @see {Client#run_loop!}
+    # The block will be yielded all non-exception events *for any channel*.
+    def run_loop!(*args, &block)
+      @client.run_loop!(*args, &block)
+    end
+    
+    # @see {Client#break!}
+    def break!
+      @client.break!
     end
     
     ##
     # Exchange operations
     
     def exchange_declare(name, type, **opts)
-      rpc :exchange_declare, [
+      send_request :exchange_declare, {
         exchange:    name,
         type:        type,
         passive:     opts.fetch(:passive,     false),
         durable:     opts.fetch(:durable,     false),
         auto_delete: opts.fetch(:auto_delete, false),
         internal:    opts.fetch(:internal,    false),
-      ], :exchange_declare_ok
+      }
+      fetch_response :exchange_declare_ok
     end
     
     def exchange_delete(name, **opts)
-      rpc :exchange_delete, [
+      send_request :exchange_delete, {
         exchange:  name,
-        if_unused: opts.fetch(:if_unused, false),
-      ], :exchange_delete_ok
+        if_unused: opts.fetch(:if_unused, false)
+      }
+      fetch_response :exchange_delete_ok
     end
     
     def exchange_bind(source, destination, **opts)
-      rpc :exchange_bind, [
+      send_request :exchange_bind, {
         source:      source,
         destination: destination,
         routing_key: opts.fetch(:routing_key, ""),
-        arguments:   opts.fetch(:arguments,   {}),
-      ], :exchange_bind_ok
+        arguments:   opts.fetch(:arguments,   {})
+      }
+      fetch_response :exchange_bind_ok
     end
     
     def exchange_unbind(source, destination, **opts)
-      rpc :exchange_unbind, [
+      send_request :exchange_unbind, {
         source:      source,
         destination: destination,
         routing_key: opts.fetch(:routing_key, ""),
-        arguments:   opts.fetch(:arguments,   {}),
-      ], :exchange_unbind_ok
+        arguments:   opts.fetch(:arguments,   {})
+      }
+      fetch_response :exchange_unbind_ok
     end
     
     ##
     # Queue operations
     
     def queue_declare(name, **opts)
-      rpc :queue_declare, [
+      send_request :queue_declare, {
         queue:       name,
         passive:     opts.fetch(:passive,     false),
         durable:     opts.fetch(:durable,     false),
         exclusive:   opts.fetch(:exclusive,   false),
         auto_delete: opts.fetch(:auto_delete, false),
-        arguments:   opts.fetch(:arguments,   {}),
-      ], :queue_declare_ok
+        arguments:   opts.fetch(:arguments,   {})
+      }
+      fetch_response :queue_declare_ok
     end
     
     def queue_bind(name, exchange, **opts)
-      rpc :queue_bind, [
+      send_request :queue_bind, {
         queue:       name,
         exchange:    exchange,
         routing_key: opts.fetch(:routing_key, ""),
-        arguments:   opts.fetch(:arguments,   {}),
-      ], :queue_bind_ok
+        arguments:   opts.fetch(:arguments,   {})
+      }
+      fetch_response :queue_bind_ok
     end
     
     def queue_unbind(name, exchange, **opts)
-      rpc :queue_unbind, [
+      send_request :queue_unbind, {
         queue:       name,
         exchange:    exchange,
         routing_key: opts.fetch(:routing_key, ""),
-        arguments:   opts.fetch(:arguments,   {}),
-      ], :queue_unbind_ok
+        arguments:   opts.fetch(:arguments,   {})
+      }
+      fetch_response :queue_unbind_ok
     end
     
     def queue_purge(name)
-      rpc :queue_purge, [queue: name], :queue_purge_ok
+      send_request :queue_purge, { queue: name }
+      fetch_response :queue_purge_ok
     end
     
     def queue_delete(name, **opts)
-      rpc :queue_delete, [
+      send_request :queue_delete, {
         queue:     name,
         if_unused: opts.fetch(:if_unused, false),
-        if_empty:  opts.fetch(:if_empty,  false),
-      ], :queue_delete_ok
+        if_empty:  opts.fetch(:if_empty,  false)
+      }
+      fetch_response :queue_delete_ok
     end
     
     ##
     # Consumer operations
     
     def basic_qos(**opts)
-      rpc :basic_qos, [
+      send_request :basic_qos, {
         prefetch_count: opts.fetch(:prefetch_count, 0),
         prefetch_size:  opts.fetch(:prefetch_size,  0),
-        global:         opts.fetch(:global,         false),
-      ], :basic_qos_ok
+        global:         opts.fetch(:global,         false)
+      }
+      fetch_response :basic_qos_ok
     end
     
     def basic_consume(queue, consumer_tag="", **opts)
-      rpc :basic_consume, [
+      send_request :basic_consume, {
         queue:        queue,
         consumer_tag: consumer_tag,
         no_local:     opts.fetch(:no_local,  false),
         no_ack:       opts.fetch(:no_ack,    false),
         exclusive:    opts.fetch(:exclusive, false),
-        arguments:    opts.fetch(:arguments, {}),
-      ], :basic_consume_ok
+        arguments:    opts.fetch(:arguments, {})
+      }
+      fetch_response :basic_consume_ok
     end
     
     def basic_cancel(consumer_tag)
-      rpc :basic_cancel, [consumer_tag: consumer_tag], :basic_cancel_ok
+      send_request :basic_cancel, { consumer_tag: consumer_tag }
+      fetch_response :basic_cancel_ok
     end
     
     ##
     # Transaction operations
     
     def tx_select
-      rpc :tx_select, [], :tx_select_ok
+      send_request :tx_select
+      fetch_response :tx_select_ok
     end
     
     def tx_commit
-      rpc :tx_commit, [], :tx_commit_ok
+      send_request :tx_commit
+      fetch_response :tx_commit_ok
     end
     
     def tx_rollback
-      rpc :tx_rollback, [], :tx_rollback_ok
+      send_request :tx_rollback
+      fetch_response :tx_rollback_ok
     end
     
     ##
     # Message operations
     
     def basic_get(queue, **opts)
-      rpc :basic_get, [
+      send_request :basic_get, {
         queue:  queue,
-        no_ack: opts.fetch(:no_ack, false),
-      ], [:basic_get_ok, :basic_get_empty]
+        no_ack: opts.fetch(:no_ack, false)
+      }
+      fetch_response [:basic_get_ok, :basic_get_empty]
     end
     
     def basic_ack(delivery_tag, **opts)
-      rpc :basic_ack, [
+      send_request :basic_ack, {
         delivery_tag: delivery_tag,
-        multiple:     opts.fetch(:multiple, false),
-      ], nil
+        multiple:     opts.fetch(:multiple, false)
+      }
+      true
     end
     
     def basic_nack(delivery_tag, **opts)
-      rpc :basic_nack, [
+      send_request :basic_nack, {
         delivery_tag: delivery_tag,
         multiple:     opts.fetch(:multiple, false),
-        requeue:      opts.fetch(:requeue, true),
-      ], nil
+        requeue:      opts.fetch(:requeue, true)
+      }
+      true
     end
     
     def basic_reject(delivery_tag, **opts)
-      rpc :basic_reject, [
+      send_request :basic_reject, {
         delivery_tag: delivery_tag,
-        requeue:      opts.fetch(:requeue, true),
-      ], nil
+        requeue:      opts.fetch(:requeue, true)
+      }
+      true
     end
     
     def basic_publish(body, exchange, routing_key, **opts)
-      body        = FFI::Bytes.from_s(body)
-      exchange    = FFI::Bytes.from_s(exchange)
-      routing_key = FFI::Bytes.from_s(routing_key)
+      body        = FFI::Bytes.from_s(body.to_s)
+      exchange    = FFI::Bytes.from_s(exchange.to_s)
+      routing_key = FFI::Bytes.from_s(routing_key.to_s)
       properties  = FFI::BasicProperties.new.apply(
         content_type:       opts.fetch(:content_type,     nil),
         content_encoding:   opts.fetch(:content_encoding, nil),
@@ -243,7 +279,7 @@ module RabbitMQ
       )
       
       Util.error_check :"publishing a message",
-        FFI.amqp_basic_publish(connection.send(:ptr), @id,
+        FFI.amqp_basic_publish(@conn.ptr, @id,
           exchange,
           routing_key,
           opts.fetch(:mandatory, false),

data/lib/rabbitmq/client.rb

@@ -0,0 +1,332 @@
+
+require_relative 'client/connection'
+
+module RabbitMQ
+  
+  # A {Client} holds a connection to a RabbitMQ server and has facilities
+  # for sending events to and handling received events from that server.
+  #
+  # A {Client} is not threadsafe; both the {Client} and any {Channel}s linked
+  # to it should not be shared between threads. If they are shared without
+  # appropriate locking mechanisms, the behavior is undefined and might result
+  # in catastrophic process failures like segmentation faults in the underlying
+  # C library. A {Client} can be safely used in a multithreaded application by
+  # only passing control and message data between threads.
+  #
+  # To use a {Client} effectively, it is necessary to understand the
+  # methods available in the underlying AMQP protocol. Please refer to
+  # the protocol documentation for more information about specific methods:
+  # http://www.rabbitmq.com/amqp-0-9-1-reference.html
+  #
+  class Client
+    
+    # Create a new {Client} instance with the given properties.
+    # There are several ways to convey connection info:
+    #
+    # @example with a URL string
+    #  RabbitMQ::Client.new("amqp://user:password@host:1234/vhost")
+    #
+    # @example with explicit options
+    #  RabbitMQ::Client.new(user: "user", password: "password", port: 1234)
+    #
+    # @example with both URL string and explicit options
+    #  RabbitMQ::Client.new("amqp://host:1234", user: "user", password: "password")
+    #
+    # Parsed options from a URL will be applied first, then any options given
+    # explicitly will override those parsed. If any options are ambiguous, they
+    # will have the default values:
+    #   {
+    #     user:           "guest",
+    #     password:       "guest",
+    #     host:           "localhost",
+    #     vhost:          "/",
+    #     port:           5672,
+    #     ssl:            false,
+    #     max_channels:   RabbitMQ::FFI::CHANNEL_MAX_ID, # absolute maximum
+    #     max_frame_size: 131072,
+    #   }
+    #
+    def initialize(*args)
+      @conn = Connection.new(*args)
+      
+      @open_channels     = {}
+      @released_channels = {}
+      @event_handlers    = Hash.new { |h,k| h[k] = {} }
+      @incoming_events   = Hash.new { |h,k| h[k] = {} }
+      
+      @protocol_timeout  = DEFAULT_PROTOCOL_TIMEOUT
+    end
+    
+    # Initiate the connection with the server. It is necessary to call this
+    # before any other communication, including creating a {#channel}. 
+    def start
+      close # Close if already open
+      @conn.start
+      self
+    end
+    
+    # Gracefully close the connection with the server. This will
+    # be done automatically on garbage collection if not called explicitly.
+    def close
+      @conn.close
+      release_all_channels
+      self
+    end
+    
+    # Free the native resources associated with this object. This will
+    # be done automatically on garbage collection if not called explicitly.
+    def destroy
+      @conn.destroy
+      self
+    end
+    
+    # The timeout to use when waiting for protocol events, in seconds.
+    # By default, this has the value of {DEFAULT_PROTOCOL_TIMEOUT}.
+    # When set, it affects operations like {#fetch_response} and {#run_loop!}.
+    attr_accessor :protocol_timeout
+    DEFAULT_PROTOCOL_TIMEOUT = 30 # seconds
+    
+    def user;           @conn.options.fetch(:user);           end
+    def password;       @conn.options.fetch(:password);       end
+    def host;           @conn.options.fetch(:host);           end
+    def vhost;          @conn.options.fetch(:vhost);          end
+    def port;           @conn.options.fetch(:port);           end
+    def ssl?;           @conn.options.fetch(:ssl);            end
+    def max_channels;   @conn.options.fetch(:max_channels);   end
+    def max_frame_size; @conn.options.fetch(:max_frame_size); end
+    
+    # Send a request on the given channel with the given type and properties.
+    #
+    # @param channel_id [Integer] The channel number to send on.
+    # @param method [Symbol] The type of protocol method to send.
+    # @param properties [Hash] The properties to apply to the method.
+    # @raise [RabbitMQ::FFI::Error] if a library exception occurs.
+    #
+    def send_request(channel_id, method, properties={})
+      Util.error_check :"sending a request",
+        @conn.send_method(Integer(channel_id), method.to_sym, properties)
+      
+      nil
+    end
+    
+    # Wait for a specific response on the given channel of the given type
+    # and return the event data for the response when it is received.
+    # Any other events received will be processed or stored internally.
+    #
+    # @param channel_id [Integer] The channel number to watch for.
+    # @param method [Symbol,Array<Symbol>] The protocol method(s) to watch for.
+    # @param timeout [Float] The maximum time to wait for a response in seconds;
+    #   uses the value of {#protocol_timeout} by default.
+    # @raise [RabbitMQ::ServerError] if any error event is received.
+    # @raise [RabbitMQ::FFI::Error::Timeout] if no event is received.
+    # @raise [RabbitMQ::FFI::Error] if a library exception occurs.
+    # @return [Hash] the response data received.
+    #
+    def fetch_response(channel_id, method, timeout: protocol_timeout)
+      methods = Array(method).map(&:to_sym)
+      timeout = Float(timeout) if timeout
+      fetch_response_internal(Integer(channel_id), methods, timeout)
+    end
+    
+    # Register a handler for events on the given channel of the given type.
+    # Only one handler for each event type may be registered at a time.
+    # If no callable or block is given, the handler will be cleared.
+    #
+    # @param channel_id [Integer] The channel number to watch for.
+    # @param method [Symbol] The type of protocol method to watch for.
+    # @param callable [#call,nil] The callable handler if no block is given.
+    # @param block [Proc,nil] The handler block to register.
+    # @return [Proc,#call,nil] The given block or callable.
+    # @yieldparam event [Hash] The event passed to the handler.
+    #
+    def on_event(channel_id, method, callable=nil, &block)
+      handler = block || callable
+      raise ArgumentError, "expected block or callable as the event handler" \
+        unless handler.respond_to?(:call)
+      
+      @event_handlers[Integer(channel_id)][method.to_sym] = handler
+      handler
+    end
+    
+    # Unregister the event handler associated with the given channel and method.
+    #
+    # @param channel_id [Integer] The channel number to watch for.
+    # @param method [Symbol] The type of protocol method to watch for.
+    # @return [Proc,nil] This removed handler, if any.
+    #
+    def clear_event_handler(channel_id, method)
+      @event_handlers[Integer(channel_id)].delete(method.to_sym)
+    end
+    
+    # Fetch and handle events in a loop that blocks the calling thread.
+    # The loop will continue until the {#break!} method is called from within
+    # an event handler, or until the given timeout duration has elapsed.
+    #
+    # @param timeout [Float] the maximum time to run the loop, in seconds;
+    #   if none is given, the value is {#protocol_timeout} or until {#break!}
+    # @param block [Proc,nil] if given, the block will be yielded each
+    #   non-exception event received on any channel. Other handlers or
+    #   response fetchings that match the event will still be processed,
+    #   as the block does not consume the event or replace the handlers.
+    # @return [undefined] assume no value - reserved for future use.
+    #
+    def run_loop!(timeout: protocol_timeout, &block)
+      timeout = Float(timeout) if timeout
+      @breaking = false
+      fetch_events(timeout, &block)
+      nil
+    end
+    
+    # Stop iterating from within an execution of the {#run_loop!} method.
+    # Call this method only from within an event handler.
+    # It will take effect only after the handler finishes running.
+    #
+    # @return [nil]
+    #
+    def break!
+      @breaking = true
+      nil
+    end
+    
+    # Open a new channel of communication and return a new {Channel} object
+    # with convenience methods for communicating on that channel. The
+    # channel will be automatically released if the {Channel} instance is
+    # garbage collected, or if the {Client} connection is {#close}d.
+    #
+    # @param id [Integer,nil] The channel id number to use. If nil or not
+    #   given, a unique channel number will be chosen automatically.
+    # @raise [ArgumentError] If the given channel id number is not unique or
+    #   if the given channel id number is greater than {#max_channels}.
+    # @return [Channel] The new channel handle.
+    #
+    def channel(id=nil)
+      id = allocate_channel(id)
+      finalizer = Proc.new { release_channel(id) }
+      Channel.new(self, @conn, id, finalizer)
+    end
+    
+    # Open the specified channel.
+    private def open_channel(id)
+      Util.error_check :"opening a new channel",
+        @conn.send_method(id, :channel_open)
+      
+      fetch_response(id, :channel_open_ok)
+    end
+    
+    # Re-open the specified channel after unexpected closure.
+    private def reopen_channel(id)
+      Util.error_check :"acknowledging server-initated channel closure",
+        @conn.send_method(id, :channel_close_ok)
+      
+      Util.error_check :"reopening channel after server-initated closure",
+        @conn.send_method(id, :channel_open)
+      
+      fetch_response(id, :channel_open_ok)
+    end
+    
+    # Verify or choose a channel id number that is available for use.
+    private def allocate_channel(id=nil)
+      if id
+        id = Integer(id)
+        raise ArgumentError, "channel #{id} is already in use" if @open_channels[id]
+      elsif @released_channels.empty?
+        id = (@open_channels.keys.sort.last || 0) + 1
+      else
+        id = @released_channels.keys.first
+      end
+      raise ArgumentError, "channel #{id} is too high" if id > max_channels
+      
+      already_open = @released_channels.delete(id)
+      open_channel(id) unless already_open
+      
+      @open_channels[id] = true
+      @event_handlers[id] ||= {}
+      
+      id
+    end
+    
+    # Release the given channel id to be reused later and clear its handlers.
+    private def release_channel(id)
+      @open_channels.delete(id)
+      @event_handlers.delete(id)
+      @released_channels[id] = true
+    end
+    
+    # Release all channel ids to be reused later.
+    private def release_all_channels
+      @open_channels.clear
+      @event_handlers.clear
+      @released_channels.clear
+    end
+    
+    # Execute the handler for this type of event, if any.
+    private def handle_incoming_event(event)
+      if (handlers = @event_handlers[event.fetch(:channel)])
+        if (handler = (handlers[event.fetch(:method)]))
+          handler.call(event)
+        end
+      end
+    end
+    
+    # Store the event in short-term storage for retrieval by fetch_response.
+    # If another event is received with the same method name, it will
+    # overwrite this one - fetch_response gets the latest or next by method.
+    # Raises an exception if the incoming event is an error condition.
+    private def store_incoming_event(event)
+      method  = event.fetch(:method)
+      
+      case method
+      when :channel_close
+        raise_if_server_error!(event)
+      when :connection_close
+        raise_if_server_error!(event)
+      else
+        @incoming_events[event.fetch(:channel)][method] = event
+      end
+    end
+    
+    # Raise an exception if the incoming event is an error condition.
+    # Also takes action to reopen the channel or close the connection.
+    private def raise_if_server_error!(event)
+      if (exc = ServerError.from(event))
+        if exc.is_a?(ServerError::ChannelError)
+          reopen_channel(event.fetch(:channel)) # recover by reopening the channel
+        elsif exc.is_a?(ServerError::ConnectionError)
+          close # can't recover here - close and let the user recover manually
+        end
+        raise exc
+      end
+    end
+    
+    # Internal implementation of the {#run_loop!} method.
+    private def fetch_events(timeout=protocol_timeout, start=Time.now)
+      @conn.garbage_collect
+      
+      while (event = @conn.fetch_next_event(timeout, start))
+        handle_incoming_event(event)
+        store_incoming_event(event)
+        yield event if block_given?
+        break if @breaking
+      end
+    end
+    
+    # Internal implementation of the {#fetch_response} method.
+    private def fetch_response_internal(channel_id, methods, timeout=protocol_timeout, start=Time.now)
+      methods.each { |method|
+        found = @incoming_events[channel_id].delete(method)
+        return found if found
+      }
+      
+      @conn.garbage_collect_channel(channel_id)
+      
+      while (event = @conn.fetch_next_event(timeout, start))
+        handle_incoming_event(event)
+        return event if channel_id == event.fetch(:channel) \
+                     && methods.include?(event.fetch(:method))
+        store_incoming_event(event)
+      end
+      
+      raise FFI::Error::Timeout, "waiting for response"
+    end
+  end
+end