Classe: Mongo::Cursor Private

Herda:
Objeto
  • Objeto
mostrar tudo
Estendido por:
Encaminhável
Inclui:
Enumerável , repetível
Definido em:
lib/mongo/cursor.rb,
lib/mongo/cursor/kill_spec.rb,
lib/mongo/cursor/nontailable.rb

Visão geral

Esta classe faz parte de uma API privada. Evite usar essa classe, se possível, pois ela pode ser removida ou alterada no futuro.

Representação do lado do cliente de um iterador sobre um conjunto de resultados de query no servidor.

Cursor objetos não estão diretamente expostos ao código do aplicativo. Em vez disso, Collection::View expõe a interface Enumerable aos aplicativos, e o enumerador é apoiado por uma instância Cursor .

Exemplos:

Obtenha uma array de 5 usuários chamados Emily.

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

Chame um bloco em cada documento de usuário.

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

Subclasses conhecidas diretas

CacheingCursor

Definido sob namespace

Módulos: Não rastreável Classes: KillSpec

Recolhimento do Resumo do atributo de instância

Recolhimento do Resumo do método de classe

Recolhimento do Resumo do método de instância

Métodos incluídos no Retryable

#read_worker, #select_server, #with_overload_retry, #write_worker

Detalhes do construtor

#inicializar(visualização, resultado, servidor, opções = {}) ➤ Cursor

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Cria um objeto Cursor .

Exemplos:

Instancie o cursor.

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

Parâmetros:

  • vista (CollectionView) —

    O CollectionView definindo a query.

  • Resultado (Operação::Resultado) —

    O resultado da primeira execução.

  • Servidor (Servidor MongoDB) —

    O servidor para o qual este cursor está bloqueado.

  • opções (Hash) (padrão para: {}) —

    As opções do cursor.

Hash de opções (opções):

  • :context (Operação::Contexto) —

    O contexto da operação para este cursor.

  • :disable_retry (verdadeiro, falso) —

    Se deve desabilitar a nova tentativa em caso de erro ao enviar operações getMore (descontinuadas, as operações getMore não são mais repetidas)

  • :retry_reads (verdadeiro, falso) —

    Tentar ler novamente (seguindo o mecanismo moderno), o padrão é verdadeiro

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
 
# Arquivo 'lib/mongo/cursor.rb', linha 72

def inicializar(vista, Resultado, Servidor, opções = {})
  a menos que Resultado.is_a?((operação)::Resultado)
    aumentar ArgumentError, "O segundo argumento deve ser um Mongo::Operation::Result: #{result.inspect}"
  end

  @view = vista
  @server = Servidor
  @initial_result = Resultado
  @namespace = Resultado.namespace
  @remaining = limit se limitado?
  set_cursor_id(Resultado)
  aumentar ArgumentError, ' OID do cursor deve estar presente no resultado' se @cursor_id.nada?

  @opções = opções
  @session = @opções[:session]
  @connection_global_id = Resultado.connection_global_id
  @context = @opções[:context]&.com(connection_global_id: connection_global_id_for_context) || refresh_context
  @explicitly_closed = false
  @get_more_network_error = false
  @ bloqueio = Mutex.Novo
  se Servidor.load_balancer?
    # Precisamos da conexão no cursor somente em topologia balanceada de carga;
    # não precisamos de uma referência adicional a ele de outra forma.
    @connection = @initial_result.Conexão
  end
  se fechado?
    check_in_connection
  mais
    register
    ObjectSpace.define_finalizer(
      auto,
      auto.classe.finalizar(kill_spec(@connection_global_id), cluster)
    )
  end
end

Detalhes do atributo da instância

#connection ➤ Object (somente leitura)

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro. 



115
116
117
 
# Arquivo 'lib/mongo/cursor.rb', linha 115

def Conexão
  @connection
end

#context ➤ Operação::Context (somente leitura)

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Retorna o contexto deste cursor.

Retorna:



51
52
53
 
# Arquivo 'lib/mongo/cursor.rb', linha 51

def Contexto
  @context
end

#initial_result ➤ Objeto (somente leitura)

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro. 



112
113
114
 
# Arquivo 'lib/mongo/cursor.rb', linha 112

def initial_result
  @initial_result
