mongo 0.18.2 → 0.18.3

data/lib/mongo/connection.rb

@@ -20,11 +20,10 @@ require 'thread'
 
 module Mongo
 
-  # A connection to MongoDB.
+  # Instantiates and manages connections to MongoDB.
   class Connection
 
-    # We need to make sure that all connection abort when
-    # a ConnectionError is raised.
+    # Abort connections if a ConnectionError is raised.
     Thread.abort_on_exception = true
 
     DEFAULT_PORT = 27017
@@ -33,70 +32,59 @@ module Mongo
 
     attr_reader :logger, :size, :host, :port, :nodes, :sockets, :checked_out
 
-    def slave_ok?
-      @slave_ok
-    end
-
     # Counter for generating unique request ids.
     @@current_request_id = 0
 
-    # Creates a connection to MongoDB. Specify either one or a pair of servers,
+    # Create 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.
     #
-    # 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
+    # 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.
-    #
-    # :auto_reconnect :: DEPRECATED. See http://www.mongodb.org/display/DOCS/Replica+Pairs+in+Ruby
-    #
-    # :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.
-    #
     # Note that there are a few issues when using connection pooling with Ruby 1.9 on Windows. These
     # should be resolved in the next release.
     #
-    # === Examples:
+    # @param [String, Hash] pair_or_host See explanation above.
+    # @param [Integer] port specify a port number here if only one host is being specified. Leave nil if
+    #   specifying a pair of servers in +pair_or_host+.
     #
-    #  # localhost, 27017
-    #  Connection.new
+    # @option options [Boolean] :slave_ok (false) Must be set to +true+ when connecting
+    #   to a single, slave node.
+    # @option options [Logger, #debug] :logger (nil) Logger instance to receive driver operation log.
+    # @option options [Boolean] :auto_reconnect DEPRECATED. See http://www.mongodb.org/display/DOCS/Replica+Pairs+in+Ruby
+    # @option options [Integer] :pool_size (1) The maximum number of socket connections that can be opened to the database.
+    # @option options [Float] :timeout (5.0) 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.
     #
-    #  # 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)
+    # @example localhost, 27017
+    #   Connection.new
     #
-    #  # localhost, 3000, where this node may be a slave
-    #  Connection.new("localhost", 3000, :slave_ok => true)
+    # @example localhost, 27017
+    #   Connection.new("localhost")
     #
-    #  # 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],
+    # @example localhost, 3000, max 5 connections, with max 5 seconds of wait time.
+    #   Connection.new("localhost", 3000, :pool_size => 5, :timeout => 5)
+    #
+    # @example localhost, 3000, where this node may be a slave
+    #   Connection.new("localhost", 3000, :slave_ok => true)
+    #
+    # @example A pair of servers. The driver will always talk to master.
+    #   # On connection errors, Mongo::ConnectionFailure will be raised.
+    #   Connection.new({:left  => ["db1.example.com", 27017],
     #                  :right => ["db2.example.com", 27017]})
     #
-    #  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)
+    # @example A pair of servers with connection pooling enabled. Note the nil param placeholder for port.
+    #   Connection.new({:left  => ["db1.example.com", 27017],
+    #                   :right => ["db2.example.com", 27017]}, nil,
+    #                   :pool_size => 20, :timeout => 5)
+    #
+    # @see http://www.mongodb.org/display/DOCS/Replica+Pairs+in+Ruby Replica pairs in Ruby
     def initialize(pair_or_host=nil, port=nil, options={})
       @nodes = format_pair(pair_or_host, port)
 
@@ -124,7 +112,7 @@ module Mongo
         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 can be true only if one node is specified
       @slave_ok = options[:slave_ok] && @nodes.length == 1
       @logger   = options[:logger] || nil
       @options  = options
@@ -133,8 +121,10 @@ module Mongo
       connect_to_master if should_connect
     end
 
-    # Returns a hash with all database names and their respective sizes on
-    # disk.
+    # Return a hash with all database names
+    # and their respective sizes on disk.
+    #
+    # @return [Hash]
     def database_info
       doc = self['admin'].command(:listDatabases => 1)
       returning({}) do |info|
@@ -142,39 +132,57 @@ module Mongo
       end
     end
 
-    # Returns an array of database names.
+    # Return an array of database names.
+    #
+    # @return [Array]
     def database_names
       database_info.keys
     end
 
-    # Returns the database named +db_name+. The slave_ok and
-    # See DB#new for other options you can pass in.
+    # Return a database with the given name.
+    # See DB#new for valid options hash parameters.
+    #
+    # @param [String] db_name a valid database name.
+    #
+    # @return [Mongo::DB]
     def db(db_name, options={})
       DB.new(db_name, self, options.merge(:logger => @logger))
     end
 
