mongo 0.17.1 → 0.18

data/README.rdoc

@@ -1,34 +1,33 @@
 = Introduction
 
-This is a Ruby driver for MongoDB[http://www.mongodb.org].
+This is the 10gen-supported Ruby driver for MongoDB[http://www.mongodb.org].
 
-Here is a quick code sample. See the files in the "examples" subdirectory for
-many more.
+Here is a quick code sample. See the MongoDB Ruby Tutorial
+(http://www.mongodb.org/display/DOCS/Ruby+Tutorial) for much more.
 
+  require 'rubygems'
   require 'mongo'
-
   include Mongo
 
-  db = Connection.new('localhost').db('sample-db')
-  coll = db.collection('test')
-
-  coll.remove
-  3.times { |i| coll.insert({'a' => i+1}) }
-  puts "There are #{coll.count()} records. Here they are:"
-  coll.find().each { |doc| puts doc.inspect }
+  @db   = Connection.new.db('sample-db')
+  @coll = db.collection('test')
 
-This driver also includes an implementation of a GridStore class, a Ruby
-interface to Mongo's GridFS storage.
+  @coll.remove
+  3.times do |i| 
+    @coll.insert({'a' => i+1})
+  end
+  puts "There are #{@coll.count()} records. Here they are:"
+  @coll.find().each { |doc| puts doc.inspect }
 
 = Installation
 
 The driver's gems are hosted on Gemcutter[http://gemcutter.org]. If you haven't
-installed a gem from Gemcutter before you'll need to set up Gemcutter first
+installed a gem from Gemcutter before, you'll need to set up Gemcutter first:
 
   $ gem install gemcutter
   $ gem tumble
 
-If (or once) you have Gemcutter setup, install the "mongo" gem by typing
+Once you've installed Gemcutter, install the mongo gem as follows:
 
   $ gem install mongo
 
@@ -54,11 +53,14 @@ That's all there is to it!
 
 = Examples
 
-There are many examples in the "examples" subdirectory. Samples include using
-the driver and using the GridFS class GridStore. Mongo must be running for
+For extensive examples, see the MongoDB Ruby Tutorial
+(http://www.mongodb.org/display/DOCS/Ruby+Tutorial).
+
+Bundled with the dirver are many examples in the "examples" subdirectory. Samples include using
+the driver and using the GridFS class GridStore. MongoDB must be running for
 these examples to work, of course.
 
-Here's how to start mongo and run the "simple.rb" example:
+Here's how to start MongoDB and run the "simple.rb" example:
 
   $ cd path/to/mongo
   $ ./mongod run
@@ -68,33 +70,15 @@ Here's how to start mongo and run the "simple.rb" example:
 
 See also the test code, especially test/test_db_api.rb.
 
-= The Driver
-
-Here is some simple example code:
-
-  require 'rubygems'        # not required for Ruby 1.9
-  require 'mongo'
-
-  include Mongo
-  db = Connection.new.db('my-db-name')
-  things = db.collection('things')
-
-  things.remove
-  things.insert('a' => 42)
-  things.insert('a' => 99, 'b' => Time.now)
-  puts things.count                               # => 2
-  puts things.find('a' => 42).next_object.inspect # {"a"=>42}
-
-
 = GridStore
 
-The GridStore class is a Ruby implementation of Mongo's GridFS file storage
-system. An instance of GridStore is like an IO object. See the rdocs for
+The GridStore class is a Ruby implementation of MongoDB's GridFS file storage
+system. An instance of GridStore is like an IO object. See the RDocs for
 details, and see examples/gridfs.rb for code that uses many of the GridStore
-features like metadata, content type, rewind/seek/tell, etc.
+features (metadata, content type, rewind/seek/tell, etc).
 
 Note that the GridStore class is not automatically required when you require
-'mongo'. You need to require 'mongo/gridfs'.
+'mongo'. You also need to require 'mongo/gridfs'
 
 Example code:
 
@@ -112,12 +96,31 @@ Example code:
   }
 
 
-
 = Notes
 
 == Thread Safety
 
-mongo-ruby-driver is thread safe.
+The driver is thread safe.
+
+== Connection Pooling
+
+As of 0.18, the driver implements connection pooling. By default, only one
+socket connection will be opened to MongoDB. However, if you're running a
+multi-threaded application, you can specify a maximum pool size and a maximum
+timeout for waiting for old connections to be released to the pool.
+
+To set up a pooled connection to a single MongoDB instance:
+
+  @conn = Connection.new("localhost", 27017, :pool_size => 5, :timeout => 5)
+
+A pooled connection to a paired instance would look like this:
+
+  @conn = Connection.new({:left  => ["db1.example.com", 27017],
+                    :right => ["db2.example.com", 27017]}, nil,
+                    :pool_size => 20, :timeout => 5)
+
+Though the pooling architecure will undoubtedly evolve, it owes much credit
+to the connection pooling implementations in ActiveRecord and PyMongo.
 
 == Using with Phusion Passenger
 
@@ -255,7 +258,26 @@ If you have the source code, you can run the tests.
 
   $ rake test
 
-The tests now require shoulda and mocha.  You can install these gems as
+This will run both unit and functional tests. If you want to run these
+individually:
+
+  $ rake test:unit
+  $ rake test:functional
+
+
+If you want to test replica pairs, you can run the following tests
+individually:
+
+  $ rake test:pair_count
+  $ rake test:pair_insert
+  $ rake test:pair_query
+
+It's also possible to test replica pairs with connection pooling:
+
+  $ rake test:pooled_pair_insert
+
+
+All tests now require shoulda and mocha.  You can install these gems as
 follows:
 
   $ gem install shoulda
@@ -295,7 +317,7 @@ Then open the file html/index.html.
 
 = Release Notes
 
-See the git log comments.
+See HISTORY.
 
 = Credits
 
@@ -338,9 +360,6 @@ Cyril Mougel, cyril.mougel@gmail.com
 Jack Chen, chendo on github
 * Test case + fix for deserializing pre-epoch Time instances
 
-Kyle Banker, banker on github
-* #limit and #skip methods for Cursor instances
-
 Michael Bernstein, mrb on github
 * #sort method for Cursor instances
 
@@ -357,6 +376,9 @@ Sunny Hirai
 * Suggested hashcode fix for Mongo::ObjectID
 * Noted index ordering bug.
 
+Christos Trochalakis
+* Added map/reduce helper
+
 = License
 
  Copyright 2008-2009 10gen Inc.

data/Rakefile

@@ -19,6 +19,7 @@ desc "Test the MongoDB Ruby driver."
 task :test do
   Rake::Task['test:unit'].invoke
   Rake::Task['test:functional'].invoke
+  Rake::Task['test:pooled_threading'].invoke
 end
 
 namespace :test do 
@@ -31,6 +32,31 @@ namespace :test do
     t.test_files = FileList['test/test*.rb']
     t.verbose    = true
   end
+
+  Rake::TestTask.new(:pooled_threading) do |t|
+    t.test_files = FileList['test/threading/*.rb']
+    t.verbose    = true
+  end
+
+  Rake::TestTask.new(:pair_count) do |t|
+    t.test_files = FileList['test/replica/count_test.rb']
+    t.verbose    = true
+  end
+
+  Rake::TestTask.new(:pair_insert) do |t|
+    t.test_files = FileList['test/replica/insert_test.rb']
+    t.verbose    = true
+  end
+
+  Rake::TestTask.new(:pooled_pair_insert) do |t|
+    t.test_files = FileList['test/replica/pooled_insert_test.rb']
+    t.verbose    = true
+  end
+
+  Rake::TestTask.new(:pair_query) do |t|
+    t.test_files = FileList['test/replica/query_test.rb']
+    t.verbose    = true
+  end
 end
 
 desc "Generate documentation"

data/lib/mongo.rb

@@ -1,4 +1,4 @@
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 
 require 'mongo/types/binary'
 require 'mongo/types/code'
@@ -31,5 +31,5 @@ module Mongo
   ASCENDING = 1
   DESCENDING = -1
 
-  VERSION = "0.17.1"
+  VERSION = "0.18"
 end

data/lib/mongo/admin.rb

@@ -30,7 +30,7 @@ module Mongo
     def profiling_level
       oh = OrderedHash.new
       oh[:profile] = -1
-      doc = @db.db_command(oh)
+      doc = @db.command(oh)
       raise "Error with profile command: #{doc.inspect}" unless @db.ok?(doc) && doc['was'].kind_of?(Numeric)
       case doc['was'].to_i
       when 0
@@ -57,7 +57,7 @@ module Mongo
                      else
                        raise "Error: illegal profiling level value #{level}"
                      end
-      doc = @db.db_command(oh)
+      doc = @db.command(oh)
       raise "Error with profile command: #{doc.inspect}" unless @db.ok?(doc)
     end
 
@@ -71,7 +71,7 @@ module Mongo
     # problem or returning an interesting hash (see especially the
     # 'result' string value) if all is well.
     def validate_collection(name)
-      doc = @db.db_command(:validate => name)
+      doc = @db.command(:validate => name)
       raise "Error with validate command: #{doc.inspect}" unless @db.ok?(doc)
       result = doc['result']
       raise "Error with validation data: #{doc.inspect}" unless result.kind_of?(String)

data/lib/mongo/collection.rb

@@ -41,6 +41,7 @@ module Mongo
       end
 
       @db, @name  = db, name
+      @connection = @db.connection
       @pk_factory = pk_factory || ObjectID
       @hint = nil
     end
@@ -109,14 +110,10 @@ module Mongo
     def find(selector={}, options={})
       fields = options.delete(:fields)
       fields = ["_id"] if fields && fields.empty?
-      skip = options.delete(:offset) || nil
-      if !skip.nil?
-        warn "the :offset option to find is deprecated and will be removed. please use :skip instead"
-      end
-      skip = options.delete(:skip) || skip || 0
-      limit = options.delete(:limit) || 0
-      sort = options.delete(:sort)
-      hint = options.delete(:hint)
+      skip   = options.delete(:skip) || skip || 0
+      limit  = options.delete(:limit) || 0
+      sort   = options.delete(:sort)
+      hint   = options.delete(:hint)
       snapshot = options.delete(:snapshot)
       if options[:timeout] == false && !block_given?
         raise ArgumentError, "Timeout can be set to false only when #find is invoked with a block." 
@@ -222,17 +219,10 @@ module Mongo
       BSON.serialize_cstr(message, "#{@db.name}.#{@name}")
       message.put_int(0)
       message.put_array(BSON_SERIALIZER.serialize(selector, false).unpack("C*"))
-      @db.send_message_with_operation(Mongo::Constants::OP_DELETE, message,
+      @connection.send_message(Mongo::Constants::OP_DELETE, message,
         "db.#{@db.name}.remove(#{selector.inspect})")
     end
 
-    # Remove all records.
-    # DEPRECATED: please use Collection#remove instead.
-    def clear
-      warn "Collection#clear is deprecated. Please use Collection#remove instead."
-      remove({})
-    end
-
     # Update a single document in this collection.
     #
     # :selector :: a hash specifying elements which must be present for a document to be updated. Note: 
@@ -261,10 +251,10 @@ module Mongo
       message.put_array(BSON_SERIALIZER.serialize(selector, false).unpack("C*"))
       message.put_array(BSON_SERIALIZER.serialize(document, false).unpack("C*"))
       if options[:safe]
-        @db.send_message_with_safe_check(Mongo::Constants::OP_UPDATE, message,
+        @connection.send_message_with_safe_check(Mongo::Constants::OP_UPDATE, message, @db.name,
           "db.#{@name}.update(#{selector.inspect}, #{document.inspect})")
       else
-        @db.send_message_with_operation(Mongo::Constants::OP_UPDATE, message, 
+        @connection.send_message(Mongo::Constants::OP_UPDATE, message, 
           "db.#{@name}.update(#{selector.inspect}, #{document.inspect})")
       end
     end
@@ -308,8 +298,44 @@ module Mongo
       @db.drop_collection(@name)
     end
 
-    # Perform a query similar to an SQL group by operation.
+    # Performs a map/reduce operation on the current collection. Returns a new
+    # collection containing the results of the operation.
+    #
+    # Required:
+    # +map+    :: a map function, written in javascript.
+    # +reduce+ :: a reduce function, written in javascript.
+    #
+    # Optional:
+    # :query    :: a query selector document, like what's passed to #find, to limit
+    #              the operation to a subset of the collection.
+    # :sort     :: sort parameters passed to the query.
+    # :limit    :: number of objects to return from the collection.
+    # :finalize :: a javascript function to apply to the result set after the
+    #              map/reduce operation has finished.
+    # :out      :: the name of the output collection. if specified, the collection will not be treated as temporary.
+    # :keeptemp :: if true, the generated collection will be persisted. default is false.
+    # :verbose  :: if true, provides statistics on job execution time.
     #
+    # For more information on using map/reduce, see http://www.mongodb.org/display/DOCS/MapReduce
+    def map_reduce(map, reduce, options={})
+      map    = Code.new(map) unless map.is_a?(Code)
+      reduce = Code.new(reduce) unless reduce.is_a?(Code)
+
+      hash = OrderedHash.new
+      hash['mapreduce'] = self.name
+      hash['map'] = map
+      hash['reduce'] = reduce
+      hash.merge! options
+
+      result = @db.command(hash)
+      unless result["ok"] == 1
+        raise Mongo::OperationFailure, "map-reduce failed: #{result['errmsg']}" 
+      end
+      @db[result["result"]]
+    end
+    alias :mapreduce :map_reduce
+
+    # Performs a group query, similar to the 'SQL GROUP BY' operation.
     # Returns an array of grouped items.
     #
     # :keys :: Array of fields to group by
@@ -327,13 +353,9 @@ module Mongo
           hash[k] = 1
         end
 
-        case reduce
-        when Code
-        else
-          reduce = Code.new(reduce)
-        end
+        reduce = Code.new(reduce) unless reduce.is_a?(Code)
 
-        result = @db.db_command({"group" =>
+        result = @db.command({"group" =>
                                   {
                                     "ns" => @name,
                                     "$reduce" => reduce,
@@ -384,7 +406,7 @@ function () {
     return {"result": map.values()};
 }
 EOS
-      return @db.eval(Code.new(group_function, scope))["result"]
+      @db.eval(Code.new(group_function, scope))["result"]
     end
 
     # Returns a list of distinct values for +key+ across all
@@ -406,7 +428,7 @@ EOS
       command[:distinct] = @name
       command[:key]        = key.to_s
 
-      @db.db_command(command)["values"]
+      @db.command(command)["values"]
     end
 
     # Rename this collection.
@@ -488,10 +510,10 @@ EOS
       BSON.serialize_cstr(message, "#{@db.name}.#{collection_name}")
       documents.each { |doc| message.put_array(BSON_SERIALIZER.serialize(doc, check_keys).unpack("C*")) }
       if safe
-        @db.send_message_with_safe_check(Mongo::Constants::OP_INSERT, message,
+        @connection.send_message_with_safe_check(Mongo::Constants::OP_INSERT, message, @db.name,
           "db.#{collection_name}.insert(#{documents.inspect})")
       else
-        @db.send_message_with_operation(Mongo::Constants::OP_INSERT, message,
+        @connection.send_message(Mongo::Constants::OP_INSERT, message,
           "db.#{collection_name}.insert(#{documents.inspect})")
       end
       documents.collect { |o| o[:_id] || o['_id'] }

data/lib/mongo/connection.rb

@@ -14,98 +14,132 @@
 # limitations under the License.
 # ++
 
+require 'set'
+require 'socket'
+require 'monitor'
+
 module Mongo
 
   # A connection to MongoDB.
   class Connection
 
+    # We need to make sure that all connection abort when
+    # a ConnectionError is raised.
+    Thread.abort_on_exception = true
+
     DEFAULT_PORT = 27017
+    STANDARD_HEADER_SIZE = 16
+    RESPONSE_HEADER_SIZE = 20
+
+    attr_reader :logger, :size, :host, :port, :nodes, :sockets, :checked_out, :reserved_connections
+
+    def slave_ok? 
+      @slave_ok
+    end
+    
+    # Counter for generating unique request ids.
+    @@current_request_id = 0
 
-    # Create a Mongo database server instance. You specify either one or a
-    # pair of servers. If one, you also say if connecting to a slave is
-    # OK. In either case, the host default is "localhost" and port default
-    # is DEFAULT_PORT.
-    #
-    # If you specify a pair, pair_or_host is a hash with two keys :left
-    # and :right. Each key maps to either
-    # * a server name, in which case port is DEFAULT_PORT
-    # * a port number, in which case server is "localhost"
-    # * an array containing a server name and a port number in that order
-    #
-    # +options+ are passed on to each DB instance:
-    #
-    # :slave_ok :: Only used if one host is specified. If false, when
-    #              connecting to that host/port a DB object will check to
-    #              see if the server is the master. If it is not, an error
-    #              is thrown.
-    #
-    # :auto_reconnect :: If a DB connection gets closed (for example, we
-    #                    have a server pair and saw the "not master"
-    #                    error, which closes the connection), then
-    #                    automatically try to reconnect to the master or
-    #                    to the single server we have been given. Defaults
-    #                    to +false+.
+    # Creates a connection to MongoDB. Specify either one or a pair of servers,
+    # along with a maximum connection pool size and timeout.
+    #
+    # == Connecting
+    # If connecting to just one server, you may specify whether connection to slave is permitted.
+    # 
+    # In all cases, the default host is "localhost" and the default port, is 27017.
+    #
+    # When specifying a pair, pair_or_host, is a hash with two keys: :left and :right. Each key maps to either
+    # * a server name, in which case port is 27017,
+    # * a port number, in which case the server is "localhost", or
+    # * an array containing [server_name, port_number]
+    #
+    # === Options
+    #
+    # :slave_ok :: Defaults to +false+. Must be set to +true+ when connecting
+    #              to a single, slave node.
+    #
     # :logger :: Optional Logger instance to which driver usage information
     #            will be logged.
     #
-    # Since that's so confusing, here are a few examples:
+    # :auto_reconnect :: DEPRECATED. See http://www.mongodb.org/display/DOCS/Replica+Pairs+in+Ruby
     #
-    #  Connection.new                         # localhost, DEFAULT_PORT, !slave
-    #  Connection.new("localhost")            # localhost, DEFAULT_PORT, !slave
-    #  Connection.new("localhost", 3000)      # localhost, 3000, slave not ok
-    #  # localhost, 3000, slave ok
-    #  Connection.new("localhost", 3000, :slave_ok => true)
-    #  # localhost, DEFAULT_PORT, auto reconnect
-    #  Connection.new(nil, nil, :auto_reconnect => true)
+    # :pool_size :: The maximum number of socket connections that can be opened
+    #               that can be opened to the database.
+    #
+    # :timeout   :: When all of the connections to the pool are checked out,
+    #               this is the number of seconds to wait for a new connection
+    #               to be released before throwing an exception.
+    #                
+    #
+    # === Examples:
+    #
+    #  # localhost, 27017
+    #  Connection.new
+    #   
+    #  # localhost, 27017
+    #  Connection.new("localhost")
+    #
+    #  # localhost, 3000, max 5 connections, with max 5 seconds of wait time.
+    #  Connection.new("localhost", 3000, :pool_size => 5, :timeout => 5)
     #
-    #  # A pair of servers. DB will always talk to the master. On socket
-    #  # error or "not master" error, we will auto-reconnect to the
-    #  # current master.
-    #  Connection.new({:left  => ["db1.example.com", 3000],
-    #             :right => "db2.example.com"}, # DEFAULT_PORT
-    #            nil, :auto_reconnect => true)
+    #  # localhost, 3000, where this node may be a slave
+    #  Connection.new("localhost", 3000, :slave_ok => true)
     #
-    #  # Here, :right is localhost/DEFAULT_PORT. No auto-reconnect.
-    #  Connection.new({:left => ["db1.example.com", 3000]})
+    #  # A pair of servers. The driver will always talk to master. 
+    #  # On connection errors, Mongo::ConnectionFailure will be raised.
+    #  # See http://www.mongodb.org/display/DOCS/Replica+Pairs+in+Ruby 
+    #  Connection.new({:left  => ["db1.example.com", 27017],
+    #                  :right => ["db2.example.com", 27017]})
     #
-    # When a DB object first connects to a pair, it will find the master
-    # instance and connect to that one.
+    #  A pair of servers, with connection pooling. Not the nil param placeholder for port.
+    #  Connection.new({:left  => ["db1.example.com", 27017],
+    #                  :right => ["db2.example.com", 27017]}, nil,
+    #                  :pool_size => 20, :timeout => 5)
     def initialize(pair_or_host=nil, port=nil, options={})
-      @pair = case pair_or_host
-               when String
-                 [[pair_or_host, port ? port.to_i : DEFAULT_PORT]]
-               when Hash
-                connections = []
-                connections << pair_val_to_connection(pair_or_host[:left])
-                connections << pair_val_to_connection(pair_or_host[:right])
-                connections
-               when nil
-                 [['localhost', DEFAULT_PORT]]
-               end
-
-      @options = options
-    end
-
-    # Return the Mongo::DB named +db_name+. The slave_ok and
-    # auto_reconnect options passed in via #new may be overridden here.
-    # See DB#new for other options you can pass in.
-    def db(db_name, options={})
-      DB.new(db_name, @pair, @options.merge(options))
-    end
-    
-    def logger
-      @options[:logger]
+      @nodes = format_pair(pair_or_host)
+
+      # Host and port of current master.
+      @host = @port = nil
+      
+      # Lock for request ids.
+      @id_lock = Mutex.new
+
+      # Pool size and timeout.
+      @size      = options[:pool_size] || 1
+      @timeout   = options[:timeout]   || 1.0
+
+      # Cache of reserved sockets mapped to threads
+      @reserved_connections = {}
+
+      # Mutex for synchronizing pool access
+      @connection_mutex = Monitor.new
+
+      # Condition variable for signal and wait
+      @queue = @connection_mutex.new_cond
+
+      @sockets      = []
+      @checked_out  = []
+
+      if options[:auto_reconnect]
+        warn(":auto_reconnect is deprecated. see http://www.mongodb.org/display/DOCS/Replica+Pairs+in+Ruby")
+      end
+      
+      # Slave ok can be true only if one node is specified
+      @slave_ok = options[:slave_ok] && @nodes.length == 1
+      @logger   = options[:logger] || nil
+      @options  = options
+
+      should_connect = options[:connect].nil? ? true : options[:connect]
+      connect_to_master if should_connect
     end
 
-    # Returns a hash containing database names as keys and disk space for
-    # each as values.
+    # Returns a hash with all database names and their respective sizes on
+    # disk.
     def database_info
-      doc = single_db_command('admin', :listDatabases => 1)
-      h = {}
-      doc['databases'].each { |db|
-        h[db['name']] = db['sizeOnDisk'].to_i
-      }
-      h
+      doc = self['admin'].command(:listDatabases => 1)
+      returning({}) do |info|
+        doc['databases'].each { |db| info[db['name']] = db['sizeOnDisk'].to_i }
+      end
     end
 
     # Returns an array of database names.
@@ -113,9 +147,20 @@ module Mongo
       database_info.keys
     end
 
+    # Returns the database named +db_name+. The slave_ok and
+    # See DB#new for other options you can pass in.
+    def db(db_name, options={})
+      DB.new(db_name, self, options.merge(:logger => @logger))
+    end
+
+    # Returns the database named +db_name+.
+    def [](db_name)
+      DB.new(db_name, self, :logger => @logger)
+    end
+
     # Drops the database +name+.
     def drop_database(name)
-      single_db_command(name, :dropDatabase => 1)
+      self[name].command(:dropDatabase => 1)
     end
 
     # Copies the database +from+ on the local server to +to+ on the specified +host+.
@@ -126,22 +171,373 @@ module Mongo
       oh[:fromhost] = host
       oh[:fromdb]   = from
       oh[:todb]     = to
-      single_db_command('admin', oh)
+      self["admin"].command(oh)
+    end
+
+    # Increments and returns the next available request id.
+    def get_request_id
+      request_id = ''
+      @id_lock.synchronize do 
+        request_id = @@current_request_id += 1
+      end
+      request_id
     end
 
-    # Return the build information for the current connection.
+    # Returns the build information for the current connection.
     def server_info
       db("admin").command({:buildinfo => 1}, {:admin => true, :check_response => true})
     end
 
-    # Returns the build version of the current server, using
-    # a ServerVersion object for comparability.
+    # Gets the build version of the current server.
+    # Returns a ServerVersion object for comparability.
     def server_version
       ServerVersion.new(server_info["version"])
     end
 
-    protected
 
+    ## Connections and pooling ##
+    
+    # Sends a message to MongoDB.
+    #
+    # Takes a MongoDB opcode, +operation+, a message of class ByteBuffer,
+    # +message+, and an optional formatted +log_message+.
+    # Sends the message to the databse, adding the necessary headers.
+    def send_message(operation, message, log_message=nil)
+      @logger.debug("  MONGODB #{log_message || message}") if @logger
+      packed_message = add_message_headers(operation, message).to_s
+      socket = checkout
+      send_message_on_socket(packed_message, socket)
+      checkin(socket)
+    end
+
+    # Sends a message to the database, waits for a response, and raises
+    # and exception if the operation has failed.
+    #
+    # Takes a MongoDB opcode, +operation+, a message of class ByteBuffer,
+    # +message+, the +db_name+, and an optional formatted +log_message+.
+    # Sends the message to the databse, adding the necessary headers.
+    def send_message_with_safe_check(operation, message, db_name, log_message=nil)
+      message_with_headers = add_message_headers(operation, message)
+      message_with_check   = last_error_message(db_name)
+      @logger.debug("  MONGODB #{log_message || message}") if @logger
+      sock = checkout
+      packed_message = message_with_headers.append!(message_with_check).to_s
+      send_message_on_socket(packed_message, sock)
+      docs, num_received, cursor_id = receive(sock)
+      checkin(sock)
+      if num_received == 1 && error = docs[0]['err']
+        raise Mongo::OperationFailure, error
+      end
+      [docs, num_received, cursor_id]
+    end
+
+    # Sends a message to the database and waits for the response.
+    #
+    # Takes a MongoDB opcode, +operation+, a message of class ByteBuffer,
+    # +message+, and an optional formatted +log_message+. This method 
+    # also takes an options socket for internal use with #connect_to_master.
+    def receive_message(operation, message, log_message=nil, socket=nil)
+      packed_message = add_message_headers(operation, message).to_s
+      @logger.debug("  MONGODB #{log_message || message}") if @logger
+      sock = socket || checkout
+
+      send_message_on_socket(packed_message, sock)
+      result = receive(sock)
+      checkin(sock)
+      result
+    end
+
+    # Creates a new socket and tries to connect to master.
+    # If successful, sets @host and @port to master and returns the socket.
+    def connect_to_master
+      close
+      @host = @port = nil
+      for node_pair in @nodes
+        host, port = *node_pair
+        begin
+          socket = TCPSocket.new(host, port)
+          socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+
+          # If we're connected to master, set the @host and @port
+          result = self['admin'].command({:ismaster => 1}, false, false, socket)
+          if result['ok'] == 1 && ((is_master = result['ismaster'] == 1) || @slave_ok)
+            @host, @port = host, port
+          end
+
+          # Note: slave_ok can be true only when connecting to a single node.
+          if @nodes.length == 1 && !is_master && !@slave_ok
+            raise ConfigurationError, "Trying to connect directly to slave; " +
+              "if this is what you want, specify :slave_ok => true."
+          end
+
+          break if is_master || @slave_ok
+        rescue SocketError, SystemCallError, IOError => ex
+          socket.close if socket
+          false
+        end
+      end 
+      raise ConnectionFailure, "failed to connect to any given host:port" unless socket
+    end
+
+    # Are we connected to MongoDB? This is determined by checking whether
+    # @host and @port have values, since they're set to nil on calls to #close.
+    def connected?
+      @host && @port
+    end
+
+    # Close the connection to the database.
+    def close
+      @sockets.each do |sock|
+        sock.close
+      end
+      @host = @port = nil
+      @sockets.clear   
+      @checked_out.clear
+      @reserved_connections.clear
+    end
+
+    private
+
+    # Get a socket from the pool, mapped to the current thread.
+    def checkout
+      #return @socket ||= checkout_new_socket if @size == 1
+      if sock = @reserved_connections[Thread.current.object_id]
+        sock
+      else
+        sock = obtain_socket
+        @reserved_connections[Thread.current.object_id] = sock
+      end
+      sock
+    end
+
+    # Return a socket to the pool.
+    def checkin(socket)
+      @connection_mutex.synchronize do 
+        @reserved_connections.delete Thread.current.object_id
+        @checked_out.delete(socket)
+        @queue.signal
+      end
+      true
+    end
+
+    # Releases the connection for any dead threads.
+    # Called when the connection pool grows too large to free up more sockets.
+    def clear_stale_cached_connections!
+      keys = @reserved_connections.keys
+
+      Thread.list.each do |thread|
+        keys.delete(thread.object_id) if thread.alive?
+      end
+      
+      keys.each do |key|
+        next unless @reserved_connections.has_key?(key)
+        checkin(@reserved_connections[key])
+        @reserved_connections.delete(key)
+      end
+    end
+
+    # Adds a new socket to the pool and checks it out.
+    #
+    # This method is called exclusively from #obtain_socket;
+    # therefore, it runs within a mutex, as it must.
+    def checkout_new_socket
+      begin
+      socket = TCPSocket.new(@host, @port)
+      socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+      rescue => ex
+        raise ConnectionFailure, "Failed to connect socket: #{ex}"
+      end
+      @sockets << socket
+      @checked_out << socket
+      socket
+    end
+
+    # Checks out the first available socket from the pool.
+    #
+    # This method is called exclusively from #obtain_socket;
+    # therefore, it runs within a mutex, as it must.
+    def checkout_existing_socket
+      socket = (@sockets - @checked_out).first
+      @checked_out << socket
+      socket
+    end
+
+    # Check out an existing socket or create a new socket if the maximum
+    # pool size has not been exceeded. Otherwise, wait for the next
+    # available socket.
+    def obtain_socket
+      @connection_mutex.synchronize do 
+        connect_to_master if !connected?
+
+        loop do 
+          socket = if @checked_out.size < @sockets.size
+                     checkout_existing_socket
+                   elsif @sockets.size < @size
+                     checkout_new_socket
+                   end
+
+          return socket if socket
+
+          # Try to clear out any stale threads to free up some connections
+          clear_stale_cached_connections!
+          next if @checked_out.size < @sockets.size
+
+          # Otherwise, wait.
+          if wait
+            next
+          else
+
+            # Try to clear stale threads once more before failing.
+            clear_stale_cached_connections!
+            if @size == @sockets.size
+              raise ConnectionTimeoutError, "could not obtain connection within " +
+                "#{@timeout} seconds. The max pool size is currently #{@size}; " +
+                "consider increasing it."
+            end
+          end  # if
+        end # loop
+      end # synchronize
+    end
+
+    if RUBY_VERSION >= '1.9'
+      # Ruby 1.9's Condition Variables don't support timeouts yet;
+      # until they do, we'll make do with this hack. 
+      def wait
+        Timeout.timeout(@timeout) do 
+          @queue.wait
+        end
+      end
+    else
+      def wait
+        @queue.wait(@timeout)
+      end
+    end
+
+    def receive(sock)
+      receive_header(sock)
+      number_received, cursor_id = receive_response_header(sock)
+      read_documents(number_received, cursor_id, sock)
+    end
+
+    def receive_header(sock)
+      header = ByteBuffer.new
+      header.put_array(receive_message_on_socket(16, sock).unpack("C*"))
+      unless header.size == STANDARD_HEADER_SIZE
+        raise "Short read for DB response header: " +
+          "expected #{STANDARD_HEADER_SIZE} bytes, saw #{header.size}" 
+      end
+      header.rewind
+      size        = header.get_int
+      request_id  = header.get_int
+      response_to = header.get_int
+      op          = header.get_int
+    end
+
+    def receive_response_header(sock)
+      header_buf = ByteBuffer.new
+      header_buf.put_array(receive_message_on_socket(RESPONSE_HEADER_SIZE, sock).unpack("C*"))
+      if header_buf.length != RESPONSE_HEADER_SIZE
+        raise "Short read for DB response header; " +
+          "expected #{RESPONSE_HEADER_SIZE} bytes, saw #{header_buf.length}"
+      end
+      header_buf.rewind
+      result_flags     = header_buf.get_int
+      cursor_id        = header_buf.get_long
+      starting_from    = header_buf.get_int
+      number_remaining = header_buf.get_int
+      [number_remaining, cursor_id]
+    end
+
+    def read_documents(number_received, cursor_id, sock)
+      docs = []
+      number_remaining = number_received
+      while number_remaining > 0 do
+        buf = ByteBuffer.new
+        buf.put_array(receive_message_on_socket(4, sock).unpack("C*"))
+        buf.rewind
+        size = buf.get_int
+        buf.put_array(receive_message_on_socket(size - 4, sock).unpack("C*"), 4)
+        number_remaining -= 1
+        buf.rewind
+        docs << BSON.new.deserialize(buf)
+      end
+      [docs, number_received, cursor_id]
+    end
+
+    def last_error_message(db_name)
+      message = ByteBuffer.new
+      message.put_int(0)
+      BSON.serialize_cstr(message, "#{db_name}.$cmd")
+      message.put_int(0)
+      message.put_int(-1)
+      message.put_array(BSON_SERIALIZER.serialize({:getlasterror => 1}, false).unpack("C*"))
+      add_message_headers(Mongo::Constants::OP_QUERY, message)
+    end
+    
+    # Prepares a message for transmission to MongoDB by
+    # constructing a valid message header.
+    def add_message_headers(operation, message)
+      headers = ByteBuffer.new
+
+      # Message size.
+      headers.put_int(16 + message.size)
+
+      # Unique request id.
+      headers.put_int(get_request_id)
+
+      # Response id.
+      headers.put_int(0)
+
+      # Opcode.
+      headers.put_int(operation)
+      message.prepend!(headers)
+    end
+
+    # Low-level method for sending a message on a socket.
+    # Requires a packed message and an available socket, 
+    def send_message_on_socket(packed_message, socket)
+      begin
+      socket.send(packed_message, 0)
+      rescue => ex
+        close
+        raise ConnectionFailure, "Operation failed with the following exception: #{ex}"
+      end
+    end
+
+    # Low-level method for receiving data from socket.
+    # Requires length and an available socket.
+    def receive_message_on_socket(length, socket)
+      message = ""
+      begin
+        while message.length < length do
+          chunk = socket.recv(length - message.length)
+          raise ConnectionFailure, "connection closed" unless chunk.length > 0
+          message += chunk
+        end
+        rescue => ex
+          raise ConnectionFailure, "Operation failed with the following exception: #{ex}"
+      end
+      message
+    end
+
+
+    ## Private helper methods
+
+    # Returns an array of host-port pairs.
+    def format_pair(pair_or_host)
+      case pair_or_host
+        when String
+          [[pair_or_host, port ? port.to_i : DEFAULT_PORT]]
+        when Hash
+         connections = []
+         connections << pair_val_to_connection(pair_or_host[:left])
+         connections << pair_val_to_connection(pair_or_host[:right])
+         connections
+        when nil
+          [['localhost', DEFAULT_PORT]]
+      end
+    end
+    
     # Turns an array containing a host name string and a
     # port number integer into a [host, port] pair array.
     def pair_val_to_connection(a)
@@ -157,19 +553,5 @@ module Mongo
       end
     end
 
-    # Send cmd (a hash, possibly ordered) to the admin database and return
-    # the answer. Raises an error unless the return is "ok" (DB#ok?
-    # returns +true+).
-    def single_db_command(db_name, cmd)
-      db = nil
-      begin
-        db = db(db_name)
-        doc = db.db_command(cmd)
-        raise "error retrieving database info: #{doc.inspect}" unless db.ok?(doc)
-        doc
-      ensure
-        db.close if db
-      end
-    end
   end
 end