end

#resume_token ➤ BSON::Document | nil (somente leitura)

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

O token de retomada rastreado pelo cursor para a retomada do fluxo de alterações

Retorna:

  • (BSON::Document | nil) —

    O token de retomada do cursor.



48
49
50
 
# Arquivo 'lib/mongo/cursor.rb', linha 48

def resume_token
  @resume_token
end

#server ➤ Object (somente leitura)

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro. 



109
110
111
 
# Arquivo 'lib/mongo/cursor.rb', linha 109

def Servidor
  @server
end

#view ➤ Collection::View (readonly)

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Retorna a visualização A visualização da collection.

Retorna:



42
43
44
 
# Arquivo 'lib/mongo/cursor.rb', linha 42

def vista
  @view
end

Detalhes do método de classe

.finalizar(kill_spec, cluster) ➤ Proc

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Finalize o cursor para a coleção de lixo. Agenda este cursor para ser incluído em uma operação killCursors executada pelo CursorReaper do Cluster.

Parâmetros:

  • kill_spec (Cursor::KillSpec) —

    A especificação da operação KillCursor.

  • cluster (Mongo::Cluster) —

    O cluster associado a este cursor e seu servidor.

Retorna:

  • (Proc) —

    O Finalizador.

Aumenta:

  • (ArgumentError) 


126
127
128
129
130
131
132
 
# Arquivo 'lib/mongo/cursor.rb', linha 126

def auto.finalizar(kill_spec, cluster)
  aumentar ArgumentError, "O primeiro argumento deve ser um KillSpec: #{kill_spec.inspect}" a menos que kill_spec.is_a?(KillSpec)

  proc fazer
    cluster.agendamento_kill_cursor(kill_spec)
  end
end

Detalhes do método de instância

#batch_size ➤ Inteiro

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Obtenha o tamanho do lote .

Exemplos:

Obtenha o tamanho do lote .

cursor.batch_size

Retorna:

  • (Inteiro) —

    O tamanho do lote.

Desde:

  • 2.2.0



269
270
271
272
273
274
275
276
 
# Arquivo 'lib/mongo/cursor.rb', linha 269

def batch_size
  valor = (@view.batch_size && @view.batch_size > 0) ? @view.batch_size : limit
  se valor == 0
    nada
  mais
    valor
  end
end

#close(opts = {}) ➤ nil

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Fecha este cursor, liberando quaisquer recursos associados no cliente e no servidor.

Retorna:

  • (nil) —

    Sempre 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
 
# Arquivo 'lib/mongo/cursor.rb', linha 295

def Fechar(opciona = {})
  Método se fechado?

  ctx = Contexto ? Contexto.atualizar(timeout_ms: opciona[:timeout_ms]) : refresh_context(opciona)

  cancelar registro
  a menos que @get_more_network_error
    read_with_one_retry fazer
      especificações = {
        coll_name: collection_name,
        db_name: database.name,
        cursor_ids: [ id ],
      }
      op = (operação)::matarCursores.Novo(especificações)
      execute_operation(op, contexto: ctx)
    end
  end

  nada
salvar Erro::Falha de operação::família, Erro::Erro de soquete, Erro::SocketTimeoutError, Erro::ServerNotUsable, Erro::ConnectionPerished
  # Os erros são aceitos porque não há nada que possa ser feito ao gerenciá-los.
garantir
  end_session
  @cursor_id = 0
  @ bloqueio.sincronizar fazer
    @explicitly_closed = true
  end
  check_in_connection
end

#fechado? ➤ true, false

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

O cursor está fechado?

Exemplos:

O cursor está fechado?

cursor.closed?

Retorna:

  • (verdadeiro, falso) —

    Se o cursor estiver fechado.

Desde:

  • 2.2.0



286
287
288
289
 
# Arquivo 'lib/mongo/cursor.rb', linha 286

def fechado?
  # @cursor_id deve, em princípio, nunca ser nulo
  @cursor_id.nada? || @cursor_id == 0
end

#collection_name ➤ string

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Obtém o nome da coleção analisada.

Exemplos:

Obtém o nome da coleção analisada.

cursor.coll_name

Retorna:

  • (string) —

    O nome da collection.

