Clase: Mongo::Cursor Privado

Hereda:
Objeto
  • Objeto
Mostrar todo
Ampliado por:
Reenviable
Incluye:
Enumerable, Reintento posible
Definido en:
lib/mongo/cursor.rb,
lib/mongo/cursor/kill_spec.rb,
lib/mongo/cursor/nontailable.rb

Overview

Esta clase forma parte de una API privada. Evita usar esta clase si es posible, ya que puede ser eliminada o modificada en el futuro.

Representación del lado del cliente de un iterador sobre un conjunto de resultados de una query en el servidor.

Cursor los objetos no se exponen directamente al código de la aplicación. En cambio, Collection::View expone la interfaz Enumerable a las aplicaciones, y el enumerador está respaldado por una instancia de Cursor.

Ejemplos:

Obtenga un arreglo de 5 usuarios llamados Emily.

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

Ejecuta un bloque en cada documento de usuario.

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

Subclases conocidas directas

CachingCursor

Definido bajo Namespace

Modules: No encajable clase: KillSpec

Resumen de atributos de la instancia colapsar

Resumen del método de clase colapsar

Resumen del método de instancia colapsar

Métodos incluidos de Retryable

#read_worker, #select_server, #with_overload_retry, #write_worker

Detalles del Constructor

#initialize(vista, resultado, servidor, opciones = {}) ⇒ Cursor

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Crea un objeto Cursor.

Ejemplos:

Instanciar el cursor.

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

Parámetros:

  • vista (CollectionView) —

    El CollectionView que define la query.

  • Resultado (Operation::Result) —

    El resultado de la primera ejecución.

  • Server (servidor) —

    El servidor al que este cursor está bloqueado.

  • opciones (encriptada) (por defecto: {}) —

    Las opciones del cursor.

Opciones Hash (options):

  • :context (Operación::Contexto) —

    El contexto de la operación para este cursor.

  • Desactivar Reintentar (verdadero, falso) —

    Si se debe desactivar el reintento en caso de error al enviar operaciones getMore (obsoleto, las operaciones getMore ya no se reintentan)

  • :retry_reads (verdadero, falso) —

    Reintentar lecturas (siguiendo el mecanismo moderno), el valor por defecto es verdadero

Aumenta:

  • (ArgumentError)

Desde:

  • 2.0.0



72
73
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
 
# Archivo 'lib/mongo/cursor.rb', línea 72

def inicializar(vista, Resultado, Server, opciones = {})
  a menos que Resultado.is_a?(Operación::Resultado)
    propagar ArgumentError,  "El segundo argumento debe ser un Mongo::Operation::Result: #{resultado.inspectar} "
  end

  @view = vista
  @server = Server
  @initial_result = Resultado
  @namespace = Resultado.namespace
  @remaining = limit si ¿limitado?
  set_cursor_id(Resultado)
  propagar ArgumentError, 'El id del cursor debe estar presente en el resultado' si @cursor_id.nil?

  @options = opciones
  @sesión = @options[:: sesión]
  @connection_global_id = Resultado.connection_global_id
  @contexto = @options[:context]&.con(connection_global_id: connection_global_id_for_context) || fresh_context
  @explicitly_closed = false
  @get_more_network_error = false
  @lock = Mutex (exclusión mutua).Nuevo
  si Server.load_balancer?
    # Necesitamos la conexión en el cursor solo en la topología equilibrada;
    # no necesitamos una referencia adicional a él de lo contrario.
    @connection = @initial_result.Conexión
  end
  si ¿Cerrado?
    verificar_conexión
  else
    registrar
    ObjectSpace.define_finalizer(
      sí mismo,
      sí mismo.clase.finaliza(kill_spec(@connection_global_id), clúster)
    )
  end
end

Detalles de atributo de instancias

#conexión ⇒ Objeto (solo lectura)

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro. 



115
116
117
 
# Archivo 'lib/mongo/cursor.rb', línea 115

def Conexión
  @connection
end

#contexto ⇒ operación::Context (solo lectura)

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Devuelve el contexto de este cursor.

Devuelve:



51
52
53
 
# Archivo 'lib/mongo/cursor.rb', línea 51

def context
  @contexto
end

#initial_result ⇒ objeto (solo lectura)

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro. 



112
113
114
 
# Archivo 'lib/mongo/cursor.rb', línea 112

def resultado_inicial
  @initial_result
end

