/ /

/ /

Kotlin Coroutine 驱动程序

Fundamentals

连接指南

限制MongoDB Server执行时间

Overview

当您使用Kotlin驾驶员执行服务器操作时，您还可以限制服务器可以完成该操作的时间。为此，请指定客户端操作超时 (CSOT)。超时适用于完成操作所需的所有步骤，包括服务器选择、连接签出和服务器端执行。超时后， Kotlin驾驶员会引发超时异常。

注意

实验功能

CSOT功能是实验性的，可能在未来的驱动程序发布中发生变化。

timeoutMS 选项

要在连接到MongoDB 部署时指定超时，请将 timeoutMS 连接选项设立为超时长度（以毫秒为单位）。您可以通过以下方式设立timeoutMS 选项：

从 MongoClientSettings.Builder 类调用 timeout() 方法
在连接string中设置 timeoutMS 参数

以下代码示例将客户端级超时设立为 200 毫秒。选择 MongoClientSettings 或 Connection String标签页以查看相应的代码。

val settings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString("<connection string>"))
    .timeout(200L, TimeUnit.MILLISECONDS)
    .build()
val client = MongoClient.create(settings)

val uri = "<connection string>/?timeoutMS=200"
val client = MongoClient.create(uri)

接受的超时值

下表描述了与 timeoutMS 的可接受值相对应的超时行为：

值	行为
正整数	设置操作完成时使用的超时时间。
`0`	指定操作永不超时。
`null` 或未设置	Defers the timeout behavior to the following settings: waitQueueTimeoutMS socketTimeoutMS wtimeoutMS maxTimeMS maxCommitTimeMS These settings are deprecated and are ignored if you set `timeoutMS`.

如果指定 timeoutMS 选项，驾驶员会自动将指定的超时应用于每个服务器操作。以下代码示例在客户端端级别指定 200 毫秒的超时，然后调用 MongoCollection.insertOne() 方法：

val settings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString("<connection string>"))
    .timeout(200L, TimeUnit.MILLISECONDS)
    .build()
val client = MongoClient.create(settings)
val collection = client
    .getDatabase("db")
    .getCollection<Document>("people")
collection.insertOne(Document("name", "Francine Loews"))

超时继承

当您指定 timeoutMS 选项时，驾驶员会根据与其他Kotlin驾驶员选项相同的继承行为应用超时。下表描述了如何在每个级别继承超时值：

等级	继承说明
操作	具有最高优先级，并覆盖您在任何其他级别设立的超时选项。
事务	优先于您在会话、集合、数据库或客户端级别设立的超时值。
会话	适用于该会话中的所有事务和操作，除非您在这些级别设立了不同的超时值。
Database	适用于该数据库中的所有会话和操作，除非您在这些级别设立了不同的超时值。
Collection	适用于该集合上的所有会话和操作，除非您在这些级别设立了不同的超时值。
客户	适用于该客户端内未指定 `timeoutMS` 的所有数据库、集合、会话、事务和操作。

有关覆盖和特定选项的更多信息，请参阅以下覆盖部分。

覆盖

Kotlin驾驶员支持各种级别的配置来控制数据库操作的行为和性能。

您可以在更具体的级别指定 timeoutMS 选项来覆盖客户端级别的配置。上一节中的表描述了可以指定超时设置的级别。这允许您根据各个操作的需求自定义超时。

以下示例演示了集合级超时配置如何覆盖客户端级超时配置：

val settings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString("<connection string>"))
    .timeout(200L, TimeUnit.MILLISECONDS)
    .build()
val client = MongoClient.create(settings)
val database = client.getDatabase("db")
val collection = database
    .getCollection<Document>("people")
    .withTimeout(300L, TimeUnit.MILLISECONDS)

事务

当您创建新的ClientSession实例来实现ACID 事务时，请在构建 ClientSessionOptions实例时使用 defaultTimeout() 方法。您可以使用此选项指定以下方法的超时时间：

以下代码演示了如何在实例化 ClientSession 时设立defaultTimeout：

val opts = ClientSessionOptions.builder()
    .defaultTimeout(200L, TimeUnit.MILLISECONDS)
    .build()
val session = client.startSession(opts)
// ... perform operations on ClientSession

如果未指定 defaultTimeout，驾驶员将使用在父项 MongoClient 上设立的超时值。

您还可以在构建 TransactionOptions实例时调用 timeout() 方法来设立事务级超时。设置此选项会将超时应用于在ACID 事务范围内执行的所有操作：

val transactionOptions = TransactionOptions.builder()
    .timeout(200L, TimeUnit.MILLISECONDS)
    .build()

要学习；了解有关事务的更多信息，请参阅事务指南。

客户端加密

使用客户端字段级加密(CSFLE) 时，驾驶员使用 timeoutMS 选项来限制加密和解密操作所允许的时间。您可以在构建 ClientEncryptionSettings实例时调用 timeout() 方法，为 ClientEncryption实例设立超时选项。

如果在构造 ClientEncryption实例时指定了超时，则该超时将控制对该实例执行的所有操作的生命周期。如果在实例化 ClientEncryption 时未提供超时，则该实例将从 ClientEncryption 构造函数中使用的 MongoClient 继承超时设置。

如果您在客户端和直接在 ClientEncryption 中同时设立timeoutMS，则提供给 ClientEncryption 的值优先。

Cursors

使用 CSOT功能时，游标提供可配置的超时设置。您可以通过配置游标生存期或游标迭代模式来调整游标处理。要配置超时模式，请在执行任何返回继承 Flow 的结果的操作时使用 timeoutMode() 方法。

对于创建游标的操作，超时设置可以限制游标的生命周期，也可以单独应用于原始操作和所有后续调用。

注意

继承超时

要设置游标超时模式，需要在 MongoClientSettings、MongoDatabase 或 MongoCollection 中设立超时。

要学习；了解有关游标和流的更多信息，请参阅《从流访问数据》指南。

游标生命周期模式

游标生命周期模式使用超时设置来限制游标的整个生命周期。在此模式下，应用程序必须初始化游标，完成对游标方法的所有调用，并在指定的时限内返回所有文档。否则，游标的生命周期将到期，并且驾驶员会引发超时错误。

通过调用 close() 方法关闭游标时，killCursors 命令的超时时间将重置，以确保清理服务器端资源。

以下示例展示了如何设立游标超时，以确保在继承的超时时间内初始化游标并检索所有文档：

val flowWithLifetimeTimeout = collection
    .find(Filters.gte("age", 40))
    .timeoutMode(TimeoutMode.CURSOR_LIFETIME)

API 文档

要学习；了解有关在Kotlin驾驶员中使用超时的更多信息，请参阅以下API文档：

后退

MongoClient 设置

来年

网络压缩