类：Mongo::Cursor Private

继承：
对象
  • 对象
显示全部
扩展方式：
可转发
包括：
可枚举、可重试
定义于：
lib/mongo/cursor.rb,
lib/mongo/cursor/kill_spec.rb,
lib/mongo/cursor/nontailable.rb

Overview

此类是私有 API 的一部分。 应尽可能避免使用此类，因为它将来可能会被删除或更改。

针对服务器上查询结果设立的迭代器的客户端表示形式。

Cursor 对象不直接公开给应用程序代码。 相反， Collection::View向应用程序公开Enumerable接口，并且枚举器由Cursor实例支持。

例子：

获取名为 Emily 的5用户大量。

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

在每个用户文档上调用一个区块。

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

直接已知子类

缓存游标

在命名空间下定义

模块： NonTailable 类： KillSpec

实例属性摘要折叠

类方法摘要折叠

实例方法摘要折叠

Retryable 中包含的方法

#read_worker、#select_server、#with_overload_retry、#write_worker

构造函数详情

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

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

创建一个Cursor对象。

例子：

实例化游标。

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

参数：

  • 查看 ( CollectionView ) —

    定义查询的CollectionView 。

  • 结果 ( Operation::Result ) —

    第一次执行的结果。

  • server ( MongoDB Server ) —

    此游标锁定到的服务器。

  • 选项 （哈希） （默认为： {} ） —

    游标选项。

选项哈希 ( options )：

  • :context （Operation::Context） —

    此游标的操作上下文。

  • :disable_retry ( true , false ) —

    发送 getMore 操作时是否禁用出错重试（已弃用，不再重试 getMore 操作）

  • :retry_reads ( true , false ) —

    重试读取（遵循现代机制），默认值为 true

引发：

  • ( ArgumentError )

由于：

  • 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
 
# File 'lib/ Mongo/ 游标.rb', 第 72 行

def 初始化(查看, 结果, server, 选项 = {})
  除非 结果.is_a?(操作::结果)
    提高 ArgumentError, "第二个参数必须是 Mongo::Operation::Result: #{ result .inspect } } "
  end

  @view = 查看
  @server = server
  @initial_result = 结果
  @namespace = 结果.namespace
  @remaining = limit if 有限？
  set_cursor_id(结果)
  提高 ArgumentError, '游标 ID 必须出现在结果中' if @cursor_id.nil?

  @options = 选项
  @session = @options[:session]
  @connection_global_id = 结果.connection_global_id
  @context = @options[:context]&。通过(connection_global_id: connection_global_id_for_context) || fresh_context
  @explicitly_close = false
  @get_more_network_error = false
  锁 = 互斥锁.new
  if server.load_balancer？
    # 只有在负载均衡拓扑结构结构中，我们才需要游标中的连接；
    # 否则，我们不需要对它进行额外的引用。
    @connection = @initial_result.连接
  end
  if 已关闭？
    check_in_connection
  else
    报名
    ObjectSpace.define_finalizer(
      self,
      self.class.finalize(kill_spec(@connection_global_id), 集群)
    )
  end
end

实例属性详细信息

# 连接 ⇒ 对象（只读）

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。 



115
116
117
 
# File 'lib/ Mongo/ 游标.rb', 第 115 行

def 连接
  @connection
end

# context ="Operation::Context (readonly)"

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回 context 此游标的上下文。

返回：



51
52
53
 
# File 'lib/ Mongo/ 游标.rb', 第 51 行

def 上下文
  @context
end

#initial_result ⇒对象（只读）

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。 



112
113
114
 
# File 'lib/ Mongo/ 游标.rb', 第 112 行

def Initial_result
  @initial_result
end

#resume_token ⇒ BSON::Document | nil （只读）

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

游标跟踪的用于变更流恢复的恢复令牌

返回：

  • ( BSON::Document | nil ) —

    游标恢复令牌。



48
49
50
 
# File 'lib/ Mongo/ 游标.rb', 第 48 行

def resume_token
  @resume_token
end

# server ⇒对象（只读）

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。 



109
110
111
 
# File 'lib/ Mongo/ 游标.rb', 第 109 行

def server
  @server
end

# view ⇒ Collection::View (readonly)

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回视图集合视图。

返回：



42
43
44
 
# File 'lib/ Mongo/ 游标.rb', 第 42 行

def 查看
  @view
end

类方法详细信息

。 finalize (kill_spec, cluster) ⇒ Proc

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

完成游标以进行垃圾集合。安排此游标包含在由集群的 CursorReaper 执行的 killCursors 操作中。

参数：

返回：

  • ( Proc ) —

    终结器。

引发：

  • ( ArgumentError ) 


126
127
128
129
130
131
132
 
# File 'lib/ Mongo/ 游标.rb', 第 126 行

def self.finalize(kill_spec, 集群)
  提高 ArgumentError, " 第一个参数必须是 KillSpec: # { kill_spec .inspect } } " 除非 kill_spec.is_a?(KillSpec)

  proc do
    集群.schedule_kill_cursor(kill_spec)
  end
