编辑“︁Kotlin协程超时”︁

= Kotlin协程超时 =

== 介绍 ==
在Kotlin协程中，'''超时'''（Timeout）是一种重要的机制，用于限制协程的执行时间，防止长时间运行的任务阻塞程序或消耗过多资源。超时机制允许开发者设置一个时间上限，如果协程在该时间内未完成，则会自动取消并抛出异常。

超时在以下场景中特别有用：
* 网络请求（避免因服务器响应慢而卡住UI）
* 数据库操作（防止查询时间过长）
* 任何可能长时间运行的任务（文件I/O、复杂计算等）

Kotlin提供了两种主要方式实现超时控制：
1. `withTimeout` - 超时后抛出`TimeoutCancellationException`
2. `withTimeoutOrNull` - 超时后返回`null`而不抛出异常

== 基础用法 ==

=== withTimeout ===
`syntaxhighlight`块展示基本用法：

<syntaxhighlight lang="kotlin">
import kotlinx.coroutines.*

suspend fun fetchData(): String {
    delay(1000) // 模拟耗时操作
    return "Data fetched"
}

fun main() = runBlocking {
    try {
        val result = withTimeout(500) { // 设置500ms超时
            fetchData()
        }
        println(result)
    } catch (e: TimeoutCancellationException) {
        println("Operation timed out")
    }
}
</syntaxhighlight>

输出：
<pre>
Operation timed out
</pre>

解释：
* 我们设置500ms超时，但`fetchData()`需要1000ms完成
* 超时后会抛出`TimeoutCancellationException`
* 使用try-catch捕获异常进行优雅处理

=== withTimeoutOrNull ===
替代方案，不抛出异常：

<syntaxhighlight lang="kotlin">
fun main() = runBlocking {
    val result = withTimeoutOrNull(500) {
        fetchData()
    }
    println(result ?: "Operation returned null due to timeout")
}
</syntaxhighlight>

输出：
<pre>
Operation returned null due to timeout
</pre>

== 高级特性 ==

=== 嵌套超时 ===
超时可以嵌套，内层超时必须小于外层：

<syntaxhighlight lang="kotlin">
fun main() = runBlocking {
    try {
        withTimeout(1000) {
            withTimeout(500) { // 必须 <= 1000
                fetchData()
            }
        }
    } catch (e: TimeoutCancellationException) {
        println("Nested timeout caught: ${e.message}")
    }
}
</syntaxhighlight>

=== 资源清理 ===
超时取消时，协程的取消是协作式的，需要在代码中检查取消状态：

<syntaxhighlight lang="kotlin">
suspend fun processFile() {
    val file = openFile()
    try {
        withTimeout(1000) {
            while (hasMoreData()) {
                ensureActive() // 检查取消状态
                readNextChunk()
            }
        }
    } finally {
        file.close() // 确保资源释放
    }
}
</syntaxhighlight>

== 实际应用案例 ==

=== 网络请求超时 ===
典型HTTP客户端实现：

<syntaxhighlight lang="kotlin">
suspend fun fetchUserProfile(userId: String): Profile? {
    return withTimeoutOrNull(3000) { // 3秒超时
        val response = httpClient.get<Profile>("$API_URL/users/$userId")
        if (!response.isSuccessful) null else response.body()
    }
}
</syntaxhighlight>

=== 并行任务竞速 ===
使用超时获取最快响应：

<syntaxhighlight lang="kotlin">
suspend fun fetchFromFastestServer(): String {
    val deferred1 = async { fetchFromServer1() }
    val deferred2 = async { fetchFromServer2() }
    
    return withTimeoutOrNull(1000) {
        select<String> {
            deferred1.onAwait { it }
            deferred2.onAwait { it }
        }
    } ?: throw TimeoutException("No server responded in time")
}
</syntaxhighlight>

== 超时与取消的关系 ==
超时本质上是协程取消的一种特殊形式。当超时发生时：
1. 协程作用域被取消
2. 抛出`TimeoutCancellationException`（`withTimeout`）
3. 所有子协程也被取消

<mermaid>
sequenceDiagram
    participant Main
    participant Coroutine
    participant Timer
    
    Main->>Coroutine: 启动(withTimeout)
    Main->>Timer: 启动计时
    alt 正常完成
        Coroutine-->>Main: 返回结果
        Timer-->>Main: 取消计时
    else 超时
        Timer->>Coroutine: 发送取消信号
        Coroutine-->>Main: 抛出异常
    end
</mermaid>

== 数学表示 ==
超时操作可以形式化表示为：

<math>
T_{out}(f, \Delta t) = \begin{cases}
f() & \text{if } t_{exec} \leq \Delta t \\
\perp & \text{otherwise}
\end{cases}
</math>

其中：
* <math>f</math> 是要执行的函数
* <math>\Delta t</math> 是超时时间
* <math>t_{exec}</math> 是实际执行时间
* <math>\perp</math> 表示超时（取消）

== 最佳实践 ==
1. 为不同操作设置合理的超时时间
2. 总是处理超时异常或检查null结果
3. 在长时间循环中定期调用`ensureActive()`
4. 使用`try-finally`确保资源释放
5. 避免在UI线程使用无超时的挂起函数

== 常见问题 ==

'''Q: 为什么我的协程没有在超时时立即停止？'''
A: Kotlin的取消是协作式的。确保在长时间运行的任务中定期检查取消状态（使用`yield()`或`ensureActive()`）。

'''Q: 如何处理多个可能超时的并行任务？'''
A: 使用`coroutineScope`组合多个`withTimeout`，或使用`asyn`+`await`模式。

'''Q: 超时异常和普通取消异常有何区别？'''
A: `TimeoutCancellationException`是`CancellationException`的子类，专门用于超时场景，行为基本相同但语义更明确。

[[Category:编程语言]]
[[Category:Kotlin]]
[[Category:Kotlin协程]]