-    # Returns the database named +db_name+.
+    # Shortcut for returning a database. Use DB#db to accept options.
+    #
+    # @param [String] db_name a valid database name.
+    #
+    # @return [Mongo::DB]
     def [](db_name)
       DB.new(db_name, self, :logger => @logger)
     end
 
-    # Drops the database +name+.
+    # Drop a database.
+    #
+    # @param [String] name name of an existing database.
     def drop_database(name)
       self[name].command(:dropDatabase => 1)
     end
 
-    # Copies the database +from+ on the local server to +to+ on the specified +host+.
+    # Copy the database +from+ on the local server to +to+ on the specified +host+.
     # +host+ defaults to 'localhost' if no value is provided.
-    def copy_database(from, to, host="localhost")
+    #
+    # @param [String] from name of the database to copy from.
+    # @param [String] to name of the database to copy to.
+    # @param [String] from_host host of the 'from' database.
+    def copy_database(from, to, from_host="localhost")
       oh = OrderedHash.new
       oh[:copydb]   = 1
-      oh[:fromhost] = host
+      oh[:fromhost] = from_host
       oh[:fromdb]   = from
       oh[:todb]     = to
       self["admin"].command(oh)
     end
 
-    # Increments and returns the next available request id.
+    # Increment and return the next available request id.
+    #
+    # return [Integer]
     def get_request_id
       request_id = ''
       @id_lock.synchronize do
@@ -183,51 +191,75 @@ module Mongo
       request_id
     end
 
-    # Returns the build information for the current connection.
+    # Get the build information for the current connection.
+    #
+    # @return [Hash]
     def server_info
       db("admin").command({:buildinfo => 1}, {:admin => true, :check_response => true})
     end
 
-    # Gets the build version of the current server.
-    # Returns a ServerVersion object for comparability.
+    # Get the build version of the current server.
+    #
+    # @return [Mongo::ServerVersion]
+    #   object allowing easy comparability of version.
     def server_version
       ServerVersion.new(server_info["version"])
     end
 
+    # Is it okay to connect to a slave?
+    #
+    # @return [Boolean]
+    def slave_ok?
+      @slave_ok
+    end
+
 
     ## Connections and pooling ##
 
-    # Sends a message to MongoDB.
+    # Send a message to MongoDB, adding the necessary headers.
     #
-    # 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.
+    # @param [Integer] operation a MongoDB opcode.
+    # @param [ByteBuffer] message a message to send to the database.
+    # @param [String] log_message text version of +message+ for logging.
+    #
+    # @return [True]
     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)
+      begin
+        packed_message = add_message_headers(operation, message).to_s
+        socket = checkout
+        send_message_on_socket(packed_message, socket)
+      ensure
+        checkin(socket)
+      end
     end
 
     # Sends a message to the database, waits for a response, and raises
     # an 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 database, adding the necessary headers.
+    # @param [Integer] operation a MongoDB opcode.
+    # @param [ByteBuffer] message a message to send to the database.
+    # @param [String] db_name the name of the database. used on call to get_last_error.
+    # @param [String] log_message text version of +message+ for logging.
+    #
+    # @return [Array]
+    #   An array whose indexes include [0] documents returned, [1] number of document received,
+    #   and [3] a cursor_id.
     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
-      docs = num_received = cursor_id = ''
-      @safe_mutex.synchronize do
-        send_message_on_socket(packed_message, sock)
-        docs, num_received, cursor_id = receive(sock)
+      begin
+        sock = checkout
+        packed_message = message_with_headers.append!(message_with_check).to_s
+        docs = num_received = cursor_id = ''
+        @safe_mutex.synchronize do
+          send_message_on_socket(packed_message, sock)
+          docs, num_received, cursor_id = receive(sock)
+        end
+      ensure
+        checkin(sock)
       end
-      checkin(sock)
       if num_received == 1 && error = docs[0]['err']
         raise Mongo::OperationFailure, error
       end
@@ -236,25 +268,35 @@ module Mongo
 
     # 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.
+    # @param [Integer] operation a MongoDB opcode.
+    # @param [ByteBuffer] message a message to send to the database.
+    # @param [String] log_message text version of +message+ for logging.
+    # @param [Socket] socket a socket to use in lieu of checking out a new one.
+    #
+    # @return [Array]
+    #   An array whose indexes include [0] documents returned, [1] number of document received,
+    #   and [3] a cursor_id.
     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
+      begin
+        sock = socket || checkout
 
-      result = ''
-      @safe_mutex.synchronize do
-        send_message_on_socket(packed_message, sock)
-        result = receive(sock)
+        result = ''
+        @safe_mutex.synchronize do
+          send_message_on_socket(packed_message, sock)
+          result = receive(sock)
+        end
+      ensure
+        checkin(sock)
       end
