Class: XGen::Mongo::Driver::Cursor

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/mongo/cursor.rb

Overview

A cursor over query results. Returned objects are hashes.

Constant Summary collapse

RESPONSE_HEADER_SIZE = 
20

Instance Method Summary collapse

Constructor Details

#initialize(db, collection, num_to_return = 0) ⇒ Cursor

Returns a new instance of Cursor.



32
33
34
35
36
37
38
 
# File 'lib/mongo/cursor.rb', line 32

def initialize(db, collection, num_to_return=0)
  @db, @collection, @num_to_return = db, collection, num_to_return
  @cache = []
  @closed = false
  @can_call_to_a = true
  read_all
end

Instance Method Details

#close ⇒ Object

Close the cursor.



104
105
106
107
108
109
 
# File 'lib/mongo/cursor.rb', line 104

def close
  @db.send_to_db(KillCursorMessage(@cursor_id)) if @cursor_id
  @cache = []
  @cursor_id = 0
  @closed = true
end

#each ⇒ Object

Iterate over each object, yielding it to the given block. At most If #to_a has already been called then this method uses the array that we store internally. In that case, #each can be called multiple times because it re-uses that array.

You can call #each after calling #to_a (multiple times even, because it will use the internally-stored array), but you can’t call #to_a after calling #each unless you also called it before calling #each. If you try to do that, an error will be raised.



66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/mongo/cursor.rb', line 66

def each
  if @rows              # Already turned into an array
    @rows.each { |row| yield row }
  else
    num_returned = 0
    while more? && (@num_to_return <= 0 || num_returned < @num_to_return)
      yield next_object()
      num_returned += 1
    end
    @can_call_to_a = false
  end
end

#more? ⇒ Boolean

Return true if there are more records to retrieve. We do not check @num_to_return; #each is responsible for doing that.

Returns:

  • (Boolean) 


42
43
44
 
# File 'lib/mongo/cursor.rb', line 42

def more?
  num_remaining > 0
end

#next_object ⇒ Object

Return the next object. Raises an error if necessary.



47
48
49
50
51
52
 
# File 'lib/mongo/cursor.rb', line 47

def next_object
  refill_via_get_more if num_remaining == 0
  o = @cache.shift
  raise o['$err'] if o['$err']
  o
end

#to_a ⇒ Object

Return all of the rows (up to the num_to_return value specified in #new) as an array. Calling this multiple times will work fine; it always returns the same array.

Don’t use this if you’re expecting large amounts of data, of course. All of the returned rows are kept in an array stored in this object so it can be reused.

You can call #each after calling #to_a (multiple times even, because it will use the internally-stored array), but you can’t call #to_a after calling #each unless you also called it before calling #each. If you try to do that, an error will be raised.



91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/mongo/cursor.rb', line 91

def to_a
  return @rows if @rows
  raise "can't call Cursor#to_a after calling Cursor#each" unless @can_call_to_a
  @rows = []
  num_returned = 0
  while more? && (@num_to_return <= 0 || num_returned < @num_to_return)
    @rows << next_object()
    num_returned += 1
  end
  @rows
end