Desde:

  • 2.2.0



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

def collection_name
  # Na maioria dos casos, será equivalente ao nome da collection
  # objeto no driver. No entanto, em alguns casos (por exemplo, quando conectado
  # para um Atlas Data Lake), o namespace retornado pelo comando find
  # pode ser diferente, e é por isso que queremos usar o nome da coleção com base
  # no namespace no resultado do comando.
  se @namespace
    # Muitas vezes, o namespace estará no formato "banco de dados.collection".
    # No entanto, às vezes, o nome da coleção conterá pontos, o que
    # é por isso que esse método une todos os componentes do namespace após o primeiro.
    ns_components = @namespace.dividir('.')
    ns_components[1...ns_components.Tamanho].juntar('.')
  mais
    collection.name
  end
end

#cada ➤ Enumerador

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Iterar através dos documentos retornados da query.

Um cursor pode ser iterado no máximo uma vez. Iteração incompleta também é permitida. A tentativa de iterar o cursor mais de uma vez gera InvalidCursorOperation.

Exemplos:

Iterar sobre os documentos no cursor.

cursor.each do |doc|
  ...
end

Retorna:

  • (Enumerador) —

    O 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
 
# Arquivo 'lib/mongo/cursor.rb', linha 160

def cada
  # Se já iteramos além do primeiro lote (ou seja, chamado get_more
  # pelo menos uma vez), o cursor no lado do servidor avançou além
  # o primeiro lote e reiniciando a iteração desde o início por
  # retornar o resultado inicial perderia documentos no segundo lote
  # e lotes subsequentes até onde estiver o cursor. Detectar isso
  # condição e abortar a iteração.
  #
  # Em uma versão futura do driver, cada um continuaria do
  # fim da iteração anterior ou sempre reiniciaria a partir do
  # início.
  se @get_more_ call
    aumentar Erro::InvalidCursorOperation, 'Não é possível reiniciar a iteração de um cursor que emitiu um getMore'
  end

  # Para manter a compatibilidade com a pré-2.10 versões do driver, redefinir
  # a array de documentos cada vez que uma nova iteração é iniciada.
  @documents = nada

  se block_given?
    # A StopIteration gerada por try_next encerra este loop.
    loop fazer
      documento = try_next
      aumentar Erro::InvalidCursorOperation, ' Ocursor foi explicitamente fechado' se explicitamente_closed?

      rendimento documento se documento
    end
    auto
  mais
    documentos = []
    # A StopIteration gerada por try_next encerra este loop.
    loop fazer
      documento = try_next
      aumentar Erro::InvalidCursorOperation, ' Ocursor foi explicitamente fechado' se explicitamente_closed?

      documentos << documento se documento
    end
    documentos
  end
end

#full_iterated? ➤ Booleano

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Retorna:

  • (Booleano) 


409
410
411
 
# Arquivo 'lib/mongo/cursor.rb', linha 409

def full_iterated?
  !!@full_iterated
end

#get_more ➤ Array<BSON::Document>

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Execute um comando getMore e retorne o lote de documentos obtidos do servidor.

Retorna:

  • (Array<BSON::Document>) —

    O 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
 
# Arquivo 'lib/mongo/cursor.rb', linha 370

def get_more
  @get_more_ call = true

  # A especificação moderna de leituras repetíveis proíbe a repetição de getMores.
  # A lógica legada de leitura repetível usada para tentar novamente getMores, mas desde
  # isso pode resultar em perda silenciosa de dados, o motorista não tenta mais
  # operações getMore em qualquer circunstância.
  # https://github.com/mongodb/specifications/blob/master/source/retryable-reads/retryable-reads.md#qa
  #
  # No entanto, erros de sobrecarga (SystemOverloadedError + RetryableError) são
  # tentou com backoff exponencial desde o servidor nunca processado
  # a solicitação.
  with_overload_retry(contexto: possivelmente_refreshed_context) fazer
    Processo(execute_operation(get_more_operation))
  end
salvar Erro::Erro de soquete, Erro::SocketTimeoutError
  @get_more_network_error = true
  aumentar
salvar Erro::Falha de operação => e
  # Quando as tentativas de sobrecarga se esgotarem no getMore, feche o cursor
  # para que o killCursors seja enviado ao servidor.
  Fechar se e.rótulo?('RetryableError') && e.rótulo?('SystemOverloadedError')
  aumentar
