Class: Mongo::Cursor Private

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable, Retryable
Defined in:
lib/mongo/cursor.rb,
lib/mongo/cursor/kill_spec.rb,
lib/mongo/cursor/nontailable.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

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

Cursor objects are not directly exposed to application code. Rather, Collection::View exposes the Enumerable interface to the applications, and the enumerator is backed by a Cursor instance.

Examples:

Get an array of 5 users named Emily.

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

Call a block on each user doc.

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

Direct Known Subclasses

CachingCursor

Defined Under Namespace

Modules: NonTailable Classes: KillSpec

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Retryable

#read_worker, #select_server, #write_worker

Constructor Details

#initialize(view, result, server, options = {}) ⇒ Cursor

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates a Cursor object.

Examples:

Instantiate the cursor.

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

Parameters:

  • view (CollectionView) —

    The CollectionView defining the query.

  • result (Operation::Result) —

    The result of the first execution.

  • server (Server) —

    The server this cursor is locked to.

  • options (Hash) (defaults to: {}) —

    The cursor options.

Options Hash (options):

  • :context (Operation::Context) —

    The operation context for this cursor.

  • :disable_retry (true, false) —

    Whether to disable retrying on error when sending getMore operations (deprecated, getMore operations are no longer retried)

  • :retry_reads (true, false) —

    Retry reads (following the modern mechanism), default is true

Since:

  • 2.0.0



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/mongo/cursor.rb', line 74

def initialize(view, result, server, options = {})
  unless result.is_a?(Operation::Result)
    raise ArgumentError, "Second argument must be a Mongo::Operation::Result: #{result.inspect}"
  end

  @view = view
  @server = server
  @initial_result = result
  @namespace = result.namespace
  @remaining = limit if limited?
  set_cursor_id(result)
  if @cursor_id.nil?
    raise ArgumentError, 'Cursor id must be present in the result'
  end
  @options = options
  @session = @options[:session]
  @connection_global_id = result.connection_global_id
  @context = @options[:context]&.with(connection_global_id: connection_global_id_for_context) || fresh_context
  @explicitly_closed = false
  @lock = Mutex.new
  if server.load_balancer?
    # We need the connection in the cursor only in load balanced topology;
    # we do not need an additional reference to it otherwise.
    @connection = @initial_result.connection
  end
  if closed?
    check_in_connection
  else
    register
    ObjectSpace.define_finalizer(
      self,
      self.class.finalize(kill_spec(@connection_global_id), cluster)
    )
  end
end

Instance Attribute Details

#connection ⇒ Object (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



117
118
119
 
# File 'lib/mongo/cursor.rb', line 117

def connection
  @connection
end

#context ⇒ Operation::Context (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns context the context for this cursor.

Returns:



53
54
55
 
# File 'lib/mongo/cursor.rb', line 53

def context
  @context
end

#initial_result ⇒ Object (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



114
115
116
 
# File 'lib/mongo/cursor.rb', line 114

def initial_result
  @initial_result
end

#resume_token ⇒ BSON::Document | nil (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The resume token tracked by the cursor for change stream resuming

Returns:

  • (BSON::Document | nil) —

    The cursor resume token.



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

def resume_token
  @resume_token
end

#server ⇒ Object (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



111
112
113
 
# File 'lib/mongo/cursor.rb', line 111

def server
  @server
end

#view ⇒ Collection::View (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns view The collection view.

Returns:



44
45
46
 
# File 'lib/mongo/cursor.rb', line 44

def view
  @view
end

Class Method Details

.finalize(kill_spec, cluster) ⇒ Proc

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

  • kill_spec (Cursor::KillSpec) —

    The KillCursor operation specification.

  • cluster (Mongo::Cluster) —

    The cluster associated with this cursor and its server.

Returns:

  • (Proc) —

    The Finalizer.



128
129
130
131
132
133
134
135
 
# File 'lib/mongo/cursor.rb', line 128

def self.finalize(kill_spec, cluster)
  unless KillSpec === kill_spec
    raise ArgumentError, "First argument must be a KillSpec: #{kill_spec.inspect}"
  end
  proc do
    cluster.schedule_kill_cursor(kill_spec)
  end
