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

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, #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

Desde:

  • 2.0.0

[Ver fonte]

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

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)
  se @cursor_id.nada?
    aumentar ArgumentError, ' OID do cursor deve estar presente no resultado'
  end
  @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
  @ 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

#connectionObject (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.


117
118
119
# Arquivo 'lib/mongo/cursor.rb', linha 117

def Conexão
  @connection
end

#contextOperaçã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:


53
54
55
# Arquivo 'lib/mongo/cursor.rb', linha 53

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.


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

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.


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

def resume_token
  @resume_token
end

#serverObject (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.


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

def Servidor
  @server
end

#viewCollection::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:


44
45
46
# Arquivo 'lib/mongo/cursor.rb', linha 44

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

[Ver fonte]

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

def auto.finalizar(kill_spec, cluster)
  a menos que KillSpec === kill_spec
    aumentar ArgumentError, "O primeiro argumento deve ser um KillSpec: #{kill_spec.inspect}"
  end
  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

[Ver fonte]

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

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.

[Ver fonte]

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

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

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

  cancelar registro
  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

  nada
salvar Erro::Falha de operação::família, Erro::Erro de soquete, Erro::SocketTimeoutError, Erro::ServerNotUsable
  # Os erros são aceitos porque é possível fazer anotações ao lidar com eles.
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

[Ver fonte]

296
297
298
299
# Arquivo 'lib/mongo/cursor.rb', linha 296

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

#collection_namestring

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

[Ver fonte]

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

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

#cadaEnumerador

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

[Ver fonte]

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

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
      se explicitamente_closed?
        aumentar Erro::InvalidCursorOperation, ' Ocursor foi explicitamente fechado'
      end
      rendimento documento se documento
    end
    auto
  mais
    documentos = []
    # A StopIteration gerada por try_next encerra este loop.
    loop fazer
      documento = try_next
      se explicitamente_closed?
        aumentar Erro::InvalidCursorOperation, ' Ocursor foi explicitamente fechado'
      end
      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)
[Ver fonte]

416
417
418
# Arquivo 'lib/mongo/cursor.rb', linha 416

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

[Ver fonte]

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

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
  Processo(execute_operation(get_more_operation))
end

#idInteger

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

[Ver fonte]

368
369
370
# Arquivo 'lib/mongo/cursor.rb', linha 368

def id
  @cursor_id
end

#inspecionarstring

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

[Ver fonte]

145
146
147
# Arquivo 'lib/mongo/cursor.rb', linha 145

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.

[Ver fonte]

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

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

#to_returnInteger

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 número de documentos a serem retornados. Usado em 3.0 e versões de servidor inferiores.

Exemplos:

Obtenha o número para retornar.

cursor.to_return

Retorna:

  • (Inteiro)

    O número de documentos a retornar.

Desde:

  • 2.2.0

[Ver fonte]

381
382
383
# Arquivo 'lib/mongo/cursor.rb', linha 381

def to_return
  use_limit? ? @remaining : (batch_size || 0)
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.

[Ver fonte]

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

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

    a menos que fechado?
      se esgotado?
        Fechar
        @full_iterated = true
        aumentar StopIteration
      end
      @documents = get_more
    mais
      @full_iterated = true
      aumentar StopIteration
    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
  se @documents[0]
    cache_resume_token(@documents[0])
  end

  # 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
    se fechado?
      @full_iterated = true
    end
  end

  Método @documents.mudança
end