-      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.
+    # Create a new socket and attempt to connect to master.
+    # If successful, sets host and port to master and returns the socket.
+    #
+    # @raise [ConnectionFailure] if unable to connect to any host or port.
     def connect_to_master
       close
       @host = @port = nil
@@ -286,7 +328,7 @@ module Mongo
     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.
+    # host and port have values, since they're set to nil on calls to #close.
     def connected?
       @host && @port
     end
@@ -361,6 +403,9 @@ module Mongo
           return socket if socket
 
           # Otherwise, wait
+          if @logger
+            @logger.warn "Waiting for available connection; #{@checked_out.size} of #{@size} connections checked out."
+          end
           @queue.wait(@connection_mutex)
         end
       end

data/lib/mongo/cursor.rb

@@ -25,7 +25,10 @@ module Mongo
 
     # Create a new cursor.
     #
-    # Should not be called directly by application developers.
+    # Note: cursors are created when executing queries using [Collection#find] and other
+    # similar methods. Application developers shouldn't have to create cursors manually.
+    #
+    # @return [Cursor]
     def initialize(collection, options={})
       @db         = collection.db
       @collection = collection
@@ -49,7 +52,9 @@ module Mongo
       @query_run = false
     end
 
-    # Return the next document or nil if there are no more.
+    # Get the next document specified the cursor options.
+    #
+    # @return [Hash, Nil] the next document or Nil if no documents remain.
     def next_document
       refill_via_get_more if num_remaining == 0
       doc = @cache.shift
@@ -71,6 +76,7 @@ module Mongo
       doc
     end
 
+    # @deprecated use Cursor#next_document instead.
     def next_object
       warn "Cursor#next_object is deprecated; please use Cursor#next_document instead."
       next_document
@@ -78,9 +84,10 @@ module Mongo
 
     # Get the size of the result set for this query.
     #