end

Instance Method Details

#batch_size ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get the batch size.

Examples:

Get the batch size.

cursor.batch_size

Returns:

  • (Integer) —

    The batch size.

Since:

  • 2.2.0



279
280
281
282
283
284
285
286
 
# File 'lib/mongo/cursor.rb', line 279

def batch_size
  value = @view.batch_size && @view.batch_size > 0 ? @view.batch_size : limit
  if value == 0
    nil
  else
    value
  end
end

#close(opts = {}) ⇒ nil

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Closes this cursor, freeing any associated resources on the client and the server.

Returns:

  • (nil) —

    Always nil.



305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
 
# File 'lib/mongo/cursor.rb', line 305

def close(opts = {})
  return if closed?

  ctx = context ? context.refresh(timeout_ms: opts[:timeout_ms]) : fresh_context(opts)

  unregister
  read_with_one_retry do
    spec = {
      coll_name: collection_name,
      db_name: database.name,
      cursor_ids: [id],
    }
    op = Operation::KillCursors.new(spec)
    execute_operation(op, context: ctx)
  end

  nil
rescue Error::OperationFailure::Family, Error::SocketError, Error::SocketTimeoutError, Error::ServerNotUsable
  # Errors are swallowed since there is noting can be done by handling them.
ensure
  end_session
  @cursor_id = 0
  @lock.synchronize do
    @explicitly_closed = true
  end
  check_in_connection
end

#closed? ⇒ true, false

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Is the cursor closed?

Examples:

Is the cursor closed?

cursor.closed?

Returns:

  • (true, false) —

    If the cursor is closed.

Since:

  • 2.2.0



296
297
298
299
 
# File 'lib/mongo/cursor.rb', line 296

def closed?
  # @cursor_id should in principle never be nil
  @cursor_id.nil? || @cursor_id == 0
end

#collection_name ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get the parsed collection name.

Examples:

Get the parsed collection name.

cursor.coll_name

Returns:

  • (String) —

    The collection name.

Since:

  • 2.2.0



341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/mongo/cursor.rb', line 341

def collection_name
  # In most cases, this will be equivalent to the name of the collection
  # object in the driver. However, in some cases (e.g. when connected
  # to an Atlas Data Lake), the namespace returned by the find command
  # may be different, which is why we want to use the collection name based
  # on the namespace in the command result.
  if @namespace
    # Often, the namespace will be in the format "database.collection".
    # However, sometimes the collection name will contain periods, which
    # is why this method joins all the namespace components after the first.
    ns_components = @namespace.split('.')
    ns_components[1...ns_components.length].join('.')
  else
    collection.name
  end
end

#each ⇒ Enumerator

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Iterate through documents returned from the query.

A cursor may be iterated at most once. Incomplete iteration is also allowed. Attempting to iterate the cursor more than once raises InvalidCursorOperation.

Examples:

Iterate over the documents in the cursor.

cursor.each do |doc|
  ...
end

Returns:

  • (Enumerator) —

    The enumerator.

Since:

  • 2.0.0



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/mongo/cursor.rb', line 163

def each

  # If we already iterated past the first batch (i.e., called get_more
  # at least once), the cursor on the server side has advanced past
  # the first batch and restarting iteration from the beginning by
  # returning initial result would miss documents in the second batch
  # and subsequent batches up to wherever the cursor is. Detect this
  # condition and abort the iteration.
  #
  # In a future driver version, each would either continue from the
  # end of previous iteration or would always restart from the
  # beginning.
  if @get_more_called
    raise Error::InvalidCursorOperation, 'Cannot restart iteration of a cursor which issued a getMore'
  end

  # To maintain compatibility with pre-2.10 driver versions, reset
  # the documents array each time a new iteration is started.
  @documents = nil

  if block_given?
    # StopIteration raised by try_next ends this loop.
    loop do
      document = try_next
      if explicitly_closed?
        raise Error::InvalidCursorOperation, 'Cursor was explicitly closed'
      end
      yield document if document
    end
    self
  else
    documents = []
    # StopIteration raised by try_next ends this loop.
    loop do
      document = try_next
      if explicitly_closed?
        raise Error::InvalidCursorOperation, 'Cursor was explicitly closed'
      end
      documents << document if document
    end
    documents
  end