end

#id ⇒ Integer

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Observação:

Um ID de cursor de 0 significa que o cursor foi fechado no servidor.

Obtenha o ID do cursor.

Exemplos:

Obtenha o ID do cursor.

cursor.id

Retorna:

  • (Inteiro) —

    O ID do cursor.

Desde:

  • 2.2.0



360
361
362
 
# Arquivo 'lib/mongo/cursor.rb', linha 360

def id
  @cursor_id
end

#inspecionar ➤ string

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Obtenha uma representação de string legível por humanos de Cursor.

Exemplos:

Inspecione o cursor.

cursor.inspect

Retorna:

  • (string) —

    Uma representação de string de uma instância do Cursor .

Desde:

  • 2.0.0



142
143
144
 
# Arquivo 'lib/mongo/cursor.rb', linha 142

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

#kill_spec(connection_global_id) ➤ Objeto

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro. 



396
397
398
399
400
401
402
403
404
405
406
 
# Arquivo 'lib/mongo/cursor.rb', linha 396

def kill_spec(connection_global_id)
  KillSpec.Novo(
    cursor_id: id,
    coll_name: collection_name,
    db_name: database.name,
    connection_global_id: connection_global_id,
    server_address: Servidor.endereço,
    sessão: @session,
    conexão: @connection
  )
end

#refresh_timeout! ➤ Objeto

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Atualiza o contexto CSOT do cursor para que o próximo getMore comece com um novo prazo de tempo limite. Usado por cursores tailable awaitData para implementar a atualização do tempo limite por iteração, conforme exigido pela especificação do CSOT. Só é atualizado se este for um cursor tailable awaitData com um tempo limite ativo.



419
420
421
422
423
 
# Arquivo 'lib/mongo/cursor.rb', linha 419

def refresh_timeout!
  Método a menos que vista.cursor_type == :tailable_await && Contexto.tempo-limite?

  @context = @context.atualizar(visualizar: vista)
end

#try_next ➤ BSON::Document | nada

Este método faz parte de uma API privada. Evite usar esse método, se possível, pois ele pode ser removido ou alterado no futuro.

Observação:

Este método é experimental e sujeito a alterações.

Retorne um documento da query, se houver um disponível.

Este método aguardará até max_await_time_ms milissegundos por alterações do servidor e, se nenhuma alteração for recebida, retornará nulo. Se não houver mais documentos para retornar do servidor, ou se tivermos esgotado o cursor, será gerada uma exceção de StopIteration.

Retorna:

  • (BSON::Document | nil) —

    Um documento.

Aumenta:

  • (StopIteration) —

    Elevado nas chamadas depois que o cursor tiver sido completamente iterado.



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
 
# Arquivo 'lib/mongo/cursor.rb', linha 217

def try_next
  se @documents.nada?
    # Como as versões publicadas do Mongoid têm uma cópia do cursor do driver antigo
    # code, nossa chamada dup em #process não é invocada quando Mongoid query
    # cache está ativo. Contorne isso ligando para dup aqui em
    # o resultado de #process que pode sair do código do Mongoid.
    @documents = Processo(@initial_result).dup
    # os documentos aqui podem ser uma array vazia, portanto
    # podemos acabar emitindo um getMore na primeira chamada try_next
  end

  se @documents.vazio?
    # Em lotes vazios, armazenamos em cache o token de retomada do lote
    cache_batch_resume_token

    se fechado?
      @full_iterated = true
      aumentar StopIteration
    mais
      se esgotado?
        Fechar
        @full_iterated = true
        aumentar StopIteration
      end
      @documents = get_more
    end
  mais
    # cursor está fechado aqui
    # mantém documentos como um array vazio
  end

  # Se houver pelo menos um documento, armazene em cache seu _id
  cache_resume_token(@documents[0]) se @documents[0]

  # Armazene em cache o token de retomada do lote se estivermos iterando
  # sobre o último documento ou se o lote estiver vazio
  se @documents.Tamanho <= 1
    cache_batch_resume_token
    @full_iterated = true se fechado?
  end

  @documents.mudança
end