end

实例方法详细信息

# batch_size ⇒整数

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

获取批处理大小。

例子：

获取批处理大小。

cursor.batch_size

返回：

  • ( Integer ) —

    批量大小。

由于：

  • 2.2.0



269
270
271
272
273
274
275
276
 
# File 'lib/ Mongo/ 游标.rb', 第 269 行

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

# close (opts = {}) ⇒ nil

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

关闭此游标，从而释放客户端和服务器上的所有关联资源。

返回：

  • ( nil ) —

    始终为零。



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
 
# File 'lib/ Mongo/ 游标.rb', 第 295 行

def 关闭(opts = {})
  return if 已关闭？

  ctx = 上下文 ? 上下文.刷新(timeout_ms: opts[:timeout_ms]) : fresh_context(opts)

  取消注册
  除非 @get_more_network_error
    read_with_one_retry do
      spec = {
        coll_name: collection_name,
        db_name: database.名称,
        cursor_id: [ id ],
      }
      op = 操作::killCursors.new(spec)
      execute_operation(op, 上下文： ctx)
    end
  end

  nil
救援 错误::OperationFailure::家庭情况, 错误::SocketError, 错误::SocketTimeoutError, 错误::ServerNotUsable, 错误::ConnectionPershed
  # 错误会被吞掉，因为无法处理这些错误。
确保
  end_session
  @cursor_id = 0
  锁.同步 do
    @explicitly_close = true
  end
  check_in_connection
end

#已关闭？ ⇒ true , false

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

游标是否已关闭？

例子：

游标是否已关闭？

cursor.closed?

返回：

  • ( true , false ) —

    如果游标已关闭。

由于：

  • 2.2.0



286
287
288
289
 
# File 'lib/ Mongo/ 游标.rb', 第 286 行

def 已关闭？
  # 原则上，@cursor_id 不应为 nil
  @cursor_id.nil? || @cursor_id == 0
end

# collection_name ⇒ string

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

获取解析的集合名称。

例子：

获取解析的集合名称。

cursor.coll_name

返回：

  • ( string ) —

    collection名称。

由于：

  • 2.2.0



333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/ Mongo/ 游标.rb', 第 333 行

def collection_name
  # 在大多数情况下，这相当于集合的名称
  # 驱动程序中的对象。但是，在某些情况下（例如，当连接
  # 到Atlas Data Lake），find 命令返回的命名空间
  # 可能不同，这就是为什么我们要使用基于集合名称的
  # 命令结果中的命名空间。
  if @namespace
    # 通常，命名空间的集合为“ 数据库 ”。
    # 但是，有时集合名称会包含句点，这
    # 就是该方法连接第一个之后的所有命名空间组件的原因。
    ns_components = @namespace.拆分(' 。 ')
    ns_components[1...ns_components.长度].连接 (JOIN)(' 。 ')
  else
    集合.名称
  end
end

#each ⇒枚举器

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

遍历从查询返回的文档。

一个游标最多只能迭代一次。 不完整迭代也是允许的。 尝试多次迭代游标会引发 InvalidCursorOperation。

例子：

遍历游标中的文档。

cursor.each do |doc|
  ...
end

返回：

  • (枚举器) —

    枚举器。

由于：

  • 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
 
# File 'lib/ Mongo/ 游标.rb', 第 160 行

def 每
  # 如果我们已经遍历了第一批（即调用了 get_more
  # 至少一次），服务器端的游标已前进到
  # 第一个批处理，然后从头开始重新启动迭代
  # 返回初始结果会丢失第二批处理中的文档
  # 和后续批处理，直到游标所在的位置。 检测此
  # 条件并中止迭代。
  #
  # 在未来的驱动程序版本中，每个版本都会继续执行
  # 上一次迭代结束，或者始终从
  # 开始。
  if @get_more_used
    提高 错误::InvalidCursorOperation, '无法重新启动发出 getMore 的游标的迭代'
  end

  # 保持与2.10之前版本的兼容性 驱动程序版本，重置
  # 每次开始新的迭代时，文档大量。
  @documents = nil

  if block_given?
    # 由 try_next 引发的 StopIteration 会结束此循环。
    循环 do
      文档 = try_next
      提高 错误::InvalidCursorOperation, '游标已显式关闭' if 明确关闭？

      产量 文档 if 文档
    end
    self
  else
    文档 = []
    # 由 try_next 引发的 StopIteration 会结束此循环。
    循环 do
      文档 = try_next
      提高 错误::InvalidCursorOperation, '游标已显式关闭' if 明确关闭？

      文档 << 文档 if 文档
    end
    文档
  end
end

# full_iterated? ⇒布尔

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

返回：

  • （布尔值） 


409
410
411
 
# File 'lib/ Mongo/ 游标.rb', 第 409 行

def full_iterated?
  !!@Fully_iterated
end

# get_more ⇒ Array<BSON::Document>

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

执行 getMore 命令并返回从服务器获取的批处理文档。