end

#fully_iterated? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


416
417
418
 
# File 'lib/mongo/cursor.rb', line 416

def fully_iterated?
  !!@fully_iterated
end

#get_more ⇒ Array<BSON::Document>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Execute a getMore command and return the batch of documents obtained from the server.

Returns:

  • (Array<BSON::Document>) —

    The batch of documents



391
392
393
394
395
396
397
398
399
400
 
# File 'lib/mongo/cursor.rb', line 391

def get_more
  @get_more_called = true

  # Modern retryable reads specification prohibits retrying getMores.
  # Legacy retryable read logic used to retry getMores, but since
  # doing so may result in silent data loss, the driver no longer retries
  # getMore operations in any circumstance.
  # https://github.com/mongodb/specifications/blob/master/source/retryable-reads/retryable-reads.rst#qa
  process(execute_operation(get_more_operation))
end

#id ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

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

Get the cursor id.

Examples:

Get the cursor id.

cursor.id

Returns:

  • (Integer) —

    The cursor id.

Since:

  • 2.2.0



368
369
370
 
# File 'lib/mongo/cursor.rb', line 368

def id
  @cursor_id
end

#inspect ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get a human-readable string representation of Cursor.

Examples:

Inspect the cursor.

cursor.inspect

Returns:

  • (String) —

    A string representation of a Cursor instance.

Since:

  • 2.0.0



145
146
147
 
# File 'lib/mongo/cursor.rb', line 145

def inspect
  "#<Mongo::Cursor:0x#{object_id} @view=#{@view.inspect}>"
end

#kill_spec(connection_global_id) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



403
404
405
406
407
408
409
410
411
412
413
 
# File 'lib/mongo/cursor.rb', line 403

def kill_spec(connection_global_id)
  KillSpec.new(
    cursor_id: id,
    coll_name: collection_name,
    db_name: database.name,
    connection_global_id: connection_global_id,
    server_address: server.address,
    session: @session,
    connection: @connection
  )
end

#to_return ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Examples:

Get the number to return.

cursor.to_return

Returns:

  • (Integer) —

    The number of documents to return.

Since:

  • 2.2.0



381
382
383
 
# File 'lib/mongo/cursor.rb', line 381

def to_return
  use_limit? ? @remaining : (batch_size || 0)
end

#try_next ⇒ BSON::Document | nil

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

This method is experimental and subject to change.

Return one document from the query, if one is available.

This method will wait up to max_await_time_ms milliseconds for changes from the server, and if no changes are received it will return nil. If there are no more documents to return from the server, or if we have exhausted the cursor, it will raise a StopIteration exception.

Returns:

  • (BSON::Document | nil) —

    A document.

Raises:

  • (StopIteration) —

    Raised on the calls after the cursor had been completely iterated.



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/mongo/cursor.rb', line 223

def try_next
  if @documents.nil?
    # Since published versions of Mongoid have a copy of old driver cursor
    # code, our dup call in #process isn't invoked when Mongoid query
    # cache is active. Work around that by also calling dup here on
    # the result of #process which might come out of Mongoid's code.
    @documents = process(@initial_result).dup
    # the documents here can be an empty array, hence
    # we may end up issuing a getMore in the first try_next call
  end

  if @documents.empty?
    # On empty batches, we cache the batch resume token
    cache_batch_resume_token

    unless closed?
      if exhausted?
        close
        @fully_iterated = true
        raise StopIteration
      end
      @documents = get_more
    else
      @fully_iterated = true
      raise StopIteration
    end
  else
    # cursor is closed here
    # keep documents as an empty array
  end

  # If there is at least one document, cache its _id
  if @documents[0]
    cache_resume_token(@documents[0])
  end

  # Cache the batch resume token if we are iterating
  # over the last document, or if the batch is empty
  if @documents.size <= 1
    cache_batch_resume_token
    if closed?
      @fully_iterated = true
    end
  end

  return @documents.shift
end