class Mongo::Cursor

Client-side representation of an iterator over a query result set on the server.

A Cursor is not created directly by a user. Rather, CollectionView creates a Cursor in an Enumerable module method.

@example Get an array of 5 users named Emily.

users.find({:name => 'Emily'}).limit(5).to_a

@example Call a block on each user doc.

users.find.each { |doc| puts doc }

@note The Cursor API is semipublic. @api semipublic

Attributes

view[R]

@return [ Collection::View ] view The collection view.

Public Class Methods

finalize(cursor_id, cluster, op_spec, server) click to toggle source

Finalize the cursor for garbage collection. Schedules this cursor to be included in a killCursors operation executed by the Cluster's CursorReaper.

@example Finalize the cursor.

Cursor.finalize(id, cluster, op, server)

@param [ Integer ] cursor_id The cursor's id. @param [ Mongo::Cluster ] cluster The cluster associated with this cursor and its server. @param [ Hash ] op_spec The killCursors operation specification. @param [ Mongo::Server ] server The server to send the killCursors operation to.

@return [ Proc ] The Finalizer.

@since 2.3.0

# File lib/mongo/cursor.rb, line 83
def self.finalize(cursor_id, cluster, op_spec, server)
  proc { cluster.schedule_kill_cursor(cursor_id, op_spec, server) }
end
new(view, result, server) click to toggle source

Creates a Cursor object.

@example Instantiate the cursor.

Mongo::Cursor.new(view, response, server)

@param [ CollectionView ] view The CollectionView defining the query. @param [ Operation::Result ] result The result of the first execution. @param [ Server ] server The server this cursor is locked to.

@since 2.0.0

# File lib/mongo/cursor.rb, line 55
def initialize(view, result, server)
  @view = view
  @server = server
  @initial_result = result
  @remaining = limit if limited?
  @cursor_id = result.cursor_id
  register
  ObjectSpace.define_finalizer(self, self.class.finalize(result.cursor_id,
                                                         cluster,
                                                         kill_cursors_op_spec,
                                                         server))
end

Public Instance Methods

batch_size() click to toggle source

Get the batch size.

@example Get the batch size.

cursor.batch_size

@return [ Integer ] The batch size.

@since 2.2.0

# File lib/mongo/cursor.rb, line 125
def batch_size
  @view.batch_size && @view.batch_size > 0 ? @view.batch_size : limit
end
closed?() click to toggle source

Is the cursor closed?

@example Is the cursor closed?

cursor.closed?

@return [ true, false ] If the cursor is closed.

@since 2.2.0

# File lib/mongo/cursor.rb, line 137
def closed?
  !more?
end
collection_name() click to toggle source

Get the parsed collection name.

@example Get the parsed collection name.

cursor.coll_name

@return [ String ] The collection name.

@since 2.2.0

# File lib/mongo/cursor.rb, line 149
def collection_name
  @coll_name || collection.name
end
each() { |doc| ... } click to toggle source

Iterate through documents returned from the query.

@example Iterate over the documents in the cursor.

cursor.each do |doc|
  ...
end

@return [ Enumerator ] The enumerator.

@since 2.0.0

# File lib/mongo/cursor.rb, line 109
def each
  process(@initial_result).each { |doc| yield doc }
  while more?
    return kill_cursors if exhausted?
    get_more.each { |doc| yield doc }
  end
end
id() click to toggle source

Get the cursor id.

@example Get the cursor id.

cursor.id

@note A cursor id of 0 means the cursor was closed on the server.

@return [ Integer ] The cursor id.

@since 2.2.0

# File lib/mongo/cursor.rb, line 163
def id
  @cursor_id
end
inspect() click to toggle source

Get a human-readable string representation of Cursor.

@example Inspect the cursor.

cursor.inspect

@return [ String ] A string representation of a Cursor instance.

@since 2.0.0

# File lib/mongo/cursor.rb, line 95
def inspect
  "#<Mongo::Cursor:0x#{object_id} @view=#{@view.inspect}>"
end
to_return() click to toggle source

Get the number of documents to return. Used on 3.0 and lower server versions.

@example Get the number to return.

cursor.to_return

@return [ Integer ] The number of documents to return.

@since 2.2.0

# File lib/mongo/cursor.rb, line 176
def to_return
  use_limit? ? @remaining : (batch_size || 0)
end

Private Instance Methods

exhausted?() click to toggle source
# File lib/mongo/cursor.rb, line 182
def exhausted?
  limited? ? @remaining <= 0 : false
end
get_more() click to toggle source
# File lib/mongo/cursor.rb, line 186
def get_more
  read_with_retry do
    process(get_more_operation.execute(@server))
  end
end
get_more_operation() click to toggle source
# File lib/mongo/cursor.rb, line 192
def get_more_operation
  if @server.features.find_command_enabled?
    Operation::Commands::GetMore.new(Builder::GetMoreCommand.new(self).specification)
  else
    Operation::Read::GetMore.new(Builder::OpGetMore.new(self).specification)
  end
end
kill_cursors() click to toggle source
# File lib/mongo/cursor.rb, line 200
def kill_cursors
  unregister
  read_with_one_retry do
    kill_cursors_operation.execute(@server)
  end
end
kill_cursors_op_spec() click to toggle source
# File lib/mongo/cursor.rb, line 215
def kill_cursors_op_spec
  if @server.features.find_command_enabled?
    Builder::KillCursorsCommand.new(self).specification
  else
    Builder::OpKillCursors.new(self).specification
  end
end
kill_cursors_operation() click to toggle source
# File lib/mongo/cursor.rb, line 207
def kill_cursors_operation
  if @server.features.find_command_enabled?
    Operation::Commands::Command.new(kill_cursors_op_spec)
  else
    Operation::KillCursors.new(kill_cursors_op_spec)
  end
end
limited?() click to toggle source
# File lib/mongo/cursor.rb, line 223
def limited?
  limit ? limit > 0 : false
end
more?() click to toggle source
# File lib/mongo/cursor.rb, line 227
def more?
  @cursor_id != 0
end
process(result) click to toggle source
# File lib/mongo/cursor.rb, line 231
def process(result)
  @remaining -= result.returned_count if limited?
  @coll_name ||= result.namespace.sub("#{database.name}.", '') if result.namespace
  unregister if result.cursor_id == 0
  @cursor_id = result.cursor_id
  result.documents
end
register() click to toggle source
# File lib/mongo/cursor.rb, line 243
def register
  cluster.register_cursor(@cursor_id)
end
unregister() click to toggle source
# File lib/mongo/cursor.rb, line 247
def unregister
  cluster.unregister_cursor(@cursor_id)
end
use_limit?() click to toggle source
# File lib/mongo/cursor.rb, line 239
def use_limit?
  limited? && batch_size >= @remaining
end