返回：

  • ( Array<BSON::Document> ) —

    批处理文档



370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
 
# File 'lib/ Mongo/ 游标.rb', 第 370 行

def get_more
  @get_more_used = true

  # 现代可重试读取规范禁止重试 getMores。
  # 用于重试 getMores 的传统可重试读取逻辑，但由于
  # 这样做可能会导致静默数据丢失，驱动程序不再重试
  # 在任何情况下都可以执行 getMore 操作。
  # https://github.com/mongodb/specifications/blob/master/source/retryable-reads/retryable-reads.md#qa
  #
  # 但是，重载错误 (SystemOverloadedError + RetryableError) 会
  # 使用指数退避算法重试，因为服务器从未处理过
  #请求。
  with_overload_retry(上下文： possible_refreshed_context) do
    处理(execute_operation(get_more_operation))
  end
救援 错误::SocketError, 错误::SocketTimeoutError
  @get_more_network_error = true
  提高
救援 错误::OperationFailure => e
  # 当 getMore 的重试次数用尽时，关闭游标
  # 以便将 killCursors 发送到服务器。
  关闭 if e.标签？('RetryableError') && e.标签？('SystemOverloadedError')
  提高
end

#id ⇒ Integer

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

注意：

游标ID 为0表示游标已在服务器上关闭。

获取游标 ID。

例子：

获取游标 ID。

cursor.id

返回：

  • ( Integer ) —

    游标 ID。

由于：

  • 2.2.0



360
361
362
 
# File 'lib/ Mongo/ 游标.rb', 第 360 行

def id
  @cursor_id
end

#检查⇒ string

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

获取 Cursor 的人类可读string表示形式。

例子：

检查游标。

cursor.inspect

返回：

  • ( string ) —

    Cursor 实例的string表示形式。

由于：

  • 2.0.0



142
143
144
 
# File 'lib/ Mongo/ 游标.rb', 第 142 行

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

# kill_spec (connection_global_id) ⇒对象

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。 



396
397
398
399
400
401
402
403
404
405
406
 
# File 'lib/ Mongo/ 游标.rb', 第 396 行

def kill_spec(connection_global_id)
  KillSpec.new(
    cursor_id: id,
    coll_name: collection_name,
    db_name: database.名称,
    connection_global_id: connection_global_id,
    server_address: server.地址,
    会话： @session,
    连接： @connection
  )
end

# refresh_timeout! ⇒ 对象

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

刷新游标的 CSOT 上下文，以便下一个 getMore 以新的超时截止时间开始。由可追加的 awaitData 游标用于根据 CSOT 规范的要求实现每次迭代超时刷新。仅当这是具有活动超时的可追加 awaitData游标时才进行刷新。



419
420
421
422
423
 
# File 'lib/ Mongo/ 游标.rb', 第 419 行

def refresh_timeout!
  return 除非 查看.cursor_type == :tailable_await && 上下文.超时？

  @context = @context.刷新(视图： 查看)
end

# try_next ⇒ BSON::Document | nil

此方法是私有 API 的一部分。 您应尽可能避免使用此方法，因为它将来可能会被删除或更改。

注意：

此方法是实验性的，可能会发生变化。

从查询中返回一份文档（如果有）。

此方法将等待来自服务器的更改长达 max_await_time_ms 毫秒，如果没有收到更改，将返回 nil。 如果没有更多文档可从服务器返回，或者游标已耗尽，则会引发 StopIteration 异常。

返回：

  • ( BSON::Document | nil ) —

    一个文档。

引发：

  • ( StopIteration ) —

    在游标完全迭代后进行调用时引发此警报。



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
 
# File 'lib/ Mongo/ 游标.rb', 第 217 行

def try_next
  if @documents.nil?
    # 由于已发布的 Mongoid 版本具有旧驱动程序游标的副本
    # 代码，当 Mongoid查询时，不会调用 #进程中的 dup 调用
    # 缓存处于活动状态。 通过在此处同时调用 dup 来解决此问题
    # 可能来自 Mongoid 代码的 #进程的结果。
    @documents = 处理(@initial_result).dup
    # 这里的文档可以是空数组，因此
    # 我们最终可能会在第一次 try_next 调用中发出 getMore
  end

  if @documents.空？
    # 对于空批次，我们缓存批处理恢复令牌
    cache_batch_resume_token

    if 已关闭？
      @Fully_iterated = true
      提高 StopIteration
    else
      if 精疲力尽？
        关闭
        @Fully_iterated = true
        提高 StopIteration
      end
      @documents = get_more
    end
  else
    # 游标在此处已关闭
    # 将文档保留为空大量
  end

  # 如果至少有一个文档，则缓存其_id
  cache_resume_token(@documents[0]) if @documents[0]

  # 如果要迭代，则缓存批处理恢复令牌
  # 超过最后一个文档，或者如果批次为空
  if @documents.size <= 1
    cache_batch_resume_token
    @Fully_iterated = true if 已关闭？
  end

  @documents.转变
end