#resume_token ⇒ BSON::documento | nil (solo lectura)

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

El token de reanudación rastreado por el cursor para la reanudación del flujo de cambios

Devuelve:

  • (BSON::Document | nil) —

    El token de reanudación del cursor.



48
49
50
 
# Archivo 'lib/mongo/cursor.rb', línea 48

def resume_token
  @resume_token
end

#servidor ⇒ objeto (solo lectura)

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro. 



109
110
111
 
# Archivo 'lib/mongo/cursor.rb', línea 109

def Server
  @server
end

#vista ⇒ Colección::Vista (solo lectura)

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Devuelve vista La vista de la colección.

Devuelve:



42
43
44
 
# Archivo 'lib/mongo/cursor.rb', línea 42

def vista
  @view
end

Detalles del método de clase

.finalize(kill_spec, clúster) ⇒ Proc

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Finalizar el cursor para la colección de basura. Programa este cursor para que se incluya en una operación killCursors ejecutada por el CursorReaper del clúster.

Parámetros:

  • kill_spec (Cursor::KillSpec) —

    La especificación de la operación KillCursor.

  • clúster (Mongo::clúster) —

    El clúster asociado con este cursor y su servidor.

Devuelve:

  • (Proc) —

    El Finalizador.

Aumenta:

  • (ArgumentError) 


126
127
128
129
130
131
132
 
# Archivo 'lib/mongo/cursor.rb', línea 126

def sí mismo.finaliza(kill_spec, clúster)
  propagar ArgumentError, "El primer argumento debe ser un KillSpec: #{kill_spec.inspect}" a menos que kill_spec.is_a?(KillSpec)

  proc hacer
    clúster.schedule_kill_cursor(kill_spec)
  end
end

Detalles del método de instancia

#batch_size ⇒ Integer

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Obtén el tamaño del lote.

Ejemplos:

Obtén el tamaño del lote.

cursor.batch_size

Devuelve:

  • (Número entero) —

    El tamaño del lote.

Desde:

  • 2.2.0



269
270
271
272
273
274
275
276
 
# Archivo 'lib/mongo/cursor.rb', línea 269

def batch_size
  Valor = (@view.batch_size && @view.batch_size > 0) ? @view.batch_size : limit
  si Valor == 0
    nulo
  else
    Valor
  end
end

#close(opts = {}) ⇒ nil(nulo)

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Cierra este cursor, liberando cualquier recurso asociado tanto en el cliente como en el servidor.

Devuelve:

  • (nil) —

    Siempre nulo.



295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
 
# Archivo 'lib/mongo/cursor.rb', línea 295

def Cerrar(opciones = {})
  return si ¿Cerrado?

  ctx = context ? context.actualizar(tiempo_de_espera_ms: opciones[:timeout_ms]) : fresh_context(opciones)

  unregister
  a menos que @get_more_network_error
    read_with_one_retry hacer
      especificación = {
        coll_name: nombre_colección,
        db_name: database.Nombre,
        cursor_ids: [ ID ],
      }
      op = Operación::killCursors.Nuevo(especificación)
      execute_operation(op, context: ctx)
    end
  end

  nulo
rescate Error::OperationFailure::Familia, Error::SocketError, Error::SocketTimeoutError, Error::ServerNotUsable, Error::ConnectionPerished
  # Los errores se descartan porque no hay nada que pueda hacerse manipulándolos.
asegurar
  end_session
  @cursor_id = 0
  @lock.sincronizar hacer
    @explicitly_closed = true
  end
  verificar_conexión
end

#cerrado? ⇒ verdadero, falso

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

¿Está cerrado el cursor?

Ejemplos:

¿Está cerrado el cursor?

cursor.closed?

Devuelve:

  • (true, false) —

    Si el cursor está cerrado.

Desde:

  • 2.2.0



286
287
288
289
 
# Archivo 'lib/mongo/cursor.rb', línea 286

def ¿Cerrado?
  # @cursor_id en principio no debería ser nunca nil
  @cursor_id.nil? || @cursor_id == 0
end

#collection_name ⇒ String

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Obtenga el nombre de la colección procesada.

Ejemplos:

Obtenga el nombre de la colección procesada.

cursor.coll_name

Devuelve:

  • (string) —

    El nombre de la colección.

Desde:

  • 2.2.0



333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# Archivo 'lib/mongo/cursor.rb', línea 333

