Cursor — Documentation by YARD 0.9.37 (original) (raw)

Class: Mongo::CursorPrivate

Inherits:

Object

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.

Defined Under Namespace

Modules: NonTailable Classes: KillSpec

Instance Attribute Summary collapse

Class Method Summarycollapse

Instance Method Summarycollapse

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.

| 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? @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

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

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.

53 54 55 # File 'lib/mongo/cursor.rb', line 53 def context @context end

#initial_result ⇒ 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.

114 115 116 # File 'lib/mongo/cursor.rb', line 114 def initial_result @initial_result end

#resume_token ⇒ 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.

The resume token tracked by the cursor for change stream resuming

50 51 52 # File 'lib/mongo/cursor.rb', line 50 def resume_token @resume_token end

#server ⇒ 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.

111 112 113 # File 'lib/mongo/cursor.rb', line 111 def server @server end

#view ⇒ Collection::View

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.

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.

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.

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.

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 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?

| 296 297 298 299 | # File 'lib/mongo/cursor.rb', line 296 def closed? @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.

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 if @namespace 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.

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 @get_more_called raise Error::InvalidCursorOperation, 'Cannot restart iteration of a cursor which issued a getMore' end @documents = nil if block_given? loop do document = try_next if explicitly_closed? raise Error::InvalidCursorOperation, 'Cursor was explicitly closed' end yield document if document end self else documents = [] 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.

416 417 418 # File 'lib/mongo/cursor.rb', line 416 def fully_iterated? !!@fully_iterated end

#get_more ⇒ ArrayBSON::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.

391 392 393 394 395 396 397 398 399 400 # File 'lib/mongo/cursor.rb', line 391 def get_more @get_more_called = true 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.

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.

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.

| 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.

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? @documents = process(@initial_result).dup end if @documents.empty? 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 end if @documents[0] cache_resume_token(@documents[0]) end if @documents.size <= 1 cache_batch_resume_token if closed? @fully_iterated = true end end return @documents.shift end