-    # Returns the number of objects in the result set for this query. Does
-    # not take limit and skip into account. Raises OperationFailure on a
-    # database error.
+    # @return [Integer] the number of objects in the result set for this query. Does
+    #   not take limit and skip into account. 
+    #
+    # @raise [OperationFailure] on a database error.
     def count
       command = OrderedHash["count",  @collection.name,
                             "query",  @selector,
@@ -93,15 +100,16 @@ module Mongo
 
     # Sort this cursor's results.
     #
-    # Takes either a single key and a direction, or an array of [key,
-    # direction] pairs. Directions should be specified as Mongo::ASCENDING / Mongo::DESCENDING
-    # (or :ascending / :descending, :asc / :desc).
-    #
-    # Raises InvalidOperation if this cursor has already been used. Raises
-    # InvalidSortValueError if the specified order is invalid.
-    #
     # This method overrides any sort order specified in the Collection#find
     # method, and only the last sort applied has an effect.
+    #
+    # @param [Symbol, Array] key_or_list either 1) a key to sort by or 2) 
+    #   an array of [key, direction] pairs to sort by. Direction should
+    #   be specified as Mongo::ASCENDING (or :ascending / :asc) or Mongo::DESCENDING (or :descending / :desc)
+    #
+    # @raise [InvalidOperation] if this cursor has already been used.
+    #
+    # @raise [InvalidSortValueError] if the specified order is invalid.
     def sort(key_or_list, direction=nil)
       check_modifiable
 
@@ -115,13 +123,14 @@ module Mongo
       self
     end
 
-    # Limits the number of results to be returned by this cursor.
-    # Returns the current number_to_return if no parameter is given.
-    #
-    # Raises InvalidOperation if this cursor has already been used.
+    # Limit the number of results to be returned by this cursor.
     #
     # This method overrides any limit specified in the Collection#find method,
     # and only the last limit applied has an effect.
+    #
+    # @return [Integer] the current number_to_return if no parameter is given.
+    #
+    # @raise [InvalidOperation] if this cursor has already been used.
     def limit(number_to_return=nil)
       return @limit unless number_to_return
       check_modifiable
@@ -134,10 +143,12 @@ module Mongo
     # Skips the first +number_to_skip+ results of this cursor.
     # Returns the current number_to_skip if no parameter is given.
     #
-    # Raises InvalidOperation if this cursor has already been used.
-    #
     # This method overrides any skip specified in the Collection#find method,
     # and only the last skip applied has an effect.
+    #
+    # @return [Integer]
+    #
+    # @raise [InvalidOperation] if this cursor has already been used.
     def skip(number_to_skip=nil)
       return @skip unless number_to_skip
       check_modifiable
@@ -151,6 +162,13 @@ module Mongo
     # block.
     #
     # Iterating over an entire cursor will close it.
+    #
+    # @yield passes each document to a block for processing.
+    #
+    # @example if 'comments' represents a collection of comments:
+    #   comments.find.each do |doc|
+    #     puts doc['user']
+    #   end
     def each
       num_returned = 0
       while more? && (@limit <= 0 || num_returned < @limit)
@@ -159,13 +177,15 @@ module Mongo
       end
     end
 
-    # Return all of the documents in this cursor as an array of hashes.
+    # Receive all the documents from this cursor as an array of hashes.
     #
-    # Raises InvalidOperation if this cursor has already been used or if
-    # this methods has already been called on the cursor.
+    # Note: use of this method is discouraged - in most cases, it's much more
+    # efficient to retrieve documents as you need them by iterating over the cursor.
     #
-    # Use of this method is discouraged - iterating over a cursor is much
-    # more efficient in most cases.
+    # @return [Array] an array of documents.
+    #
+    # @raise [InvalidOperation] if this cursor has already been used or if
+    #   this method has already been called on the cursor.
     def to_a
       raise InvalidOperation, "can't call Cursor#to_a on a used cursor" if @query_run
       rows = []
@@ -177,7 +197,9 @@ module Mongo
       rows
     end
 
-    # Returns an explain plan document for this cursor.
+    # Get the explain plan for this cursor.
+    #
+    # @return [Hash] a document containing the explain plan for this cursor.
     def explain
       c = Cursor.new(@collection, query_options_hash.merge(:limit => -@limit.abs, :explain => true))
       explanation = c.next_document
@@ -186,19 +208,19 @@ module Mongo
       explanation
     end
 
-    # Closes the cursor.
+    # Close the cursor.
     #
     # Note: if a cursor is read until exhausted (read until Mongo::Constants::OP_QUERY or
     # Mongo::Constants::OP_GETMORE returns zero for the cursor id), there is no need to
-    # close it by calling this method.
+    # close it manually.
+    #
+    # Note also: Collection#find takes an optional block argument which can be used to
+    # ensure that your cursors get closed.
     #
-    # Collection#find takes an optional block argument which can be used to
-    # ensure that your cursors get closed. See the documentation for
-    # Collection#find for details.
+    # @return [True]
     def close
       if @cursor_id
-        message = ByteBuffer.new
-        message.put_int(0)
+        message = ByteBuffer.new([0, 0, 0, 0])
         message.put_int(1)
         message.put_long(@cursor_id)
         @connection.send_message(Mongo::Constants::OP_KILL_CURSORS, message, "cursor.close()")
@@ -207,18 +229,26 @@ module Mongo
       @closed    = true
     end
 
-    # Returns true if this cursor is closed, false otherwise.
+    # Is this cursor closed?
+    #
+    # @return [Boolean]
     def closed?; @closed; end
 
     # Returns an integer indicating which query options have been selected.
-    # See http://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol#MongoWireProtocol-Mongo::Constants::OPQUERY
+    #
+    # @return [Integer]
+    #
+    # @see http://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol#MongoWireProtocol-Mongo::Constants::OPQUERY
+    # The MongoDB wire protocol.
     def query_opts
       timeout  = @timeout ? 0 : Mongo::Constants::OP_QUERY_NO_CURSOR_TIMEOUT
       slave_ok = @connection.slave_ok? ? Mongo::Constants::OP_QUERY_SLAVE_OK : 0
       slave_ok + timeout
     end
 
-    # Returns the query options for this Cursor.
+    # Get the query options for this Cursor.
+    #
+    # @return [Hash]
     def query_options_hash
       { :selector => @selector,
         :fields   => @fields,
@@ -233,7 +263,7 @@ module Mongo
 
     private
 
-    # Converts the +:fields+ parameter from a single field name or an array
+    # Convert the +:fields+ parameter from a single field name or an array
     # of fields names to a hash, with the field names for keys and '1' for each
     # value.
     def convert_fields_for_query(fields)
@@ -284,9 +314,7 @@ module Mongo
 
     def refill_via_get_more
       return if send_initial_query || @cursor_id.zero?
-      message = ByteBuffer.new
-      # Reserved.
-      message.put_int(0)
+      message = ByteBuffer.new([0, 0, 0, 0])
 
       # DB name.
       db_name = @admin ? 'admin' : @db.name
@@ -328,8 +356,8 @@ module Mongo
       if query_contains_special_fields?
         selector = selector_with_special_query_fields
       end
-      message.put_array(BSON.serialize(selector, false).unpack("C*"))
-      message.put_array(BSON.serialize(@fields, false).unpack("C*")) if @fields
+      message.put_array(BSON.serialize(selector, false).to_a)
+      message.put_array(BSON.serialize(@fields, false).to_a) if @fields
       message
     end