def nombre_colección
  # En la mayoría de los casos, será equivalente al nombre de la colección
  # objeto en el controlador. Sin embargo, en algunos casos (por ejemplo, cuando se conecta
  # a un Atlas Data Lake), el namespace devuelto por el comando find
  # puede ser diferente, por eso queremos usar el nombre de colección basado
  # on the namespace en el resultado del comando.
  si @namespace
    # A menudo, el namespace estará en el formato "database.collection".
    # Sin embargo, a veces el nombre de la colección contendrá puntos, que
    # es por eso que este método une todos los componentes del namespace después del primero.
    ns_components = @namespace.división('.')
    ns_components[1...ns_components.longitud].unirse('.')
  else
    Colección.Nombre
  end
end

#cada uno ⇒ Enumerator

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Itera a través de los documentos devueltos por la query.

Un cursor puede ser iterado como máximo una vez. También se permite la iteración incompleta. Intentar iterar el cursor más de una vez genera InvalidCursorOperation.

Ejemplos:

Iterar sobre los documentos en el cursor.

cursor.each do |doc|
  ...
end

Devuelve:

  • (Enumerator) —

    El enumerador.

Desde:

  • 2.0.0



160
161
162
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
 
# Archivo 'lib/mongo/cursor.rb', línea 160

def cada
  # Se já iteramos além do primeiro lote (ou seja, chamamos get_more
  # al menos una vez), el cursor en el lado del servidor ha avanzado más allá
  # el primer agrupar y reiniciar la iteración desde el principio por
  # devolver el resultado inicial haría que se pasaran por alto los documentos en el segundo agrupar
  # y lotes subsiguientes hasta donde esté el cursor. Detecte esto
  # condición y abortar la iteración.
  #
  # En una futura versión del controlador, cada uno continuaría desde el
  # final de la iteración anterior o siempre se reiniciaría desde el
  # principio.
  si @get_more_called
    propagar Error::InvalidCursorOperation, 'No se puede reiniciar la iteración de un cursor que ha emitido un getMore'
  end

  # Para mantener la compatibilidad con las versiones previas a2.10 versiones del driver, restablecer
  # el arreglo de documentos cada vez que se inicia una nueva iteración.
  @documents = nulo

  si ¿block_given?
    # StopIteration generado por try_next termina este ciclo.
    bucle hacer
      Documento = try_next
      propagar Error::InvalidCursorOperation, 'El cursor se cerró explícitamente' si explicitly_closed?

      rendimiento Documento si Documento
    end
    sí mismo
  else
    Documentos = []
    # StopIteration generado por try_next termina este ciclo.
    bucle hacer
      Documento = try_next
      propagar Error::InvalidCursorOperation, 'El cursor se cerró explícitamente' si explicitly_closed?

      Documentos << Documento si Documento
    end
    Documentos
  end
end

#fully_iterated? ⇒ Booleano

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Devuelve:

  • (booleano) 


409
410
411
 
# Archivo 'lib/mongo/cursor.rb', línea 409

def fully_iterated?
  !!@fully_iterated
end

#get_more ⇒ arreglo<BSON::Document>

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Ejecute un comando getMore y devuelva el lote de documentos obtenidos del servidor.

Devuelve:

  • (arreglo<BSON::Document>) —

    El lote de documentos



370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
 
# Archivo 'lib/mongo/cursor.rb', línea 370

def obtener más
  @get_more_called = true

  # La especificación moderna de lecturas reintentables prohíbe reintentar getMores.
  # La antigua lógica de reintentos utilizaba lecturas reintentables para volver a intentar getMores, pero desde
  # hacerlo puede dar lugar a una pérdida de datos silenciosa, el controlador ya no intenta de nuevo
  # operaciones getMore en cualquier circunstancia.
  # https://github.com/mongodb/specifications/blob/master/source/retryable-reads/retryable-reads.md#qa
  #
  # Sin embargo, los errores de sobrecarga (SystemOverloadedError + RetryableError) son
  # se reintentó con retroceso exponencial ya que el servidor nunca procesó
  # la solicitud.
  con_reintento_por_sobrecarga(context: possibly_refreshed_context) hacer
    Proceso(execute_operation(get_more_operation))
  end
rescate Error::SocketError, Error::SocketTimeoutError
  @get_more_network_error = true
  propagar
rescate Error::OperationFailure => e
  # Cuando se agoten los reintentos por sobrecarga en getMore, cierra el cursor
  # para que killCursors se envíe al servidor.
  Cerrar si e.¿etiqueta?('RetryableError') && e.¿etiqueta?('SystemOverloadedError')
  propagar
end

#id ⇒ Integer

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Nota:

Un id de cursor de 0 significa que el cursor se cerró en el servidor.

Obtener el id del cursor.

Ejemplos:

Obtener el id del cursor.

cursor.id

Devuelve:

  • (Número entero) —

    El id del cursor.

Desde:

  • 2.2.0



360
361
362
 
# Archivo 'lib/mongo/cursor.rb', línea 360

def ID
  @cursor_id
end

#inspect ⇒ String

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Obtén una representación en string legible por humanos de Cursor.

Ejemplos:

Inspecciona el cursor.

cursor.inspect

Devuelve:

  • (string) —

    Una representación en string de una instancia de Cursor.

Desde:

  • 2.0.0



142
143
144
 
# Archivo 'lib/mongo/cursor.rb', línea 142

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

#kill_spec(connection_global_id) ⇒ Objeto

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro. 



396
397
398
399
400
401
402
403
404
405
406
 
# Archivo 'lib/mongo/cursor.rb', línea 396

def kill_spec(connection_global_id)
  KillSpec.Nuevo(
    cursor_id: ID,
    coll_name: nombre_colección,
    db_name: database.Nombre,
    connection_global_id: connection_global_id,
    server_address: Server.dirección,
    sesión: @sesión,
    conexión: @connection
  )
end

#refresh_timeout! ⇒ Object

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Actualiza el contexto CSOT del cursor para que la siguiente operación getMore comience con un nuevo plazo de tiempo de espera. Utilizado por los cursores tailable awaitData para implementar la actualización por iteración del tiempo de espera según lo requerido por la especificación CSOT. Solo se actualiza si este es un cursor tailable awaitData con un tiempo de espera activo.



419
420
421
422
423
 
# Archivo 'lib/mongo/cursor.rb', línea 419

def refresh_timeout!
  return a menos que vista.cursor_type == tailable_await && context.¿tiempo agotado?

  @contexto = @contexto.actualizar(ver: vista)
end

#try_next ⇒ BSON::Document | nil

Este método es parte de una API privada. Se debe evitar el uso de este método si es posible, ya que podría eliminarse o modificarse en el futuro.

Nota:

Este método es experimental y está sujeto a cambios.

Devuelve un documento de la query, si hay uno disponible.

Este método esperará hasta un máximo de max_await_time_ms milisegundos por cambios del servidor, y si no se reciben cambios, devolverá nil. Si no quedan más documentos por devolver del servidor, o si hemos agotado el cursor, se generará una excepción StopIteration.

Devuelve:

  • (BSON::Document | nil) —

    Un documento.

Aumenta:

  • (StopIteration) —

    Se activó en las llamadas después de que el cursor se había iterado completamente.



217
218
219
220
221
222
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
 
# Archivo 'lib/mongo/cursor.rb', línea 217

def try_next
  si @documents.nil?
    # Dado que las versiones publicadas de Mongoid contienen una copia del cursor de driver antiguo
    # código, nuestra llamada dup en #process no se invoca cuando hay una query de Mongoid
    # La caché está activa. Soluciona eso llamando también a dup aquí en
    # el resultado de #proceso que podría derivarse del código de Mongoid.
    @documents = Proceso(@initial_result).dup
    # los documentos aquí pueden ser un arreglo vacío, por lo tanto
    # podemos terminar emitiendo un getMore en la primera llamada try_next
  end

  si @documents.¿vacío?
    # En los lotes vacíos, almacenamos en caché el token de reanudación del lote
    cache_batch_resume_token

    si ¿Cerrado?
      @fully_iterated = true
      propagar Detener iteración
    else
      si ¿agotado?
        Cerrar
        @fully_iterated = true
        propagar Detener iteración
      end
      @documents = obtener más
    end
  else
    # el cursor se cierra aquí
    # mantener los documentos como un arreglo vacío
  end

  # Si hay al menos un documento, guardar en caché su _id
  cache_resume_token(@documents[0]) si @documents[0]

  # Guarda en caché el token de reanudación por lotes si estamos iterando
  # sobre el último documento, o si el lote está vacío
  si @documents.Tamaño <= 1
    cache_batch_resume_token
    @fully_iterated = true si ¿Cerrado?
  end

  @documents.turno
end