Skip to content

9. 使用协程进行异步编程

上一章介绍了线程:可以“同时”执行多段代码,对它们进行同步,并通过执行器([ExecutorService])把任务分配给线程池。本章讨论一个相关但不同的问题:如何编写一个需要大量 等待 (等待磁盘、网络或数据库)的程序,而不在这些等待期间占用线程。

本章是 Kotlin 与 Java 差异最大的一章。Java 课程介绍了两种解决方案:[CompletableFuture<T>] 类,其行为通过回调方法来扩展,以及 Java 21 的 虚拟线程,它允许你编写阻塞式代码而不阻塞任何系统线程。这两种工具在 Kotlin 中仍然可用(它们是 JDK 的类),我们还会回头讨论它们。但 Kotlin 提供了自己的解决方案:协程:

  • 语言本身只包含一个关键字 [suspend],它标记一个 挂起函数:这种函数可以在执行过程中暂停,释放执行它的线程,然后稍后在同一位置、以相同的局部变量值继续执行;
  • 编译器把每个挂起函数转换为能够暂停和恢复的“状态机”;我们将看到具体是如何做的;
  • 其他一切都由一个库 kotlinx.coroutines 提供:启动协程([launch]、[async])、等待它们([join]、[await])、不阻塞地等待([delay])、选择执行它们的线程(即 调度器)、取消它们、限制它们的持续时间,以及在它们之间传递值([Flow]、[Channel])。

由此得到的代码像顺序代码一样自上而下阅读:它等价于 C# 关键字 [async] / [await](原课程的读者对此很熟悉),此外还有 C# 和 Java 都不提供(Java 仅有初步形式)的一个概念:结构化并发,它把协程组织成一棵树,其中每个节点等待它的子节点、取消它们并接收它们的错误。

协程如今在整个 Kotlin 生态系统中无处不在:在 Android 上、在 Web 框架中(Ktor、Spring,其控制器接受 [suspend] 函数)、在 HTTP 客户端中以及在数据库驱动中。后续各章将使用它们来访问数据库和网络。

kotlinx.coroutines 库不属于标准库:本章的 Gradle 项目位于 [09-async] 文件夹中,在其 [build.gradle.kts] 文件中声明了它:

// 第 9 章:使用协程的异步编程
plugins {
    kotlin("jvm") version "2.4.20"
    application
}

group = "examples"
version = "1.0"

repositories {
    mavenCentral()
}

dependencies {
    // 项目程序所使用的库
    // Kotlin 协程
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
}

kotlin {
    // 代码使用 JDK 25 编译和运行
    jvmToolchain(25)
    compilerOptions {
        // 编译器警告视为错误
        allWarningsAsErrors = true
        // 函数参数名保留在字节码中
        javaParameters = true
    }
}

application {
    // 由 [gradlew run] 运行的程序由 [main] 属性给出:
    // gradlew -q run -Pmain=async01.Async01Kt
    mainClass = providers.gradleProperty("main").orElse("async01.Async01Kt")
}

tasks.named<JavaExec>("run") {
    // 正在运行的程序可以读取键盘
    standardInput = System.`in`
}

// 在 Windows 上,由 Gradle(run、bootRun 等)启动的程序的屏幕输出以 UTF-8 编码,
// 否则带重音符号的字符在 IntelliJ IDEA 控制台或终端中会出现乱码
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}
  • 第 17 行:对 kotlinx.coroutines 库的依赖,版本 1.11.0。主包是 [kotlinx.coroutines];
  • 第 32–34 行:与前几章一样,要执行的程序由 [main] 属性指定:[gradlew -q run -Pmain=async01.Async01Kt];
  • 第 42–45 行:由 Gradle 启动的程序以 UTF-8 输出,以便带重音的字符在 Windows 上正确显示(第 2 章)。

本章的程序照例被组织在以其命名的包中:[src/main/kotlin/async01/Async01.kt]、[src/main/kotlin/async02/Async02.kt]……其中许多程序使用 [System.nanoTime()] 测量耗时:显示的毫秒数每次运行都不同,不同机器上也不同(示例是在一台双处理器机器上运行的)。重要的是 数量级 :是 1 秒还是 10 秒,是 300 毫秒还是 0 毫秒。程序中首次使用协程会加载库的类,这通常会给最初的测量增加几十毫秒。

9.1. 为什么要异步

9.1.1. 会等待的操作

程序执行两类工作:

  • 计算任务,占用处理器:对列表排序、计算税款、分析文本;
  • 输入/输出 (I/O),本质上就是等待某个设备:从磁盘读取文件、向 Web 服务器发送请求并等待其响应、在数据库服务器上执行 SQL 查询。

数量级差异很大。处理器每秒可执行几十亿条指令。(SSD)磁盘的一次读操作大约需要十分之一毫秒;局域网上的一次往返需要不到一毫秒;与位于全国另一端的服务器的一次往返需要几十毫秒;而一个较复杂的 SQL 请求有时可能需要几秒钟。在这些等待期间,处理器本可以执行数百万条指令。

当程序使用阻塞函数通过网络连接读取一行数据时,执行该读取的线程会被 阻塞:它什么也不做,但仍然存在。“经典”的 JVM 线程——现在称为“平台线程”——是操作系统线程:它占用内存(它的栈,大约一兆字节),被系统所识别,而且最重要的是,它不能再用来做任何其他事情。在一次只做一件事的小型控制台程序中,这不是问题。但在两种情况下,问题要严重得多:

  • 在 服务器中:每个由阻塞线程服务的客户端都会占用该线程。如果服务器的线程池有 N 个线程,并且这 N 个线程都在执行阻塞操作,就没有可用的线程来服务新的客户端了。现代服务器能处理数千个同时到来的请求:这之所以可能,是因为它的等待操作不占用系统线程;
  • 在 图形用户界面中:单个线程——UI 线程(Android 应用的主线程、Swing 的“事件分派线程”、“JavaFX 应用程序线程”)——负责处理点击和重绘窗口。如果它被下载操作阻塞,窗口就会冻结;在 Android 上,系统最终甚至会提示用户关闭该应用。

异步 是指发起 I/O 操作,在它运行期间 释放系统线程(硬件和操作系统传输数据并不需要它),然后在操作完成后继续工作,可能是在另一个线程上。Java 的虚拟线程在 JVM 层面实现了这一点:被阻塞的虚拟线程会与其宿主线程分离,而宿主线程在此期间继续执行其他虚拟线程。Kotlin 协程则在编译后的代码层面实现这一点:等待中的协程被 挂起,也就是说,它的状态(执行到哪里以及局部变量)被存放在一个称为 续体(continuation)的堆对象中,而原先执行它的线程则被归还给线程池:

Image

  • 在 [1] 中,系统线程 T1 执行一个阻塞函数;它一直处于阻塞状态,直到 I/O 完成;
  • 在 [2] 中,协程 C1 调用一个发起 I/O 的挂起函数;该协程被 挂起:它的续体存放在堆上,原先执行它的线程 T1 可以立即执行其他协程。I/O 完成后,续体由一个空闲线程 T2(也可能就是 T1)恢复,C1 在调用挂起函数之后立即继续执行,就好像什么都没发生过一样。

程序 [Async01.kt] 测量了 100 个操作的差异,每个操作都等待一秒(等待用来模拟 I/O)。它使用了我们将在本章稍后解释的指令([runBlocking]、[launch]、[delay]):这里我们主要关心的是结果。

// 为什么要异步:100 个操作,每个都等待一秒
// (等待模拟 I/O:磁盘读取、网络请求、SQL 查询……)
package async01

import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import java.lang.management.ManagementFactory
import java.util.concurrent.Executors
import kotlin.concurrent.thread

const val NB_OPERATIONS = 100
var start = 0L

fun main() {
    val nbProcessors = Runtime.getRuntime().availableProcessors()
    println("$NB_OPERATIONS one-second operations, $nbProcessors processors")

    // 1 - 每个操作一个平台线程,每个线程在等待期间被阻塞
    start = System.nanoTime()
    val threads = List(NB_OPERATIONS) { thread { Thread.sleep(1000) } }
    waitUntilHalfway()
    display("1 - one platform thread per operation", jvmThreads())
    threads.forEach { it.join() }
    display("    end")

    // 2 - 操作交给一个 10 个线程的线程池,但它们会阻塞线程池
    start = System.nanoTime()
    Executors.newFixedThreadPool(10).use { pool ->
        repeat(NB_OPERATIONS) { pool.execute { Thread.sleep(1000) } }
        waitUntilHalfway()
        display("2 - pool of 10 threads, blocking waits", jvmThreads())
    } // close() 等待所有操作结束
    display("    end")

    // 3 - 每个操作一个虚拟线程:它在等待期间释放其载体线程
    start = System.nanoTime()
    Executors.newVirtualThreadPerTaskExecutor().use { executor ->
        repeat(NB_OPERATIONS) { executor.execute { Thread.sleep(1000) } }
        waitUntilHalfway()
        display("3 - one virtual thread per operation", jvmThreads())
    }
    display("    end")

    // 4 - 每个操作一个协程:delay 挂起协程而不阻塞线程
    start = System.nanoTime()
    runBlocking {
        repeat(NB_OPERATIONS) { launch { delay(1000) } }
        // 同样会挂起的等待:线程仍可供协程使用
        delay(500 - elapsed())
        display("4 - one coroutine per operation", jvmThreads())
    } // runBlocking 等待它启动的所有协程结束
    display("    end")

    // 5 - 十万个协程,仍然只在单个线程 [main] 上
    start = System.nanoTime()
    runBlocking {
        repeat(100_000) { launch { delay(1000) } }
        delay(500 - elapsed())
        display("5 - 100,000 coroutines", jvmThreads())
    }
    display("    end")
}

// 自 [start] 以来经过的毫秒数
fun elapsed(): Long = (System.nanoTime() - start) / 1_000_000

// 阻塞等待,直到 [start] 之后 500 毫秒
fun waitUntilHalfway() {
    val remaining = 500 - elapsed()
    if (remaining > 0) Thread.sleep(remaining)
}

// JVM 中存活的平台线程数
fun jvmThreads(): Int = ManagementFactory.getThreadMXBean().threadCount

// 显示经过的时间,以及(若提供,>= 0)线程数
fun display(message: String, nbThreads: Int = -1) {
    val threadsInfo = if (nbThreads < 0) "" else ", %3d threads in the JVM".format(nbThreads)
    println("%-44s : %5d ms%s".format(message, elapsed(), threadsInfo))
}

结果:

> gradlew -q run -Pmain=async01.Async01Kt
100 one-second operations, 2 processors
1 - one platform thread per operation        :   530 ms, 106 threads in the JVM
    end                                      :  1035 ms
2 - pool of 10 threads, blocking waits       :   500 ms,  16 threads in the JVM
    end                                      : 10009 ms
3 - one virtual thread per operation         :   501 ms,  10 threads in the JVM
    end                                      :  1014 ms
4 - one coroutine per operation              :   504 ms,  10 threads in the JVM
    end                                      :  1059 ms
5 - 100,000 coroutines                       :   501 ms,  10 threads in the JVM
    end                                      :  1341 ms

说明:

  • 第 19–25 行:最简单的解决方案——每个操作一个平台线程。来自 [thread { … }] 函数的 [kotlin.concurrent] (第 8 章)创建并启动一个线程;[List(NB_OPERATIONS) { … }] 构建包含 100 个线程的列表。每个线程执行 [Thread.sleep(1000)]:它被阻塞一秒。这 100 次等待同时进行,整个过程恰好耗时一秒(结果的第 4 行),但代价是多出 100 个系统线程:JVM 统计到 106 个(第 3 行)。如果有 10,000 个操作,就需要 10,000 个系统线程;
  • 第 27–34 行:这些操作被分配给一个 10 个线程的线程池([Executors.newFixedThreadPool(10)]),这对计算来说是合理的大小。但在这里,这些线程并不在做计算——它们是空闲的。操作以每批 10 个的方式等待空闲线程,整个过程耗时……十秒(第 6 行)。这就是所谓的“线程池饥饿”,是将线程池与阻塞 I/O 混用的服务器中最常见的缺陷。[ExecutorService] 是 [AutoCloseable] (Java 19):函数 [use] 在块结束时调用其方法 [close()] ,它拒绝新任务,并等待已提交的任务完成([use] 的作用与 Java 带资源的 [try] 相同);
  • 第 36–43 行:每个操作一个 虚拟线程 。任务代码与第 1 步相同:一个阻塞的 [Thread.sleep(1000)]。然而,被阻塞的虚拟线程不会阻塞任何系统线程。100 次等待合计持续一秒(第 8 行),而 JVM 只有 10 个系统线程(第 7 行):它自己的服务线程和两个载体线程,每个处理器一个。这就是 Java 课程中的解决方案;
  • 第 45–53 行:每个操作一个 协程 。[runBlocking { … }] 在调用它的线程(这里是 [main] 线程)上把一个代码块作为协程执行,并且直到 这个 协程 及其启动的所有协程都结束才交还控制权。在该块内,[launch { delay(1000) }] 启动一个等待一秒的新协程:[delay] 是一个挂起函数,它 挂起 协程而不阻塞线程。这 100 个协程由单个线程 [main] 执行:当它们在等待时,它不欠它们任何东西,而去执行其他协程。JVM 仍然有 10 个线程(第 9 行):与前一步相比一个也没有增加。整个过程耗时略多于一秒(第 10 行),多出来的时间来自加载库的类,这发生在首次使用时;
  • 第 50 行:为了在中途测量线程数,主协程也使用 [delay] 等待。如果使用 [Thread.sleep],它会阻塞线程 [main],而这是执行这 100 个协程的唯一线程:这些协程要到这次等待结束后才能启动。我们将回头讨论 [delay] 和 [Thread.sleep] 之间的这个关键差异;
  • 第 55–62 行:十万个协程,仍然只由 [main] 线程执行,没有任何额外的线程(第 11 行)。挂起的协程只不过是一小组堆对象,每个只有几十字节大小:可以有几十万个。创建这 100,000 个协程及其超时本身也要花一点时间(在示例机器上是几百毫秒,因此第 12 行显示了这个时间);而 100,000 个平台线程在大多数机器上根本不可能创建出来;
  • 第 75 行:[ManagementFactory.getThreadMXBean().threadCount] 返回 JVM 中存活的平台线程数。在 Kotlin 中,Java 方法 [getThreadCount()] 被视为属性 [threadCount];
  • [thread] 函数及其执行器直接使用 [Thread.sleep] :Kotlin 没有受检异常(第 3 章),因此无需捕获 [InterruptedException] (它可能由 [Thread.sleep] 抛出),就像 Java 程序中的 [waitFor] 方法所做的那样。

让我们记住这个教训:要等待,就不能阻塞任何系统线程。异步并不会让 I/O 更快;它让你能够用很少的线程同时处理许多 I/O 操作,并让应用程序所需的线程保持可用。Kotlin 提供了两种方法:编写普通的阻塞代码,由 虚拟线程执行(第 3 步,与 Java 相同),或者编写由协程执行的挂起函数(第 4 步和第 5 步)。本章重点讲解第二种方法。

9.1.2. 几种先后出现的模型

各平台提供过几种编写等待而不阻塞的代码的方式。最古老的方式仍然存在于现有代码中,而直接使用 Java 库的 Kotlin 也与它们并存:认识它们是有用的。

模型
出现时间
原理
线程和执行器
Java 1.0(1996),Java 5(2004)
每个操作一个线程,或者使用线程池([ExecutorService])。[submit] 返回一个 [Future<T>],它代表即将得到的结果,但获得这个结果的唯一方式是通过 [get()] 阻塞等待。
回调方法
Java 7(NIO.2,2011),JavaScript
通过向操作传递一个对象或回调函数来发起操作(NIO.2 中的 [CompletionHandler] ),操作结束时由线程池中的线程调用它。
可组合的 future
Java 8([CompletableFuture],2014),JavaScript 的 promise
一个代表当前操作的对象,其后续步骤通过方法组合起来([thenApply]、[thenCompose]、[exceptionally]……);响应式库(Project Reactor、RxJava)基于相同的思想。
[async] / [await]
C# 5(2012),随后是 JavaScript、Python、Rust 等
[async] 方法返回一个任务(C# 中的 [Task<T>] );[await] 挂起该方法直到任务完成,而不阻塞线程。编译器把该方法转换为状态机。
Kotlin 协程
Kotlin 1.3(2018)
带有 [suspend] 的函数被编译器转换为状态机,kotlinx.coroutines 库提供结构化并发。调用挂起函数时不带任何关键字:代码呈现为顺序代码的形式。
虚拟线程
Java 21(2023)
由虚拟线程执行的普通阻塞代码:JVM 在等待期间释放系统线程。

回调方法有一个缺点:代码被拆成了碎片。自然读起来是“连接,然后读取,然后显示”的逻辑,变成了一个发起连接的函数、一个发起读取的回调函数,以及另一个显示数据的回调函数;变量必须在这些函数之间共享,异常在不同的位置被捕获,而一个简单的循环(“只要还有数据就读取”)变成了一个递归调用自身的回调函数。可组合的 future 通过把各个步骤链接在一起,使这种碎片化更易读;协程则彻底消除了它:异步代码 采用 同步代码的形式。与虚拟线程的区别在于,在等待点拆分代码的是编译器,而不是 JVM。

程序 [Async02.kt] 使用两种极端的模型实现了同一个 TCP 客户端:先用 NIO.2 的回调方法,再用协程。它还包含一个由线程运行的小型服务器,响应两个客户端(网络编程将在第 12 章详细介绍;目前只需知道客户端连接到服务器,并读取服务器发给它的消息即可)。

// 同一个 TCP 客户端,先用回调方法(NIO.2)编写,再用协程编写
package async02

import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.suspendCancellableCoroutine
import java.io.IOException
import java.net.InetAddress
import java.net.InetSocketAddress
import java.net.ServerSocket
import java.net.SocketAddress
import java.nio.ByteBuffer
import java.nio.channels.AsynchronousSocketChannel
import java.nio.channels.CompletionHandler
import java.util.concurrent.CountDownLatch
import kotlin.concurrent.thread
import kotlin.coroutines.resume
import kotlin.coroutines.resumeWithException

const val PORT = 27500
val local: InetAddress = InetAddress.getLoopbackAddress()

fun main() {
    // 一个最小的服务器,由一个线程执行:它为两个客户端服务后停止
    val listener = ServerSocket(PORT, 10, local)
    val server = thread(name = "server") {
        listener.use {
            for (i in 1..2) {
                listener.accept().use { service ->
                    // 服务器需要一些时间才能应答
                    Thread.sleep(500)
                    service.getOutputStream().write("Hello client no. $i".toByteArray())
                }
            }
        }
    }
    display("start of the program")

    // 1 - "回调方法"风格:AsynchronousSocketChannel 和 CompletionHandler
    val end = CountDownLatch(1)
    val client = AsynchronousSocketChannel.open()
    val buffer = ByteBuffer.allocate(1024)
    // 启动连接,并给出完成时要回调的对象
    client.connect(InetSocketAddress(local, PORT), Unit, object : CompletionHandler<Void?, Unit> {
        // 回调方法 1:连接已建立
        override fun completed(nothing: Void?, attachment: Unit) {
            display("callbacks: connected, read started")
            // 用第二个回调对象启动对应答的读取
            client.read(buffer, Unit, object : CompletionHandler<Int, Unit> {
                // 回调方法 2:数据已到达
                override fun completed(nbBytes: Int, attachment: Unit) {
                    display("callbacks: received [${String(buffer.array(), 0, nbBytes)}]")
                    client.close()
                    // 通知主线程
                    end.countDown()
                }

                override fun failed(e: Throwable, attachment: Unit) {
                    display("callbacks: read failed: $e")
                    end.countDown()
                }
            })
        }

        override fun failed(e: Throwable, attachment: Unit) {
            display("callbacks: connection failed: $e")
            end.countDown()
        }
    })
    display("callbacks: connection started, the program continues")
    // 主线程无事可做:它等待最后一个回调方法的信号
    end.await()

    // 2 - 用协程编写的同一个客户端:代码自上而下阅读
    runBlocking {
        try {
            AsynchronousSocketChannel.open().use { channel ->
                // 两个挂起函数:协程被挂起,没有线程在等待
                channel.connectTo(InetSocketAddress(local, PORT))
                display("coroutine: connected, read started")
                val buffer2 = ByteBuffer.allocate(1024)
                val nbBytes = channel.readInto(buffer2)
                display("coroutine: received [${String(buffer2.array(), 0, nbBytes)}]")
            }
        } catch (e: IOException) {
            display("coroutine: $e")
        }
    }
    server.join()
}

// 带回调的连接,转换为挂起函数
suspend fun AsynchronousSocketChannel.connectTo(address: SocketAddress): Unit =
    suspendCancellableCoroutine { continuation ->
        connect(address, Unit, object : CompletionHandler<Void?, Unit> {
            // 回调方法恢复被挂起的协程……
            override fun completed(nothing: Void?, attachment: Unit) = continuation.resume(Unit)

            // ……或者通过让它抛出异常来恢复它
            override fun failed(e: Throwable, attachment: Unit) = continuation.resumeWithException(e)
        })
    }

// 带回调的读取,转换为返回所读字节数的挂起函数
suspend fun AsynchronousSocketChannel.readInto(buffer: ByteBuffer): Int =
    suspendCancellableCoroutine { continuation ->
        read(buffer, Unit, object : CompletionHandler<Int, Unit> {
            override fun completed(nbBytes: Int, attachment: Unit) = continuation.resume(nbBytes)
            override fun failed(e: Throwable, attachment: Unit) = continuation.resumeWithException(e)
        })
    }

// 以执行它的线程名称为前缀的显示
fun display(message: String) = println("[${Thread.currentThread().name}] $message")

结果:

1
2
3
4
5
6
7
> gradlew -q run -Pmain=async02.Async02Kt
[main] start of the program
[main] callbacks: connection started, the program continues
[InnocuousThread-4] callbacks: connected, read started
[InnocuousThread-2] callbacks: received [Hello client no. 1]
[main] coroutine: connected, read started
[main] coroutine: received [Hello client no. 2]

说明:

  • 第 23–36 行:服务器。它监听本机的 27500 端口([InetAddress.getLoopbackAddress()],即 127.0.0.1),先后接受两个连接,并在半秒后向每个客户端发送欢迎消息。它由一个名为 [server] 的平台线程执行,该线程由函数 [thread] 创建,使用命名参数 [name]。[use] 函数在其块结束时关闭 [ServerSocket] 以及为每个 [Socket] 服务的连接;
  • 第 38–71 行:客户端使用回调方法编写:
    • 第 40 行:[AsynchronousSocketChannel] 是一个其操作为异步的 TCP 通道;
    • 第 43 行:[connect] 发起连接并立即交还控制权(结果的第 3 行)。它的最后两个参数是一个回调方法将会收到的任意对象(这里是 [Unit],因为我们不需要它)和回调对象,该对象实现了 [CompletionHandler<V, A>] 接口,其中 [V] 是操作结果的类型(对于不返回任何东西的连接是 [Void?] ),[A] 是传递的对象的类型。Kotlin 允许使用 对象表达式 ([object : CompletionHandler<Void?, Unit> { … }])就地创建这个对象,它等价于 Java 的匿名类。其方法 [completed] 在操作成功时被调用,其方法 [failed] 在操作失败时被调用;
    • 第 44–48 行:连接建立后,通过 *[read]* 发起读取,并指定嵌套在第一个回调对象内部的第二个回调对象;
    • 第 49–54 行:读取回调对象接收读取的字节数,显示消息,关闭通道,并释放主线程;
    • 第 71 行:主线程已经无事可做。为确保程序不会在交换结束之前终止,它等待最后一个回调方法发出信号:一个初始化为 1 的 *[CountDownLatch] ,其 *[await]* 方法会阻塞调用线程,直到另一个线程调用它的 *[countDown] 方法;
  • 结果显示,回调方法由主线程之外的线程执行(它们是 JVM 中专用于异步通道的线程池中的线程,名为 [InnocuousThread-N])。两个回调对象的嵌套已经使代码难以阅读;如果有三四个连续的操作,我们最终就会陷入所谓的“回调地狱”;
  • 第 73–88 行:用由 [runBlocking] 启动的协程编写的同一个客户端。代码就像同步代码一样自上而下阅读:连接、读取、显示。变量是普通的局部变量;错误由单个 [try / catch] 处理;没有嵌套的回调对象,也没有需要管理的信号。然而,没有任何线程在等待连接或服务器的响应:[connectTo] 和 [readInto] 是挂起函数,它们在操作期间挂起协程;
  • 第 92–99 行:函数 [connectTo] 把回调操作转换为挂起函数。它是 [AsynchronousSocketChannel] 的扩展函数(第 4 章),标记为 [suspend]。kotlinx.coroutines 的函数 [suspendCancellableCoroutine] 会挂起调用它的协程,并向代码块传递该协程的 续体 ——也就是能让它恢复执行的对象。该代码块通过一个回调对象发起操作,回调对象在操作结束时恢复协程:要么返回一个值([resume]),要么使其抛出异常([resumeWithException])。回调方法不做其他任何事情:客户端的全部逻辑都保留在协程中;
  • 第 104–107 行:读取操作,同样被转换为返回读取字节数的挂起函数;
  • 结果的末尾显示,协程在两次挂起之前和之后都在 [main] 线程上打印:由 [InnocuousThread] 执行的回调方法恢复了续体,但这个恢复被转发到 [runBlocking] 线程。在关于调度器的一节中,我们将看到执行协程其余部分的线程是如何选择的。

理解这个机制很重要,因为它适用于所有协程:挂起的协程就是一个待处理的续体,而续体不过是一个回调方法——只不过它是由编译器根据其余代码自行生成的。需要自己编写像 [connectTo] 这样的函数的情况很少见:kotlinx.coroutines 库和其他 Kotlin 库为大多数操作提供了挂起函数。但如果你需要使用只提供回调方法的 API,[suspendCancellableCoroutine] 只需几行代码就能转换它。

9.2. 未来的操作:CompletableFuture 和 Deferred

9.2.1. 从 Kotlin 看 CompletableFuture

[Future<T>] ([java.util.concurrent] 包的接口,Java 5)是一个代表正在进行或已经完成的操作的结果——类型为 [T]——的对象。我们在上一章遇到过它:这就是执行器的 [submit] 方法所返回的东西。你可以查询它(是否已完成?是否成功?),取消它([cancel]),并等待它的结果([get]),但仅此而已:使用结果的唯一方式是阻塞一个线程直到结果可用。

[CompletableFuture<T>] 类(Java 8)实现了 [Future<T>] 并增加了两个关键特性:

  • 你可以 终止它(由你自己来做),给它一个结果([complete])或一个异常([completeExceptionally]);
  • 你可以 为它附加后续处理步骤——一个在结果可用时执行的函数([thenApply]、[thenAccept]、[thenCompose]……),它会产生一个新的 [CompletableFuture]。这使我们能够构建操作链,而无需任何线程等待。

[CompletableFuture] 不是线程。它可以代表由执行器的线程执行的过程(如由 [supplyAsync] 创建的那些),但许多 CompletableFuture 并不由任何线程执行:JDK 的 HTTP 客户端的 [sendAsync] 方法返回的那个,会在服务器的响应到达时完成。它是对结果的一个 承诺(promise)。

Kotlin 程序员每次使用异步 Java 库时都会遇到 [CompletableFuture] :JDK 的 HTTP 客户端、某些数据库驱动、云服务客户端,等等。他们必须知道如何处理它们——尤其是如何把它们与协程连接起来。程序 [Async03.kt] 是 Java 程序的 Kotlin 版本,该 Java 程序演示了创建、查询和等待 [CompletableFuture] 的主要方式:

// 从 Kotlin 看 CompletableFuture:创建、等待、状态、结果、后续处理
package async03

import java.util.concurrent.CompletableFuture
import java.util.concurrent.CompletionException
import java.util.concurrent.ExecutionException
import java.util.concurrent.TimeUnit

fun main() {
    // 1 - supplyAsync 将一个处理交给执行器,并返回一个 CompletableFuture<T>
    val f1: CompletableFuture<Long> = CompletableFuture.supplyAsync {
        // 一个耗时零点几秒的计算
        var sum = 0L
        for (i in 1..200_000_000) {
            sum += i % 7
        }
        sum
    }
    println("f1 started, state: ${f1.state()}")
    // join() 等待处理结束,阻塞当前线程,并返回其结果
    val result = f1.join()
    println("f1 finished, state: ${f1.state()}, result: $result")

    // 2 - 一个在 300 毫秒后由定时器完成的 CompletableFuture,不占用线程
    val f2 = CompletableFuture<Unit>().completeOnTimeout(Unit, 300, TimeUnit.MILLISECONDS)
    println("f2 started, state: ${f2.state()}")
    f2.join()
    println("f2 finished, state: ${f2.state()}")

    // 3 - 已经完成的 CompletableFuture,成功或失败
    val f3 = CompletableFuture.completedFuture(42)
    val f4 = CompletableFuture.failedFuture<Int>(IllegalStateException("breakdown"))
    println("f3: state ${f3.state()}, result ${f3.resultNow()} ; " +
            "f4: state ${f4.state()}, exception ${f4.exceptionNow()}")

    // 4 - 一个失败的处理:join() 抛出包装其异常的 CompletionException
    val f5 = CompletableFuture.supplyAsync { "abc".toInt() }
    try {
        f5.join()
    } catch (e: CompletionException) {
        println("f5: state ${f5.state()}, join() throws ${e.javaClass.simpleName} containing ${e.cause}")
    }

    // 5 - 继承自 Future 接口的 get() 将异常包装在 ExecutionException 中
    try {
        f5.get()
    } catch (e: ExecutionException) {
        println("f5: get() throws ${e.javaClass.simpleName} containing ${e.cause?.javaClass?.simpleName}")
    }

    // 6 - 后续处理:CompletableFuture 完成时要执行的操作
    val f6: CompletableFuture<Int> = f2.thenApply { 2 * 21 }
    val f7: CompletableFuture<Void> = f6.thenAccept { value ->
        println("f7: the continuation received $value")
    }
    f7.join()

    // 7 - isDone、isCompletedExceptionally、isCancelled
    println("f1: isDone=${f1.isDone}, f5: isDone=${f5.isDone}, " +
            "isCompletedExceptionally=${f5.isCompletedExceptionally}, isCancelled=${f5.isCancelled}")
}

结果:

> gradlew -q run -Pmain=async03.Async03Kt
f1 started, state: RUNNING
f1 finished, state: SUCCESS, result: 599999998
f2 started, state: RUNNING
f2 finished, state: SUCCESS
f3: state SUCCESS, result 42 ; f4: state FAILED, exception java.lang.IllegalStateException: breakdown
f5: state FAILED, join() throws CompletionException containing java.lang.NumberFormatException: For input string: "abc"
f5: get() throws ExecutionException containing NumberFormatException
f7: the continuation received 42
f1: isDone=true, f5: isDone=true, isCompletedExceptionally=true, isCancelled=false

说明:

  • 第 10–17 行:[CompletableFuture.supplyAsync(supplier)] 把一个无参函数(Java 的 [Supplier<T>])传给执行器,并立即返回一个代表其执行的 [CompletableFuture<T>] 。得益于 SAM 转换(第 7 章),可以向它传递一个 Kotlin lambda,放在括号之外;它的最后一个表达式 [sum] 就是结果。没有显式执行器时,由 JVM 的共享池 [ForkJoinPool.commonPool()] 执行该函数;
  • 第 19 行:[state()] 方法(Java 19)返回操作的状态:[RUNNING] (进行中)、[SUCCESS] (成功完成)、[FAILED] (因异常而完成),或 [CANCELLED] (已取消)。它们是 [Future.State] 枚举的常量;
  • 第 21 行:[join()] 等待操作结束并返回其结果。这是 阻塞式 等待:当前线程被挂起(本例中是主线程,这对小型控制台程序没有影响);
  • 第 24–28 行:一个由其构造函数创建为“进行中”、并在 300 毫秒后由定时器终止的 [CompletableFuture] ([completeOnTimeout],Java 9):这是 [Thread.sleep(300)] 的异步等价物。在 Java 中,没有结果的操作类型为 [CompletableFuture<Void>];在 Kotlin 中,可以写成 [CompletableFuture<Unit>],其唯一的值是 [Unit];
  • 第 30–34 行:[completedFuture(42)] 返回一个预先完成的 [CompletableFuture] ,其结果为 42,而 [failedFuture(exception)] 返回 一个 [CompletableFuture] ,它已经失败;后者的结果类型无法从其参数推断,因此在尖括号之间指定它:[failedFuture<Int>(...)]。[resultNow()] 和 [exceptionNow()] (Java 19)立即返回已完成操作的结果或异常,无需等待;
  • 第 36–41 行:函数抛出异常的操作以状态 [FAILED] 结束。异常存放在 [CompletableFuture] 中,而 [join()] 会触发一个 [CompletionException] ,它的 原因([cause],即被当作属性的 [getCause()] 方法)就是原始异常——在本例中是由 [NumberFormatException] 抛出的 ["abc".toInt()];
  • 第 44–48 行:[get()],即继承自 [Future] 接口的方法,同样以阻塞状态等待,但会把异常包装在 [ExecutionException] 中。在 Java 中,这是一个 受检异常,[main] 方法本应捕获或声明它,以及 [InterruptedException] (它可能由 [get()] 抛出)。Kotlin 没有受检异常:你只拦截自己感兴趣的异常,其他一概不管;
  • 第 51–56 行:一个 后续操作(continuation)。[f2.thenApply { 2 * 21 }] 返回一个新的 [CompletableFuture] ,一旦 [f2] 完成,它就会以该函数的结果完成:这会产生一个 [CompletableFuture<Int>]。[thenAccept] 附加一个只消费结果而不产生结果的函数,并返回一个 [CompletableFuture<Void>] (这是一个 Java 方法:它的返回类型是 [Void],Kotlin 不会把它转换为 [Unit]);
  • 第 58–60 行:布尔方法 [isDone()] (已完成,无论以何种方式)、[isCompletedExceptionally()] (因异常而完成或已被取消)和 [isCancelled()] (已取消):Kotlin 把它们表示为属性:[isDone]、[isCompletedExceptionally]和 [isCancelled]。

Java 课程接着用了好几页来讲解 [CompletableFuture] 的组合:[thenCompose]、[thenCombine]、[allOf]、[anyOf]、[exceptionally]、[handle]、[orTimeout]……在 Kotlin 中,你几乎不需要这些方法:你只需要 在协程中等待 该 [CompletableFuture] ,使用挂起函数 [await()],然后把其余部分写成普通代码即可。下表将 [CompletableFuture] 的方法与它们对应的协程等价物进行了比较(所有这些函数本章都会讲到):

[CompletableFuture]
协程
[supplyAsync(f)]、[runAsync(r)]
[async { … }] (返回 [Deferred<T>])、[launch { … }] (返回 [Job])
[completedFuture(v)]、[complete(v)]
单个值;[CompletableDeferred] 用于手动完成一个操作
[thenApply(f)]、[thenAccept(c)]、[thenRun(r)]
[val v = operation()] 后面接着其余的 代码
[thenCompose(f)]
连续两次调用挂起函数
[thenCombine(other, f)]、[allOf(...)]
[async],随后是 [await] 和 [awaitAll]
[anyOf(...)]
[select]
[exceptionally(f)]、[handle(f)]、[whenComplete(c)]
[try / catch / finally]
[orTimeout(...)]、[completeOnTimeout(...)]
[withTimeout]、[withTimeoutOrNull]
[cancel]
[cancel],它真正终止操作(协作式回滚)
[join()]、[get()]
[await()]、[join()]:挂起协程而不是阻塞线程的等待

9.2.2. Deferred

在协程中,与 [CompletableFuture<T>] 对应的是 kotlinx.coroutines 的 [Deferred<T>] (“延迟值”)接口:它是协程的未来结果。它通过用 [async] 函数启动协程,并用挂起函数 [await()] 等待其结果来获得。[Deferred<T>] 是 [Job] 的特例,后者是表示当前正在运行或已经结束的、没有结果的协程的接口;*[Job]* 通过用函数 *[launch]* 启动协程来获得,并通过挂起函数 *[join()]* 等待它结束。

程序 [Async04.kt] 演示了 [Deferred]、[Job],以及从前者到 [CompletableFuture] 的转换,反之亦然:

// Deferred:协程的未来结果;从 Deferred 转到 CompletableFuture
package async04

import kotlinx.coroutines.Deferred
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.Job
import kotlinx.coroutines.async
import kotlinx.coroutines.delay
import kotlinx.coroutines.future.asCompletableFuture
import kotlinx.coroutines.future.await
import kotlinx.coroutines.future.future
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.supervisorScope
import java.util.concurrent.CompletableFuture

fun main() = runBlocking {
    // 1 - async 启动一个协程并立即返回一个 Deferred<T>
    val d1: Deferred<Long> = async(Dispatchers.Default) {
        // 同样是耗时零点几秒的计算
        var sum = 0L
        for (i in 1..200_000_000) {
            sum += i % 7
        }
        sum
    }
    println("d1 started: ${state(d1)}")
    // await() 挂起当前协程直到得到结果,而不阻塞其线程
    val result = d1.await()
    println("d1 finished: ${state(d1)}, result: $result")

    // 2 - 一个"等待"300 毫秒的协程:delay 挂起它,不占用线程
    val d2: Deferred<String> = async {
        delay(300)
        "end of the delay"
    }
    println("d2 started: ${state(d2)}")
    println("d2 finished: ${d2.await()}")

    // 3 - launch 启动一个没有结果的协程并返回一个 Job;join() 等待其结束
    val job: Job = launch {
        delay(100)
        println("job: work finished")
    }
    job.join()
    println("job: ${state(job)}")

    // 4 - 失败的处理:await() 重新抛出原始异常,没有包装
    // (supervisorScope 阻止失败传播到程序:参见异常一节)
    supervisorScope {
        val d4 = async { "abc".toInt() }
        try {
            d4.await()
        } catch (e: NumberFormatException) {
            println("d4: ${state(d4)}, await() throws ${e.javaClass.simpleName} : ${e.message}")
        }
    }

    // 5 - 协程可以等待 CompletableFuture:await() 挂起而不阻塞
    val f5: CompletableFuture<Int> = CompletableFuture.supplyAsync { 6 * 7 }
    println("f5: CompletableFuture awaited by a coroutine: ${f5.await()}")

    // 6 - Deferred 也可以表示为 CompletableFuture,例如提供给 Java 代码
    val f6: CompletableFuture<Long> = d1.asCompletableFuture()
    println("f6: Deferred seen as a CompletableFuture: state ${f6.state()}, result ${f6.resultNow()}")
    // future { } 启动一个协程并直接返回一个 CompletableFuture
    val f7: CompletableFuture<String> = future {
        delay(100)
        "result of a coroutine"
    }
    println("f7: ${f7.thenApply { it.uppercase() }.await()}")
}

// Job 的状态(Deferred 是携带结果的 Job)
fun state(job: Job) = "isActive=${job.isActive}, isCompleted=${job.isCompleted}, isCancelled=${job.isCancelled}"

结果:

> gradlew -q run -Pmain=async04.Async04Kt
d1 started: isActive=true, isCompleted=false, isCancelled=false
d1 finished: isActive=false, isCompleted=true, isCancelled=false, result: 599999998
d2 started: isActive=true, isCompleted=false, isCancelled=false
d2 finished: end of the delay
job: work finished
job: isActive=false, isCompleted=true, isCancelled=false
d4: isActive=false, isCompleted=true, isCancelled=true, await() throws NumberFormatException : For input string: "abc"
f5: CompletableFuture awaited by a coroutine: 42
f6: Deferred seen as a CompletableFuture: state SUCCESS, result 599999998
f7: RESULT OF A COROUTINE

说明:

  • 第 17 行:函数 [main] 是一个表达式 [runBlocking { … }]。该代码块由 [main] 线程作为协程执行,并且 [runBlocking] 直到这个协程结束才交还控制权。正是在这个代码块中,可以调用挂起函数([await]、[delay]……)并启动其他协程([async]、[launch]):代码块隐式地接收一个 [CoroutineScope] (协程 作用域),而 [async] 和 [launch] 是它的扩展函数。我们将在关于结构化并发的一节中回到这一点;
  • 第 18–25 行:[async] 启动一个执行该代码块的新协程,并立即返回一个代表其结果(代码块中的最后一个表达式)的 [Deferred<Long>] 。参数 [Dispatchers.Default] 使协程由专用于计算的线程池执行:如果没有它,协程将由 [runBlocking] 的线程执行,并且要到主协程第一次挂起后才会启动;
  • 第 27 行:协程的状态由 [Job] 的三个属性决定:[isActive] (进行中)、[isCompleted] (已完成,无论以何种方式)和 [isCancelled] (已取消 或失败,稍后我们会看到)。函数 [state] (第 74–75 行)显示它们;
  • 第 29 行:[await()] 等待协程结束并返回其结果。与 [join()] 在 [CompletableFuture] 上的调用不同,这种等待 不会阻塞 线程:它是一个挂起函数,挂起的是主协程;与此同时,[main] 线程可以用于其他协程;
  • 第 32–38 行:一个用 *[delay]* 等待 300 毫秒然后返回一个字符串的协程:等待期间不占用任何线程;
  • 第 40–46 行:[launch] 启动一个不返回结果的协程,并返回一个 [Job]。[join()] 挂起主协程,直到这个协程结束。[launch] / [Job] 对于协程,就像 [runAsync] / [CompletableFuture<Void>] 对于 [CompletableFuture] 的世界一样;
  • 第 48–55 行:一个失败的协程。[await()] 重新抛出原始异常,即一个 [NumberFormatException],不会将其 包装在另一个异常中:它就像是直接调用一样被拦截。显示的状态表明,失败的 [Job] 具有 [isCancelled=true]:对 kotlinx.coroutines 而言,失败是取消的一种形式。这里需要 [supervisorScope] 块,原因将在 关于异常的一节中说明:如果没有它,协程的失败会传播到启动它的协程,并终止整个程序;
  • 第 59–61 行:扩展函数 [CompletableFuture<T>.await()](来自包 [kotlinx.coroutines.future])通过挂起协程来等待一个 [CompletableFuture] ,而不阻塞任何线程。它充当 异步 Java 库与协程之间的 桥梁:调用 [client.sendAsync(request, handler).await()] 会等待 Web 服务器的响应,我们将在本章后面看到。如果 [CompletableFuture] 失败,[await()] 会抛出原始异常,并去掉其 [CompletionException] 包装;
  • 第 63–65 行:反过来,[asCompletableFuture()] 把一个 [Deferred] 呈现为 [CompletableFuture],例如,用于把它传给不支持协程的 Java 代码;
  • 第 66–71 行:函数 [future { … }] 启动一个协程并直接返回一个 [CompletableFuture]:这就是在 Kotlin 中使用协程为 Java 代码编写异步方法的方式。在第 71 行,这个 *[CompletableFuture] 通过 *[thenApply] 进行组合,然后使用 *[await()]* 等待结果。

9.3. 挂起函数

9.3.1. suspend、launch、async 和 await

在 Kotlin 中,异步操作被写成一个 挂起函数:这是一个用 *[suspend] 修饰符声明的普通函数,它直接返回其结果(而不是返回表示该结果的 *[CompletableFuture] 或 *[Deferred]*):

  • [suspend fun makeCoffee()] 用于不返回结果的操作;
  • [suspend fun countSugars(number: Int): Int] 用于返回整数的操作。

挂起函数可以调用其他挂起函数,例如 [delay]、[await] 和 [join],而正是在这些调用期间它可以被挂起。它只能被另一个挂起函数调用,或者在协程中([runBlocking]、[launch] 或 [async] 的主体)调用;编译器会强制执行这一点。这是唯一的限制:在函数内部,你编写的是普通代码,可以有循环、[if]、[try / catch] 和局部变量。

调用挂起函数时不带任何关键字:C# 写成 [await MakeCoffeeAsync()],Kotlin 则写成 [makeCoffee()]。而且这个调用是 顺序的:只有在被调用的函数结束之后,才会执行下一行。要并行执行多个操作,必须通过用 [launch] 或 *[async]* 启动新的协程来明确表示。这是 Kotlin 设计者有意的选择:顺序代码是常态,因此它应该是最容易编写的;并发则应该是显式的。

Java 教程制作咖啡并清点方糖,先是使用通过 [CompletableFuture] 与 [thenRun] 和 [thenCompose] 链接的方式,然后使用由虚拟线程执行的阻塞代码。程序 [Async05.kt] 使用挂起函数制作同样的咖啡:

// 使用挂起函数的咖啡:普通函数,自上而下阅读
package async05

import kotlinx.coroutines.Deferred
import kotlinx.coroutines.Job
import kotlinx.coroutines.async
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

var start = System.nanoTime()

fun main() = runBlocking {
    // 1 - 两个操作在两个协程中启动,然后等待
    display("launching makeCoffee")
    val preparation: Job = launch { makeCoffee() }
    display("makeCoffee is launched: the program continues")
    display("launching countSugars")
    val counting: Deferred<Int> = async { countSugars(3) }
    display("countSugars is launched")
    // 我们现在等待这两个操作:主协程被挂起
    preparation.join()
    val nbSugars = counting.await()
    display("coffee ready, with $nbSugars sugar(s)")

    // 2 - 直接调用同样的函数:它们一个接一个地运行
    start = System.nanoTime()
    display("direct calls")
    makeCoffee()
    val number = countSugars(3)
    display("coffee ready, with $number sugar(s)")
}

// 一个不返回结果的挂起函数
suspend fun makeCoffee() {
    display("  coffee: the machine is heating up")
    // delay 挂起协程,而不阻塞执行它的线程
    delay(1000)
    display("  coffee: the machine is pouring the coffee")
    delay(500)
    display("  coffee: finished")
}

// 一个返回整数的挂起函数
suspend fun countSugars(number: Int): Int {
    for (i in 1..number) {
        delay(200)
        display("  sugar no. $i")
    }
    return number
}

// 显示,附带自 [start] 以来经过的时间和线程名称
fun display(message: String) {
    val elapsed = (System.nanoTime() - start) / 1_000_000
    println("%5d ms [%s] %s".format(elapsed, Thread.currentThread().name, message))
}

结果:

> gradlew -q run -Pmain=async05.Async05Kt
   47 ms [main] launching makeCoffee
   62 ms [main] makeCoffee is launched: the program continues
   62 ms [main] launching countSugars
   65 ms [main] countSugars is launched
   67 ms [main]   coffee: the machine is heating up
  281 ms [main]   sugar no. 1
  482 ms [main]   sugar no. 2
  683 ms [main]   sugar no. 3
 1068 ms [main]   coffee: the machine is pouring the coffee
 1569 ms [main]   coffee: finished
 1571 ms [main] coffee ready, with 3 sugar(s)
    0 ms [main] direct calls
    0 ms [main]   coffee: the machine is heating up
 1000 ms [main]   coffee: the machine is pouring the coffee
 1501 ms [main]   coffee: finished
 1702 ms [main]   sugar no. 1
 1902 ms [main]   sugar no. 2
 2103 ms [main]   sugar no. 3
 2104 ms [main] coffee ready, with 3 sugar(s)

说明:

  • 第 34–41 行:写成普通函数的一个空操作:一条打印语句,等待一秒,一条打印语句,等待半秒,一条打印语句。[delay] 是 kotlinx.coroutines 的挂起函数,它通过挂起协程来等待指定的延迟(以毫秒为单位,或以持续时间 [kotlin.time.Duration] 的形式:[delay(1.seconds)])。这等价于 Java 程序中的 [delay] 方法,后者返回一个由定时器终止的 [CompletableFuture] ;但在这里,函数的其余部分不需要写在后续操作中:它直接跟在调用之后;
  • 第 44–50 行:一个返回整数的操作。这里的循环是真正的循环,在每次迭代时等待:这是它与使用 [CompletableFuture] 的 Java 版本的唯一区别,在 Java 版本中,循环构造的是一个 [thenCompose] 链,而不是执行各次迭代(并且 lambda 需要一个变量 [number]——即 [i] 的副本);
  • 第 16 行:[launch] 启动一个执行 [makeCoffee()] 的新协程,并立即返回一个 [Job];
  • 第 19 行:[async] 启动一个执行 [countSugars(3)] 的新协程,并立即返回一个 [Deferred<Int>];
  • 第 22–23 行:主协程等待这两个操作;在这些等待期间它被挂起;
  • 输出的第 2 到 12 行显示了执行过程:咖啡在 1.5 秒后准备好——即两个操作中较长者的持续时间——而方糖在机器预热期间被清点完毕。但它们也显示出与 Java 程序的一个区别:机器要等到主程序的最后一条打印语句(第 5 行)之后才开始预热(第 6 行)。程序中的所有协程都由单个线程 [main] 执行,该线程属于 [runBlocking]:[launch] 和 [async] 不会立即执行它们创建的协程;它们把协程放入线程的队列,线程空闲时才会执行它——也就是主协程自行挂起时(第 22 行)。这称为 协作式多任务:协程一直持有线程,直到它自行挂起;
  • 第 26–31 行:直接调用同样的函数,不启动协程。每次调用都在下一次调用开始之前完成:先煮咖啡(1.5 秒),然后清点方糖(0.6 秒),总共 2.1 秒(结果的第 13–20 行)。当一个操作依赖于前一个操作的结果时,这是正确的做法;
  • 第 54 行:每条输出都显示经过的时间和执行它的线程:始终是 [main]。

我们看到了与使用虚拟线程的 Java 版本相同的优点:这些函数是普通函数,自上而下阅读;是按顺序执行(直接调用)还是并发执行([launch]、[async]),在调用时就已决定。然而,与虚拟线程不同的是,整个程序只用一个线程就足够了,而且在等待期间释放线程的不是 JVM,而是挂起函数本身。

9.3.2. delay 与 Thread.sleep

协程只有在自行挂起时才释放它的线程——也就是在调用一个正在等待的挂起函数时。如果它调用 阻塞函数([Thread.sleep]、使用 [java.io] 类的文件或套接字读取、JDBC 请求……),它就会阻塞执行它的线程,所有依赖该线程的协程都会被搁置。程序 [Async06.kt] 说明了这一区别:

// delay 挂起协程,Thread.sleep 阻塞线程
package async06

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

var start = 0L

fun main() {
    // 1 - 两个用 delay 等待的协程:它们共享唯一的线程 [main]
    start = System.nanoTime()
    runBlocking {
        launch { workWithDelay("A") }
        launch { workWithDelay("B") }
    } // 两个协程都结束后 runBlocking 返回
    display("1 - end, with delay")

    // 2 - 同样的协程使用 Thread.sleep:线程 [main] 在每次等待时被阻塞
    start = System.nanoTime()
    runBlocking {
        launch { workWithSleep("A") }
        launch { workWithSleep("B") }
    }
    display("2 - end, with Thread.sleep")

    // 3 - 在 IO 调度器上使用 Thread.sleep:每个协程阻塞 IO 池中的一个线程
    start = System.nanoTime()
    runBlocking {
        launch(Dispatchers.IO) { workWithSleep("A") }
        launch(Dispatchers.IO) { workWithSleep("B") }
    }
    display("3 - end, with Thread.sleep on Dispatchers.IO")
}

// 三个步骤,之间以会挂起协程的 100 毫秒等待分隔
suspend fun workWithDelay(name: String) {
    for (i in 1..3) {
        display("  $name$i")
        delay(100)
    }
}

// 三个步骤,之间以会阻塞线程的 100 毫秒等待分隔
fun workWithSleep(name: String) {
    for (i in 1..3) {
        display("  $name$i")
        Thread.sleep(100)
    }
}

// 显示,附带自 [start] 以来经过的时间和线程名称
fun display(message: String) {
    val elapsed = (System.nanoTime() - start) / 1_000_000
    println("%5d ms [%s] %s".format(elapsed, Thread.currentThread().name, message))
}

结果:

> gradlew -q run -Pmain=async06.Async06Kt
   67 ms [main]   A1
   97 ms [main]   B1
  193 ms [main]   A2
  198 ms [main]   B2
  294 ms [main]   A3
  298 ms [main]   B3
  399 ms [main] 1 - end, with delay
    1 ms [main]   A1
  101 ms [main]   A2
  202 ms [main]   A3
  303 ms [main]   B1
  403 ms [main]   B2
  504 ms [main]   B3
  604 ms [main] 2 - end, with Thread.sleep
   10 ms [DefaultDispatcher-worker-1]   A1
   10 ms [DefaultDispatcher-worker-2]   B1
  112 ms [DefaultDispatcher-worker-1]   A2
  112 ms [DefaultDispatcher-worker-2]   B2
  213 ms [DefaultDispatcher-worker-1]   A3
  213 ms [DefaultDispatcher-worker-2]   B3
  314 ms [main] 3 - end, with Thread.sleep on Dispatchers.IO

说明:

  • 第 12–18 行:在 *[runBlocking] 中启动的两个协程,每个协程执行由 *[delay(100)]* 分隔的三个步骤。它们共享 *[main] 线程:一个等待时,另一个工作;步骤交替进行(A1、B1、A2、B2……),两个协程的等待时间相互重叠:整个过程大约需要 300 毫秒,外加首次使用时加载库的类所需的时间(结果的第 8 行)。函数 [runBlocking] 直到它启动的两个协程都结束才返回控制权:无需编写代码来等待它们;
  • 第 20–26 行:同样的协程,用 [Thread.sleep] 等待。每次等待都会阻塞唯一的线程 [main]:协程 B 要等 A 结束后才能启动,整个过程需要 600 毫秒(第 9–15 行)。这两个协程已不再是真正的协程:它们一个接一个地执行;
  • 第 28–34 行:包含阻塞代码的协程被交给另一组线程,即调度器 [Dispatchers.IO],方法是将它作为参数传给 [launch]。随后每个协程阻塞各自的线程;它们同时运行,整个过程再次需要 300 毫秒(第 16–22 行)。当需要从协程中调用阻塞代码(例如不提供挂起函数的库,如 JDBC)时,这是标准做法;但这样每个进行中的操作都要付出一个系统线程的代价。该调度器的线程名为 [DefaultDispatcher-worker-N]:我们将在关于调度器的一节中看到原因;
  • 第 37–41 行:[workWithDelay] 调用 [delay]:这是一个挂起函数;
  • 第 45–49 行:[workWithSleep] 不调用任何挂起函数:它是一个普通函数。编译器允许从协程中调用它,但 IntelliJ 和 IDEA 会标记出在挂起函数或协程中对已知阻塞函数([Thread.sleep]、[java.io] 中的 I/O 操作)的调用(“Possibly blocking call in non-blocking context”)。

由此得出协程编程的第一条规则:挂起函数绝不能阻塞它的线程。如果它需要调用阻塞代码,就把它委托给为此设计的调度器([Dispatchers.IO],或基于虚拟线程的调度器),并配合 [withContext],我们很快就会讲到。

9.3.3. 编译器做了什么:续体和状态机

挂起函数怎么能在循环中间暂停、释放它的线程,然后稍后在同一位置、以相同的局部变量值恢复执行,甚至可能是在另一个线程上?Java 课程解释过,对于虚拟线程,这项工作由 JVM 完成:它把虚拟线程的调用栈复制到堆中,稍后再在那里恢复。JVM 对 Kotlin 协程一无所知:这项工作是由 编译器 通过转换每个挂起函数来完成的。它分两步进行。

第一步:续体变成参数。每个 [suspend] 函数在字节码中都会接收一个类型为 [Continuation<T>] (标准库中 [kotlin.coroutines] 包的一个接口)的额外参数,其中 [T] 是函数返回值的类型。续体表示“计算的下一步”:即如何处理函数的结果。它有一个方法 [resumeWith(result)],用于以结果或异常恢复执行(扩展函数 [resume(value)] 和 [resumeWithException(e)] 会调用它),以及一个属性 [context],即协程上下文(我们稍后会回到这一点)。函数的返回类型变成 [Any?] (在 JVM 上是 [Object] ):函数要么返回它的结果(如果它无需等待就能完成),要么返回一个特殊值 [COROUTINE_SUSPENDED],意思是“我已被挂起;我的续体将在稍后恢复”。这就是“续体传递风格”(CPS)。

第二步:函数体变成状态机。函数体内对挂起函数的每次调用都是一个潜在的 挂起点。编译器为这些点编号(这个编号称为 [label]),并把下一个恢复点的编号以及必须在挂起后保留的局部变量存放在该函数特有的续体对象中。函数体变成一个根据这个编号分支的 [when] :开始时进入一次(标签 0),之后每次恢复时进入一次,程序直接跳到它中断的地方。

程序 [Async07.kt] 演示了这一切。它只使用 Kotlin 标准库(不使用 kotlinx.coroutines),这样我们就能看到基本机制:它自己编写了 [delay] 的等价物,并自己启动一个协程。

// 编译器所做的事:挂起函数接收一个续体
// (该程序只使用 Kotlin 标准库,不使用 kotlinx.coroutines)
package async07

import java.util.concurrent.CountDownLatch
import java.util.concurrent.Executors
import java.util.concurrent.TimeUnit
import kotlin.coroutines.Continuation
import kotlin.coroutines.EmptyCoroutineContext
import kotlin.coroutines.resume
import kotlin.coroutines.startCoroutine
import kotlin.coroutines.suspendCoroutine

// 定时器:延迟后执行操作的线程
val timer = Executors.newSingleThreadScheduledExecutor { action -> Thread(action, "timer") }

// 相当于 delay,用 suspendCoroutine 编写
suspend fun pause(ms: Long): Unit = suspendCoroutine { continuation ->
    display("    pause($ms): the coroutine is suspended")
    // 定时器将在延迟后恢复协程
    timer.schedule({ continuation.resume(Unit) }, ms, TimeUnit.MILLISECONDS)
}

// 一个有两个挂起点和局部变量的挂起函数
suspend fun addUp(a: Int, b: Int): Int {
    display("  addUp($a, $b): start")
    val x = a * 10
    pause(300)
    display("  addUp: resumed after the 1st pause, x = $x")
    val y = b * 10
    pause(200)
    display("  addUp: resumed after the 2nd pause, x + y = ${x + y}")
    return x + y
}

fun main() {
    val end = CountDownLatch(1)
    // 最终续体:对协程的结果要做什么
    val next = Continuation<Int>(EmptyCoroutineContext) { result ->
        display("final continuation: result = ${result.getOrThrow()}")
        end.countDown()
    }
    // 一个挂起 lambda,以最终续体作为协程启动
    val coroutine: suspend () -> Int = { addUp(4, 5) }
    display("starting the coroutine")
    coroutine.startCoroutine(next)
    display("startCoroutine has returned")
    // 主线程等待最终续体的信号
    end.await()
    timer.shutdown()
}

// 以执行它的线程名称为前缀的显示
fun display(message: String) = println("[${Thread.currentThread().name}] $message")

结果:

1
2
3
4
5
6
7
8
9
> gradlew -q run -Pmain=async07.Async07Kt
[main] starting the coroutine
[main]   addUp(4, 5): start
[main]     pause(300): the coroutine is suspended
[main] startCoroutine has returned
[timer]   addUp: resumed after the 1st pause, x = 40
[timer]     pause(200): the coroutine is suspended
[timer]   addUp: resumed after the 2nd pause, x + y = 90
[timer] final continuation: result = 90

说明:

  • 第 15 行:一个定时器,即一个名为 [timer] 的单线程执行器,能够在延迟后执行一个动作([ScheduledExecutorService],第 8 章);
  • 第 17–21 行:挂起函数 [pause],即我们自己的 [delay]。它使用标准库的 [suspendCoroutine] 函数(其中 [suspendCancellableCoroutine] 是 kotlinx.coroutines 的可取消版本,我们在 [Async02.kt] 中遇到过):[suspendCoroutine] 把当前协程的续体传给代码块,然后挂起它。该代码块指示定时器在指定的延迟后,用值 [Unit] 恢复续体;
  • 第 24–33 行:一个带有两个挂起点(对 [pause] 的两次调用)和必须在挂起后保留的局部变量([a]、[b]、[x]、[y])的挂起函数;
  • 第 39–46 行:手动启动一个协程。函数 [Continuation(context) { … }] 由一个接收结果的代码块创建续体,结果类型为 [Result<Int>](一个结果或一个异常;[getOrThrow()] 返回前者或抛出后者):这就是最终续体,它显示结果并通知主线程。空上下文 [EmptyCoroutineContext] 表示不请求任何特定的东西——尤其是没有调度器。扩展函数 [startCoroutine] 以最终续体将一个挂起 lambda([suspend () -> Int])作为协程启动;
  • 结果显示了执行过程:[startCoroutine] 执行函数 [addUp] ,在线程 [main] 上运行直到第一个挂起点(第 3 行和第 4 行),然后 交还控制权 (第 5 行):函数返回了 [COROUTINE_SUSPENDED]。300 毫秒后,线程 [timer] 恢复执行:函数 [addUp] 紧接在第一次调用 [pause] 之后恢复,[x] 的值完好无损(第 6 行),并且是在与它开始时不同的线程上。接着是第二次暂停、函数结束,以及接收结果 90 的最终续体(第 9 行)。kotlinx.coroutines 的协程所做的无非就是这些;调度器只是指定由哪个线程执行每个续体。

让我们看看编译器生成了什么。JDK 的 [javap] 工具可以显示已编译类的成员。Gradle 把编译后的类放在项目的 [build/classes/kotlin/main] 文件夹中:

> javap -p -cp build/classes/kotlin/main async07.Async07Kt
Compiled from "Async07.kt"
public final class async07.Async07Kt {
  private static final java.util.concurrent.ScheduledExecutorService timer;
  public static final java.util.concurrent.ScheduledExecutorService getTimer();
  public static final java.lang.Object pause(long, kotlin.coroutines.Continuation<? super kotlin.Unit>);
  public static final java.lang.Object addUp(int, int, kotlin.coroutines.Continuation<? super java.lang.Integer>);
  public static final void main();
  public static final void display(java.lang.String);
  public static void main(java.lang.String[]);
  private static final java.lang.Thread timer$lambda$0(java.lang.Runnable);
  static {};
}
  • 第 6 行和第 7 行:函数 [pause] 和 [addUp] 接收了一个类型为 [Continuation] 的最后一个参数,它们的返回类型变成了 [Object]。[addUp] 的续体参数与其结果具有相同的类型:[Continuation<? super Integer>]。从 Java 的角度看,[addUp] 是一个普通方法,可以通过向它传递一个续体来调用(事实上,Java 代码正是这样调用挂起函数的,尽管有些困难);
  • 第 8 行:不带参数的 [main] 函数,位于编译器为 JVM 添加的 [main(String[])] 方法旁边(第 10 行),正如我们在第 3 章中看到的那样。

编译器还生成了一个名为 [Async07Kt$addUp$1] 的类:这是函数 [addUp] 的续体对象:

> javap -p -cp build/classes/kotlin/main "async07.Async07Kt$addUp$1"
Compiled from "Async07.kt"
final class async07.Async07Kt$addUp$1 extends kotlin.coroutines.jvm.internal.ContinuationImpl {
  int I$0;
  int I$1;
  int I$2;
  int I$3;
  java.lang.Object result;
  int label;
  async07.Async07Kt$addUp$1(kotlin.coroutines.Continuation<? super async07.Async07Kt$addUp$1>);
  public final java.lang.Object invokeSuspend(java.lang.Object);
}
  • 第 3 行:该类派生自 [ContinuationImpl],这是标准库中实现 [Continuation] 的一个内部类;
  • 第 4 行到第 7 行:四个整数字段,[I$0] 到 [I$3],函数在每次挂起之前把它的局部变量 [a]、[b]、[x]、和 [y] 存放在这些字段中;
  • 第 8 行:[result] 接收恢复执行时所带的结果(或异常);
  • 第 9 行:[label],下一个恢复点的编号;
  • 第 11 行:[invokeSuspend],恢复时调用的方法,它只是调用函数 [addUp],并把这个续体对象传给它。

最后,[-c] 选项让 [javap] 显示方法的字节码。下面是 [addUp] 字节码的两个节选(命令 [javap -c -p -cp build/classes/kotlin/main async07.Async07Kt] 会显示完整的字节码):

        56: invokestatic  #71                 // Method kotlin/coroutines/intrinsics/IntrinsicsKt.getCOROUTINE_SUSPENDED:()Ljava/lang/Object;
        59: astore        7
        61: aload         6
        63: getfield      #97                 // Field async07/Async07Kt$addUp$1.label:I
        66: tableswitch   { // 0 to 2
                       0: 92
                       1: 153
                       2: 242
                 default: 295
            }
  • 在函数入口处(节选之前),字节码会取出函数的续体对象(如果是恢复执行),或者在第一次调用时创建一个;
  • [getCOROUTINE_SUSPENDED] 读取特殊值 [COROUTINE_SUSPENDED],并存放在局部变量中;
  • [tableswitch] 是 JVM 的指令,对应于对整数的 [when] 操作 :根据 [label] 字段的值(0、1 或 2),执行分别跳转到函数的开头(地址 92)、紧接在第一次调用 [pause] 之后(地址 153)或紧接在第二次调用之后(地址 242)。其他任何值都会导致错误(地址 295)。
       112: ldc2_w        #115                // long 300l
       115: aload         6
       117: aload         6
       119: iload_0
       120: putfield      #119                // Field async07/Async07Kt$addUp$1.I$0:I
       123: aload         6
       125: iload_1
       126: putfield      #122                // Field async07/Async07Kt$addUp$1.I$1:I
       129: aload         6
       131: iload_3
       132: putfield      #125                // Field async07/Async07Kt$addUp$1.I$2:I
       135: aload         6
       137: iconst_1
       138: putfield      #97                 // Field async07/Async07Kt$addUp$1.label:I
       141: invokestatic  #127                // Method pause:(JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
       144: dup
       145: aload         7
       147: if_acmpne     178
       150: aload         7
       152: areturn
       153: aload         6
       155: getfield      #125                // Field async07/Async07Kt$addUp$1.I$2:I
       158: istore_3
       159: aload         6
       161: getfield      #122                // Field async07/Async07Kt$addUp$1.I$1:I
       164: istore_1
       165: aload         6
       167: getfield      #119                // Field async07/Async07Kt$addUp$1.I$0:I
       170: istore_0
       171: aload         5
       173: invokestatic  #109                // Method kotlin/ResultKt.throwOnFailure:(Ljava/lang/Object;)V
       176: aload         5
  • 地址 112 到 138:在第一次调用 [pause] 之前,函数把它的局部变量 [a]、[b] 和 [x] (JVM 的变量 0、1 和 3)保存到续体对象的字段 [I$0]、[I$1] 和 [I$2] 中,并把 [label] 设为 1;
  • 地址 141:调用 [pause(300)],续体对象作为最后一个参数;
  • 地址 144 到 152:如果 [pause] 返回了 [COROUTINE_SUSPENDED],函数也会向其调用者返回 [COROUTINE_SUSPENDED] ([areturn]):挂起就是这样沿着调用栈“向上传递”到 [startCoroutine],由它把控制权交还给线程 [main]。否则,执行直接在地址 178 处继续;
  • 地址 153 到 170:恢复点 1。函数把续体对象的字段复制到它的局部变量中,然后继续执行,就好像什么都没发生过一样。

因此,JVM 的调用栈从未被保留:每次挂起时,所有当前被挂起的函数都返回 [COROUTINE_SUSPENDED],它们的栈帧随之消失;需要保留的内容存放在续体对象中,这些续体对象链接在一起(每个都知道其调用者的续体)。每次恢复时,会按相反的顺序遍历这条链。这与 C# 编译器为 [async] 方法创建的“状态机”是同一个概念。

为了完全理解这个机制,程序 [Async08.kt] 用 Kotlin 手工编写了编译器为 [pause] 和 [addUp] 生成的内容的简化版本:

// 编译器为挂起函数生成的状态机,手工编写
// (对 Async07 程序的 [addUp] 函数所生成代码的简化版)
package async08

import java.util.concurrent.CountDownLatch
import java.util.concurrent.Executors
import java.util.concurrent.TimeUnit
import kotlin.coroutines.Continuation
import kotlin.coroutines.CoroutineContext
import kotlin.coroutines.EmptyCoroutineContext
import kotlin.coroutines.intrinsics.COROUTINE_SUSPENDED

// 定时器:延迟后执行操作的线程
val timer = Executors.newSingleThreadScheduledExecutor { action -> Thread(action, "timer") }

// "编译后"的 pause 函数:它接收要恢复的续体并返回 COROUTINE_SUSPENDED
fun pause(ms: Long, continuation: Continuation<Unit>): Any {
    display("    pause($ms): the coroutine is suspended")
    timer.schedule({ continuation.resumeWith(Result.success(Unit)) }, ms, TimeUnit.MILLISECONDS)
    return COROUTINE_SUSPENDED
}

// [addUp] 的续体:状态机的状态以及需要保留的局部变量
class AddUpContinuation(val caller: Continuation<Int>, val a: Int, val b: Int) : Continuation<Unit> {
    // 下一个恢复点的编号
    var label = 0
    // 必须在挂起之后保留的局部变量
    var x = 0
    var y = 0
    override val context: CoroutineContext get() = caller.context

    // 在暂停结束时调用:状态机从停下的地方重新启动
    override fun resumeWith(result: Result<Unit>) {
        val outcome = addUp(this)
        // 如果函数已运行到末尾,则恢复调用者的续体
        if (outcome !== COROUTINE_SUSPENDED) {
            caller.resumeWith(Result.success(outcome as Int))
        }
    }
}

// [addUp] 函数被转换为状态机:从开头进入,然后在每次恢复时进入
fun addUp(state: AddUpContinuation): Any {
    while (true) {
        when (state.label) {
            0 -> {
                display("  addUp(${state.a}, ${state.b}): start (label 0)")
                state.x = state.a * 10
                // 下一个恢复点是 1 号
                state.label = 1
                if (pause(300, state) === COROUTINE_SUSPENDED) return COROUTINE_SUSPENDED
            }
            1 -> {
                display("  addUp: resumed after the 1st pause (label 1), x = ${state.x}")
                state.y = state.b * 10
                state.label = 2
                if (pause(200, state) === COROUTINE_SUSPENDED) return COROUTINE_SUSPENDED
            }
            2 -> {
                display("  addUp: resumed after the 2nd pause (label 2), x + y = ${state.x + state.y}")
                return state.x + state.y
            }
            else -> error("unknown resumption point: ${state.label}")
        }
    }
}

fun main() {
    val end = CountDownLatch(1)
    // 最终续体:对结果要做什么
    val next = Continuation<Int>(EmptyCoroutineContext) { result ->
        display("final continuation: result = ${result.getOrThrow()}")
        end.countDown()
    }
    display("first call of addUp")
    val returned = addUp(AddUpContinuation(next, 4, 5))
    display("addUp returned ${if (returned === COROUTINE_SUSPENDED) "COROUTINE_SUSPENDED" else returned}")
    end.await()
    timer.shutdown()
}

// 以执行它的线程名称为前缀的显示
fun display(message: String) = println("[${Thread.currentThread().name}] $message")

结果:

1
2
3
4
5
6
7
8
9
> gradlew -q run -Pmain=async08.Async08Kt
[main] first call of addUp
[main]   addUp(4, 5): start (label 0)
[main]     pause(300): the coroutine is suspended
[main] addUp returned COROUTINE_SUSPENDED
[timer]   addUp: resumed after the 1st pause (label 1), x = 40
[timer]     pause(200): the coroutine is suspended
[timer]   addUp: resumed after the 2nd pause (label 2), x + y = 90
[timer] final continuation: result = 90

说明:

  • 第 16–20 行:编译器所看到的函数 [pause] :一个普通函数(没有 [suspend]),它接收要恢复的续体,安排其恢复,并返回 [COROUTINE_SUSPENDED],这是标准库 [kotlin.coroutines.intrinsics] 包中的一个常量;
  • 第 23–29 行:[addUp] 的续体对象。它知道调用者的续体([caller])、参数 [a] 和 [b]、下一个恢复点的编号([label])以及局部变量 [x] 和 [y]。而编译器则把参数也存放在字段中,并重用通用字段([I$0]……);
  • 第 30 行:续体必须提供其协程的上下文;我们使用调用者的上下文;
  • 第 33–37 行:恢复。定时器在暂停结束时调用 [resumeWith] ;该方法带着知道从哪里恢复的续体对象回调 [addUp] 。如果函数一直运行到结束(它不返回 [COROUTINE_SUSPENDED]),它的结果就传给调用者的续体:结果就是这样从一个挂起函数“传回”调用它的那个函数的;
  • 第 42–63 行:状态机。由 [when] 对 [state.label] 的分支把执行导向函数的正确部分。每个部分都以保存下一个恢复点并调用 [pause] 结束:如果 [pause] 返回 [COROUTINE_SUSPENDED],函数也返回它;否则(挂起函数可能无需挂起就运行到结束,例如结果已经已知时),[while (true)] 循环会直接跳到下一个部分。局部变量从续体对象中读取,也写入续体对象([state.x], [state.y]);
  • 第 76–77 行:第一次调用。结果显示 [addUp] 返回了 [COROUTINE_SUSPENDED] (结果的第 5 行);其余过程在 [timer] 线程上进行,与 [Async07.kt] 中完全一样。

这个程序只是出于说明的目的而收录:你绝不会自己编写这样的代码。不过,有两个关键的收获:

  • 挂起的协程只占用它的续体对象——每个活动函数几十字节——而不是像平台线程那样一兆字节的栈:这就是 [Async01.kt] 中 100,000 个协程得以实现的原因;
  • 挂起只可能发生在调用挂起函数时。普通函数无法被挂起:如果它阻塞(如 [Thread.sleep]),就会阻塞线程。这是与虚拟线程的根本区别,在虚拟线程中,JVM 可以挂起任何用 Java 编写的阻塞代码。相比之下,协程不依赖于 JVM:同样的机制适用于单线程浏览器中的 Kotlin/JS 以及 Kotlin/Native。

9.3.4. 调度器:由哪个线程执行其余代码?

协程不是线程:执行它需要线程。决定由哪个线程执行协程(在启动时以及每次恢复时)的组件是它的 调度器,它是协程 上下文的一个元素。协程的上下文([CoroutineContext])是一小组按类型索引的元素,它们用 [+] 运算符组合在一起:调度器([CoroutineDispatcher])、协程的 [Job]、它的名称([CoroutineName])以及它的异常处理器([CoroutineExceptionHandler],我们稍后讨论)……上下文作为参数传给 [launch]、[async]、[runBlocking]、或 [withContext];新协程继承其作用域上下文的元素,被覆盖的除外。

kotlinx.coroutines 提供了四个调度器,它们是 [Dispatchers] 对象的属性:

调度器
使用的线程
[Dispatchers.Default]
用于 计算的线程池,线程数与处理器数相同(至少两个)。当没有指定调度器且作用域也没有调度器时,使用的就是这个调度器。
[Dispatchers.IO]
用于 阻塞操作(文件、JDBC、阻塞套接字)的线程池,最多可包含 64 个线程(如果机器有超过 64 个处理器,则可以更多;系统属性 [kotlinx.coroutines.io.parallelism] 可以改变这一上限)。它与 [Dispatchers.Default] 共享线程,这避免了在两者之间切换时发生线程切换。
[Dispatchers.Main]
GUI 线程。只有在项目中添加了相应的模块时它才存在:[kotlinx-coroutines-android]、[kotlinx-coroutines-swing]、[kotlinx-coroutines-javafx]。
[Dispatchers.Unconfined]
没有特定的线程:协程在调用者的线程上启动,挂起之后在恢复它的线程上继续执行。它主要用于测试和非常特殊的情况。

除了这些调度器之外,还有 [runBlocking] 中的调度器,它在调用它的线程上执行其协程,以及使用扩展函数 [asCoroutineDispatcher()] 由 Java 执行器创建的调度器。程序 [Async09.kt] 显示执行每段代码的线程:

// 哪个线程执行协程,以及挂起之后它其余的代码?调度器
package async09

import kotlinx.coroutines.CoroutineName
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.asCoroutineDispatcher
import kotlinx.coroutines.delay
import kotlinx.coroutines.joinAll
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withContext
import java.util.concurrent.Executors

fun main() {
    // 调试模式会在线程名称中加上它所执行协程的名称和编号
    System.setProperty("kotlinx.coroutines.debug", "on")
    display("start of the program, ${Runtime.getRuntime().availableProcessors()} processors")
    runBlocking(CoroutineName("main")) {
        // 1 - runBlocking 的协程由调用 runBlocking 的线程执行
        display("1 - runBlocking, before delay")
        delay(100)
        display("1 - runBlocking, after delay")

        // 2 - Dispatchers.Default:针对计算调整大小的线程池
        launch(Dispatchers.Default + CoroutineName("computation")) {
            display("2 - Dispatchers.Default")
        }.join()

        // 3 - Dispatchers.IO:更大的线程池,用于阻塞操作
        launch(Dispatchers.IO + CoroutineName("io")) {
            display("3 - Dispatchers.IO")
        }.join()

        // 4 - withContext 在同一个协程中,在一个块的持续期间更改调度器
        val result = withContext(Dispatchers.Default) {
            display("4 - in withContext(Dispatchers.Default)")
            42
        }
        display("4 - back on the runBlocking thread, result = $result")

        // 5 - Dispatchers.Unconfined:其余部分由恢复协程的线程执行
        launch(Dispatchers.Unconfined + CoroutineName("free")) {
            display("5 - Dispatchers.Unconfined, before delay")
            delay(100)
            display("5 - Dispatchers.Unconfined, after delay")
        }.join()

        // 6 - 转换为调度器的 Java 执行器:这里是每个任务一个虚拟线程
        Executors.newVirtualThreadPerTaskExecutor().asCoroutineDispatcher().use { virtuals ->
            launch(virtuals + CoroutineName("virtual")) {
                display("6 - virtual threads, before delay")
                delay(100)
                display("6 - virtual threads, after delay")
            }.join()
        }

        // 7 - 在 Dispatchers.Default 上,协程在每次挂起后可能更换线程
        val a = launch(Dispatchers.Default + CoroutineName("A")) { work("A") }
        val b = launch(Dispatchers.Default + CoroutineName("B")) { work("B") }
        joinAll(a, b)
        display("end of the program")
    }
}

suspend fun work(name: String) {
    for (i in 1..3) {
        display("7 -   $name$i")
        delay(100)
    }
}

// 显示,以执行它的线程为前缀(对于虚拟线程,是其完整描述)
fun display(message: String) {
    val thread = Thread.currentThread()
    println("[${if (thread.isVirtual) thread.toString() else thread.name}] $message")
}

结果:

> gradlew -q run -Pmain=async09.Async09Kt
[main] start of the program, 2 processors
[main @main#1] 1 - runBlocking, before delay
[main @main#1] 1 - runBlocking, after delay
[DefaultDispatcher-worker-1 @computation#2] 2 - Dispatchers.Default
[DefaultDispatcher-worker-1 @io#3] 3 - Dispatchers.IO
[DefaultDispatcher-worker-1 @main#1] 4 - in withContext(Dispatchers.Default)
[main @main#1] 4 - back on the runBlocking thread, result = 42
[main @free#4] 5 - Dispatchers.Unconfined, before delay
[kotlinx.coroutines.DefaultExecutor @free#4] 5 - Dispatchers.Unconfined, after delay
[VirtualThread[#25, @virtual#5]/runnable@ForkJoinPool-1-worker-1] 6 - virtual threads, before delay
[VirtualThread[#28, @virtual#5]/runnable@ForkJoinPool-1-worker-1] 6 - virtual threads, after delay
[DefaultDispatcher-worker-1 @A#6] 7 -   A1
[DefaultDispatcher-worker-2 @B#7] 7 -   B1
[DefaultDispatcher-worker-1 @A#6] 7 -   A2
[DefaultDispatcher-worker-1 @B#7] 7 -   B2
[DefaultDispatcher-worker-1 @A#6] 7 -   A3
[DefaultDispatcher-worker-1 @B#7] 7 -   B3
[main @main#1] end of the program

说明:

  • 第 16 行:系统属性 [kotlinx.coroutines.debug] 为 kotlinx.coroutines 启用 调试模式 (它必须在首次使用该库之前设置;也可以传给 JVM:[-Dkotlinx.coroutines.debug])。在这种模式下,执行协程的线程名称在执行期间会附加上协程的名称(由其上下文中的 [CoroutineName] 元素提供,默认为 [coroutine] )及其编号:[main @main#1];
  • 第 18–22 行:[runBlocking] 的协程,名为 [main],在等待之前和之后都由线程 [main] 执行:[runBlocking] 把调用它的线程变成执行其协程的事件循环(结果的第 3 行和第 4 行);
  • 第 24–26 行:在 [Dispatchers.Default] 上启动的协程,其上下文——用 [+] 组合而成——由一个调度器和一个名称构成;它由一个名为 [DefaultDispatcher-worker-N] 的线程执行(第 5 行);
  • 第 29–31 行:在 [Dispatchers.IO] 上启动的协程;它由同名的线程执行(第 6 行),因为这两个调度器共享它们的线程;
  • 第 34–39 行:[withContext(context) { … }] 是一个挂起函数,它在不同的上下文(这里是另一个调度器)中执行一个代码块,仍在同一个协程内 (编号仍为 [#1]),然后回到原来的调度器并返回代码块的结果(第 7 行和第 8 行)。这是在 [Dispatchers.Default] 上执行计算,或在 [Dispatchers.IO] 上执行阻塞代码而不改变代码形式的首选方法:[val text = withContext(Dispatchers.IO) { file.readText() }];
  • 第 41–45 行:使用 [Dispatchers.Unconfined] 时,协程在 [main] 线程——调用者的线程(第 9 行)——上启动,并在 [delay] 之后在恢复它的线程上继续:[kotlinx.coroutines.DefaultExecutor],即 kotlinx.coroutines 的定时器线程,它负责管理超时(第 10 行)。这是 [CompletableFuture] 的非异步后续操作([thenApply]、[thenRun])的行为,它们由完成该操作的线程执行;
  • 第 48–54 行:[Executors.newVirtualThreadPerTaskExecutor().asCoroutineDispatcher()] 创建一个调度器,它把协程的每个执行片段分配给一个 Java 执行器——这里是虚拟线程执行器。生成的调度器在不再需要时必须关闭,因此使用 [use]。第 11 行和第 12 行显示,协程的开头和其余部分是由两个不同的虚拟线程(编号 25 和 28)执行的:每次恢复都是分配给执行器的一个新任务,因此执行器会创建一个新的虚拟线程。这样的调度器适用于从协程中执行阻塞代码,而不受 [Dispatchers.IO] 的 64 个线程上限的限制:虚拟线程在等待期间会被 JVM 释放;
  • 第 57–60 行:两个协程在 [Dispatchers.Default] 上连续三次显示一条消息然后等待。[joinAll] 等待多个协程结束。第 13 行到第 18 行显示,协程并不会一直附着在单个线程上:协程 B 在 [worker-2] 上启动,在 [worker-1] 上继续。因此,在协程中,绝不能假定挂起之后的代码与挂起之前的代码由同一个线程执行。一个实际的后果是:[ThreadLocal] 变量(第 8 章)在协程中是不可靠的;应当把信息存放在协程的上下文中,它会随协程去往任何地方;
  • 第 72–75 行:对于虚拟线程——它的名称默认为空——我们显示其完整描述,其中包括它的编号、它的名称(这里是协程的名称,由调试模式添加)以及它的宿主线程。

因此,调度器的选择很重要:

  • [Dispatchers.Default] 用于计算。执行冗长计算的协程会占用它的一个线程,就像线程池中的任务一样:协程不会加快计算;它们促进的是等待操作的 并发性 (同时处理许多等待操作),而不是计算的 并行性 (在多个处理器上同时执行多个计算,如上一章所述);
  • [Dispatchers.IO],或虚拟线程调度器,用于阻塞代码,并配合 [withContext];
  • [Dispatchers.Main] 用于图形应用程序:在 UI 线程上启动的协程可以更新图形组件,等待某个操作(使用 [withContext] 在别处执行)而不冻结 UI,然后用结果更新 UI,无需任何特殊处理:在 [withContext] 结束时,协程会自动回到 UI 线程。C# 就是这样工作的,其中 [async] 方法的后续部分会回到界面线程,而 Java 如果不显式地向每个后续操作传递执行器,就无法做到这一点。

最后,可以使用 [limitedParallelism(n)] 限制调度器分配给一组协程的线程数:[val base = Dispatchers.IO.limitedParallelism(10)] 返回一个调度器,它同一时刻最多执行 10 个协程,这些协程从 [Dispatchers.IO] 的线程中获取线程。使用 [limitedParallelism(1)],我们得到一个同一时刻只执行一个协程的调度器,这使得无需加锁就能操作共享状态。该特性自 kotlinx.coroutines 1.9 版本起已经稳定,将在本章后面关于有限并行的一节中使用。

9.3.5. 主程序

使用协程的程序必须从 [main] 函数的普通代码中启动第一个协程,并等待它结束:否则,[main] 函数会立即结束,程序也随之终止(调度器的线程是守护线程,不会阻止 JVM 停止)。有两种方法可以做到这一点:

  • [fun main() = runBlocking { … }],这是我们自本章开头以来一直在使用的写法:[runBlocking] 会阻塞 [main] 线程,直到该协程及其启动的所有协程结束。这是唯一一个阻塞等待属于正常做法的地方;绝不能在协程或挂起函数中调用 [runBlocking] ,因为它会阻塞其线程。当代码块中的最后一个表达式的类型不是 [Unit] 时,我们写成 [runBlocking<Unit> { … }];否则,函数 [main] 会有不同的返回类型,JVM 就不再把它识别为主程序;
  • [suspend fun main()]:函数 [main] 本身可以是挂起函数;编译器负责把它作为协程启动。这等价于 C# 中的 [static async Task Main()] 方法。

程序 [Async10.kt] 使用挂起函数 [main] 执行倒计时:

// 一个挂起的 main 函数:倒计时,以及程序的退出码
package async10

import kotlinx.coroutines.delay
import kotlin.system.exitProcess

suspend fun main(args: Array<String>) {
    // 秒数作为参数传入
    val nbSeconds = args.singleOrNull()?.toIntOrNull()
    if (nbSeconds == null || nbSeconds < 0) {
        println("syntax: gradlew -q run -Pmain=async10.Async10Kt --args=\"nbSeconds\"")
        // 程序的退出码:0 表示成功,其他值表示错误
        exitProcess(1)
    }
    println("countdown started on thread [${Thread.currentThread().name}]")
    countdown(nbSeconds)
    println("finished, on thread [${Thread.currentThread().name}]")
}

// 一个普通循环:每个 delay 挂起函数,而不阻塞线程
suspend fun countdown(nbSeconds: Int) {
    for (i in nbSeconds downTo 1) {
        println("$i s left")
        delay(1000)
    }
}

结果,先带参数,再不带参数:

1
2
3
4
5
6
> gradlew -q run -Pmain=async10.Async10Kt --args="3"
countdown started on thread [main]
3 s left
2 s left
1 s left
finished, on thread [kotlinx.coroutines.DefaultExecutor]
> gradlew -q run -Pmain=async10.Async10Kt
syntax: gradlew -q run -Pmain=async10.Async10Kt --args="nbSeconds"

说明:

  • 第 7 行:一个 [main] 挂起函数,它接收通过 Gradle 使用 [--args] 选项传入的命令行参数;
  • 第 9 行:[singleOrNull()] 返回唯一的参数,如果参数不是恰好一个,则返回 [null] ,而 [toIntOrNull()] 把它转换为整数,如果它不是整数,则返回 [null] ;
  • 第 10–13 行:如果参数缺失或不正确,程序以 [exitProcess(1)] 终止(它是 [kotlin.system] 的一个函数,它调用 [System.exit])。传入的整数是程序的退出码(0 表示成功,其他任何值表示错误),脚本可以检查它:Windows 上用 [echo %ERRORLEVEL%] ,Linux 上用 [echo $?] 。由 Gradle 启动时,以非 0 退出码退出的程序会导致任务 [run] 失败,Gradle 随后会在程序的输出之后显示它自己的错误消息(此处不再复制)。[exitProcess] 的类型是 [Nothing] (第 3 章):编译器知道这个函数永远不会返回,因此认为在 [if] 之后,[nbSeconds] 不是 [null];它可以用作 [Int] (智能转换);
  • 第 20–24 行:倒计时。Java 程序本应使用递归来实现它,每一步都通过 [thenCompose] 链接到下一步;这里则是一个普通循环,每次迭代都有一个 [delay] ;
  • 结果揭示了 [suspend fun main] 的一个特点:它的协程没有调度器。它在 [main] 线程上启动,然后在等待之后,在恢复它的线程——kotlinx.coroutines 的定时器线程([kotlinx.coroutines.DefaultExecutor])——上继续,就像 [Dispatchers.Unconfined] 一样。这里并没有什么后果,但这是更倾向于使用 [fun main() = runBlocking { … }](其行为定义得更明确),或在函数体中用 [withContext] 指定调度器的一个理由。

9.4. 结构化并发

Java 课程在其这一章的结尾概述了 结构化并发 ([StructuredTaskScope],在 Java 25 中仍处于预览阶段)。在 Kotlin 中,这不只是一个附加功能:它是整个 kotlinx.coroutines 库所基于的原则,在继续之前你需要理解它。

这个想法很简单:协程只能在作用域内启动 ([CoroutineScope]),并且作用域要等到它所启动的协程全部结束才会结束。函数 [launch] 和 [async] 是 [CoroutineScope] 的扩展函数:它们不能在任意位置调用,只能在作用域内调用,例如 [runBlocking]、[launch] 或 [async] 的代码块,其接收者([this])就是一个作用域。每个作用域都有一个 [Job];在作用域内启动的每个协程都有自己的 [Job],它成为 子节点 ,隶属于作用域的 [Job]。因此,程序中的协程构成一棵 树,其父子关系有三个后果:

Image

  • 父协程等待它的子协程:*[Job] 要等到它自己的代码以及它的所有子协程都结束后才会结束。这就是为什么 *[runBlocking] 无需编写任何代码,就会等待在其代码块内启动的协程;
  • 取消向下传播:取消一个 [Job] 会取消它的所有子协程,以及子协程的子协程;
  • 失败向上传播:如果一个子协程失败(它的代码抛出异常),它的父协程就会被取消,进而取消父协程的所有其他子协程,异常被传给父协程,再传给父协程自己的父协程,一直传到根协程,或者传到处理它的某段代码。

因此,没有哪个协程会被“遗忘”:它存在于某个作用域内,而该作用域没有它就无法结束;如果它失败,总会有人知道;如果它所属的操作被放弃,它就会被终止。这与结构化编程中代码块的规则(代码块要等到它所包含的指令都执行完才结束)是同一种纪律,只不过应用于并发,因此得名。

程序 [Async11.kt] 演示了这三条规则:

// 结构化并发:Job、父子关系、coroutineScope
package async11

import kotlinx.coroutines.async
import kotlinx.coroutines.cancelAndJoin
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.job
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

var start = System.nanoTime()

fun main() = runBlocking<Unit> {
    // 1 - 协程启动的协程是它的子协程:父协程等待它们结束
    val parent = launch {
        launch {
            delay(300)
            display("  child 1 finished")
        }
        launch {
            delay(600)
            display("  child 2 finished")
        }
        val nbChildren = coroutineContext.job.children.count()
        display("  the parent launched $nbChildren children, its code is finished")
    }
    delay(100)
    display("1 - parent: isActive=${parent.isActive}, isCompleted=${parent.isCompleted}, " +
            "children=${parent.children.count()}")
    parent.join()
    display("1 - parent: isActive=${parent.isActive}, isCompleted=${parent.isCompleted}")

    // 2 - coroutineScope:函数启动协程,并且只在它们结束后才返回
    start = System.nanoTime()
    val tray = prepareBreakfast()
    display("2 - breakfast served: $tray")

    // 3 - 取消父协程会取消它所有的子协程
    start = System.nanoTime()
    val parent3 = launch {
        for (number in 1..2) {
            launch {
                try {
                    delay(10_000)
                } finally {
                    display("  child $number: cancelled")
                }
            }
        }
    }
    delay(200)
    parent3.cancelAndJoin()
    display("3 - parent cancelled: isCancelled=${parent3.isCancelled}")

    // 4 - 子协程的失败会取消它的兄弟协程,并向上传播到父协程
    start = System.nanoTime()
    try {
        coroutineScope {
            launch {
                try {
                    delay(10_000)
                } finally {
                    display("  the sibling is cancelled")
                }
            }
            launch {
                delay(200)
                throw IllegalStateException("the toaster burned")
            }
        }
    } catch (e: IllegalStateException) {
        display("4 - coroutineScope threw: ${e.message}")
    }
}

// 三个同时进行的准备工作;函数只有在它们全部完成后才返回
suspend fun prepareBreakfast(): String = coroutineScope {
    val coffee = async { prepare("coffee", 1000) }
    val toast = async { prepare("toast", 600) }
    // 一个没有结果的协程:coroutineScope 也会等待它
    launch { prepare("table set", 300) }
    "${coffee.await()} and ${toast.await()}"
}

// 一个持续 [ms] 毫秒的准备工作
suspend fun prepare(what: String, ms: Long): String {
    display("  $what: start")
    delay(ms)
    display("  $what: ready")
    return what
}

// 显示,附带自 [start] 以来经过的时间
fun display(message: String) = println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

结果:

> gradlew -q run -Pmain=async11.Async11Kt
   48 ms :   the parent launched 2 children, its code is finished
  142 ms : 1 - parent: isActive=true, isCompleted=false, children=2
  361 ms :   child 1 finished
  661 ms :   child 2 finished
  664 ms : 1 - parent: isActive=false, isCompleted=true
    4 ms :   coffee: start
    4 ms :   toast: start
    4 ms :   table set: start
  304 ms :   table set: ready
  604 ms :   toast: ready
 1004 ms :   coffee: ready
 1011 ms : 2 - breakfast served: coffee and toast
  204 ms :   child 1: cancelled
  204 ms :   child 2: cancelled
  205 ms : 3 - parent cancelled: isCancelled=true
  201 ms :   the sibling is cancelled
  202 ms : 4 - coroutineScope threw: the toaster burned

说明:

  • 第 14 行:代码块中的最后一个表达式是一个 [try] 表达式,其类型不是 [Unit];因此,如前一段所述,需要指定 [runBlocking] 结果的类型;
  • 第 15–26 行:一个 [parent] 协程启动两个子协程,它们分别运行 300 毫秒和 600 毫秒,然后显示它的子协程数量:在 [launch] 的代码块内,[coroutineContext] 是协程的上下文,[coroutineContext.job] 是它的 [Job],而后者的属性 [children] 是它的子协程序列。父协程的代码立即结束(结果的第 2 行);
  • 第 28–30 行:100 毫秒后,父协程的 [Job] 仍处于活动状态,它的两个子协程也是如此(第 3 行):代码已经结束的 [Job] 正在等待它的子协程;
  • 第 31–32 行:[join()] 直到 600 毫秒后第二个子协程结束时才交还控制权(第 4–6 行);
  • 第 77–83 行:挂起函数 [prepareBreakfast] 同时处理三项准备工作。要启动协程,挂起函数需要一个作用域:[coroutineScope { … }] 创建一个新的作用域,其 [Job] 是调用它的协程的子节点,它执行代码块,等待在代码块内启动的所有协程结束,然后返回代码块的值。因此,从外部看,函数 [prepareBreakfast] 就像一个普通的顺序函数:当它交还控制权时,它启动的一切都已完成,包括第 82 行的协程,尽管没有人显式地等待它结束;
  • 第 34–37 行:函数调用;早餐在一秒后上桌,即最长的准备工作所需的时间(第 7–13 行);
  • 第 39–54 行:一个父协程启动两个等待十秒的子协程。200 毫秒后,[cancelAndJoin()] 中止父协程并等待中止完成:两个子协程随之一起被中止(第 14–16 行)。每个子协程的 [finally] 块都会被执行,就像通过异常退出代码块时一样:我们将在关于取消的一节中看到,情况正是如此;
  • 第 56–73 行:在由 [coroutineScope] 创建的作用域内,一个子协程等待十秒,它的兄弟协程在 200 毫秒后失败。这个失败会取消该作用域,进而取消第一个子协程(第 17 行),而 [coroutineScope] 会抛出失败的子协程的异常(第 18 行),该异常被调用外围的标准 [try / catch] 拦截。

因此有两个函数用于创建作用域,它们有两种不同的用途:

  • [runBlocking] 通过阻塞线程,从普通代码中创建程序的根作用域;
  • [coroutineScope] 在挂起函数内创建作用域,不阻塞任何线程。这是编写并发执行多个操作的挂起函数的标准方式:从外部看不到并发。

由此得出一条风格规则:挂起函数在交还控制权时必须已经完成它的所有工作。如果一个函数启动的协程要比它活得更久,它就不应该是挂起函数,而应该是 [CoroutineScope] 的扩展函数(就像 [launch] 本身一样):[fun CoroutineScope.monitor(): Job]。因此它的签名表明它在调用者的作用域内启动协程。在本章后面,我们将看到该库还提供子协程彼此独立的作用域([supervisorScope]),以及如何创建特定于应用程序组件的作用域。本章末尾将比较 Kotlin 的结构化并发与 Java 的结构化并发。

9.5. 顺序执行和并发执行

9.5.1. async 和 awaitAll

正如咖啡的例子所示,对挂起函数的调用是顺序的,要同时执行多个操作,就必须显式地在协程中启动它们。操作 被启动 ([val d = async { operation() }])的时刻和它 被等待 ([d.await()])的时刻因此可以分开,这样就可以在两者之间启动其他操作。程序 [Async12.kt] 使用耗时一秒的操作比较了这两种方法:

// 一秒钟操作的顺序执行和并发执行
package async12

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.async
import kotlinx.coroutines.asCoroutineDispatcher
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import java.util.concurrent.Executors
import kotlin.time.measureTimedValue

fun main() = runBlocking {
    // 1 - 顺序执行:每个操作结束后下一个才开始
    val (sequence, duration1) = measureTimedValue {
        val a = readTemperature("Angers")
        val b = readTemperature("Brest")
        val c = readTemperature("Colmar")
        listOf(a, b, c)
    }
    println("1 - in sequence: $sequence in ${duration1.inWholeMilliseconds} ms")

    // 2 - 并发执行:三个操作先启动,然后等待
    val (concurrent, duration2) = measureTimedValue {
        val a = async { readTemperature("Angers") }
        val b = async { readTemperature("Brest") }
        val c = async { readTemperature("Colmar") }
        listOf(a.await(), b.await(), c.await())
    }
    println("2 - concurrently: $concurrent in ${duration2.inWholeMilliseconds} ms")

    // 3 - 一个操作列表:map { async { … } } 然后 awaitAll()
    val cities = listOf("Angers", "Brest", "Colmar", "Dijon", "Évry", "Foix")
    val (temperatures, duration3) = measureTimedValue {
        cities.map { city -> async { readTemperature(city) } }.awaitAll()
    }
    println("3 - ${cities.size} cities: $temperatures in ${duration3.inWholeMilliseconds} ms")

    // 4 - 把阻塞函数交给 IO 调度器
    val (temperatures4, duration4) = measureTimedValue {
        cities.map { city -> async(Dispatchers.IO) { readTemperatureBlocking(city) } }.awaitAll()
    }
    println("4 - ${cities.size} cities (Dispatchers.IO): $temperatures4 in ${duration4.inWholeMilliseconds} ms")

    // 5 - IO 调度器上的 100 个阻塞操作,限制为 64 个线程
    val (hundredIO, duration5) = measureTimedValue {
        (1..100).map { async(Dispatchers.IO) { readTemperatureBlocking("city$it") } }.awaitAll()
    }
    println("5 - ${hundredIO.size} cities (Dispatchers.IO) in ${duration5.inWholeMilliseconds} ms")

    // 6 - 在虚拟线程调度器上做同样的事
    Executors.newVirtualThreadPerTaskExecutor().asCoroutineDispatcher().use { virtuals ->
        val (hundredVirtual, duration6) = measureTimedValue {
            (1..100).map { async(virtuals) { readTemperatureBlocking("city$it") } }.awaitAll()
        }
        println("6 - ${hundredVirtual.size} cities (virtual threads) in ${duration6.inWholeMilliseconds} ms")
    }
}

// 模拟查询一个一秒后应答的远程服务
suspend fun readTemperature(city: String): Int {
    delay(1000)
    // 由城市名称派生出的"温度"
    return 10 + city.length
}

// 同一个操作,以阻塞方式编写
fun readTemperatureBlocking(city: String): Int {
    Thread.sleep(1000)
    return 10 + city.length
}

结果:

1
2
3
4
5
6
7
> gradlew -q run -Pmain=async12.Async12Kt
1 - in sequence: [16, 15, 16] in 3045 ms
2 - concurrently: [16, 15, 16] in 1027 ms
3 - 6 cities: [16, 15, 16, 15, 14, 14] in 1004 ms
4 - 6 cities (Dispatchers.IO): [16, 15, 16, 15, 14, 14] in 1061 ms
5 - 100 cities (Dispatchers.IO) in 2018 ms
6 - 100 cities (virtual threads) in 1026 ms

说明:

  • 第 60–64 行:模拟的操作:延迟一秒,然后给出一个由城市名称长度推导出来的“温度”;
  • 第 14–21 行:每个操作都被直接调用,因此在下一个操作开始之前完成:3 秒(结果的第 2 行)。函数 [measureTimedValue { … }] 来自标准库([kotlin.time]),它执行代码块并返回一个 [TimedValue] 对象,其中包含代码块的值和其执行耗时;这是一个数据类,被解构为两个变量([val (sequence, duration1) = …],第 3 章)。耗时是一个 [Duration],其中 [inWholeMilliseconds] 表示毫秒数。由于代码块是 [inline] 的,因此可以在其中调用挂起函数;
  • 第 23–28 行:使用 [async] 在三个协程中启动这三个操作,然后等待它们。它们同时运行:用时一秒而不是三秒(第 3 行)。[await] 调用的 顺序无关紧要:第一个调用等待第一个操作结束,而其他调用发现它们的操作已经结束或几乎结束;
  • 第 32–35 行:操作列表的情形。[cities.map { city -> async { … } }] 为每个城市启动一个协程,并生成一个 [Deferred<Int>] 列表;扩展函数 [awaitAll()] (适用于 [Deferred] 集合)会等待所有操作并按操作的顺序(而不是它们结束的顺序)返回结果列表。这六个操作合计用时一秒(第 4 行)。与 Java 版本(对 [allOf] 一个 [CompletableFuture] 数组调用,随后是用 [join] 收集结果的后续操作)相比,代码十分直截了当;
  • 第 39–43 行:用阻塞函数([readTemperatureBlocking],第 67–69 行)做同样的事,在 [Dispatchers.IO] 上执行:每个操作都会阻塞该调度器的一个线程;六个操作合计用时一秒(第 5 行);
  • 第 45–49 行:有 100 个阻塞操作时,[Dispatchers.IO] 的 64 线程上限就显现出来了:先是 64 个操作,然后是其余的 36 个,总共两秒(第 6 行)。这与我们在 [Async01.kt] 的 10 线程线程池中已经遇到的线程饥饿是同一回事,只是规模更大;
  • 第 51–56 行:在虚拟线程调度器上执行同样的 100 个阻塞操作:一秒(第 7 行),因为被阻塞的虚拟线程不占用任何系统线程。[virtuals] 是 [use] 的参数,即该调度器,它作为上下文传给 [async] 。

最后两步展示了协程和虚拟线程如何互补:协程用于使用挂起函数编写的代码,而虚拟线程——通过调度器——用于在协程中执行从 Java 继承来的大量阻塞代码。

9.5.2. 第一个完成的操作:select

函数 [select] (包 [kotlinx.coroutines.selects])挂起协程,直到几个事件之一发生,并返回与该事件关联的值。每个可能的事件都是一个 子句:[onAwait] 对应一个 [Deferred] 的结束(子句接收其结果),[onJoin] 对应一个 [Job] 的结束,[onReceive] 对应通道中一个值的到达……它相当于 [CompletableFuture.anyOf],但结果是带类型的。程序 [Async13.kt] 以三种方式使用它:

// select:对第一个完成的操作作出反应
package async13

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.delay
import kotlinx.coroutines.joinAll
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.selects.select

var start = System.nanoTime()

fun main() = runBlocking {
    start = System.nanoTime()
    // 1 - 查询三个镜像服务器,保留第一个应答
    val requests = listOf(
        async { query("mirror-paris", 800) },
        async { query("mirror-lyon", 300) },
        async { query("mirror-lille", 600) })
    // select 挂起协程,直到其中一个子句被选中
    val first = select {
        requests.forEach { request -> request.onAwait { answer -> answer } }
    }
    display("1 - first answer: $first")
    // 其他请求继续进行:这里等待它们以便查看它们的应答
    display("1 - all the answers: ${requests.awaitAll()}")

    // 2 - 同样的事情,但已经没用的请求被取消
    start = System.nanoTime()
    val requests2 = listOf(
        async { query("mirror-paris", 800) },
        async { query("mirror-lyon", 300) },
        async { query("mirror-lille", 600) })
    val first2 = select {
        requests2.forEach { request -> request.onAwait { answer -> answer } }
    }
    requests2.forEach { it.cancel() }
    // 我们等待被取消的请求结束
    requests2.joinAll()
    display("2 - first answer: $first2, the other requests are cancelled")

    // 3 - 一个有时间限制的操作:它与 delay"竞速"
    start = System.nanoTime()
    val slow = async { query("slow-server", 2000) }
    val timer = launch { delay(500) }
    val answer: String? = select {
        slow.onAwait { it }
        timer.onJoin { null }
    }
    if (answer != null) {
        display("3 - answer obtained in time: $answer")
    } else {
        display("3 - the slow server did not answer within 500 ms: it is cancelled")
        slow.cancel()
    }
    slow.join()
    display("3 - end of the program")
}

// 模拟一个在 [duration] 毫秒后应答的服务器
suspend fun query(server: String, duration: Long): String {
    try {
        delay(duration)
        return "$server ($duration ms)"
    } catch (e: CancellationException) {
        // 协程在等待期间被取消:报告这一点,然后重新抛出异常
        display("  $server: request cancelled (${e.javaClass.simpleName})")
        throw e
    }
}

// 显示,附带自 [start] 以来经过的时间
fun display(message: String) = println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

结果:

1
2
3
4
5
6
7
8
9
> gradlew -q run -Pmain=async13.Async13Kt
  374 ms : 1 - first answer: mirror-lyon (300 ms)
  854 ms : 1 - all the answers: [mirror-paris (800 ms), mirror-lyon (300 ms), mirror-lille (600 ms)]
  325 ms :   mirror-paris: request cancelled (JobCancellationException)
  329 ms :   mirror-lille: request cancelled (JobCancellationException)
  340 ms : 2 - first answer: mirror-lyon (300 ms), the other requests are cancelled
  524 ms : 3 - the slow server did not answer within 500 ms: it is cancelled
  524 ms :   slow-server: request cancelled (JobCancellationException)
  525 ms : 3 - end of the program

说明:

  • 第 62–70 行:模拟的服务器在指定的时间后响应。如果查询它的协程在等待期间被取消,[delay] 会抛出一个 [CancellationException]:我们拦截它以标记这个问题,然后重新抛出它(我们将在关于取消的一节中看到为什么这是必不可少的)。[kotlinx.coroutines.CancellationException] 是 JDK 的 [java.util.concurrent.CancellationException] 类的别名;实际抛出的异常属于库的一个派生自它的内部类 [JobCancellationException];
  • 第 17–21 行:查询三个镜像服务器;它们都包含相同的信息,响应速度各不相同,每个查询在一个协程中进行;
  • 第 23–26 行:[select] 块为每个查询声明一个 [onAwait] 子句;每个子句的 lambda 接收查询结果,并返回 [select] 的值。子句可以在循环中声明,如这里所示。第一个完成的 [Deferred] 胜出:第一个响应在略多于 300 毫秒后到达(结果的第 2 行;首次使用 [select] 会多加载几个类);它的类型是 [String],无需类型转换,不像 [anyOf],后者返回的是 [Object];
  • 第 28 行:[select] 没有停止其他查询,它们继续进行:[awaitAll()] 等待它们显示所有响应(第 3 行);
  • 第 30–42 行:在大多数情况下,其他请求已经没有必要了。与 [CompletableFuture] 不同,协程可以被真正终止:[cancel()] 取消每个请求(取消已经完成的请求没有效果),而 [joinAll()] 等待被取消的请求完成。结果的第 4 行和第 5 行显示,两个待处理的请求在等待期间被中断;它们不再消耗任何资源;
  • 第 44–59 行:一个经典的用例:与时间限制赛跑。等待 500 毫秒的 [onJoin] 子句,属于 [Job] [timer],返回 [null];如果它获胜,就说明操作耗时太长,该操作随即被取消(第 7–9 行)。[answer] 的类型是 [String?]:[select] 要么返回响应字符串,要么返回 [null]。Kotlinx.coroutines 提供了更直接的方式来处理这种情况:函数 [withTimeoutOrNull],稍后会介绍。

9.5.3. 在结果到来时就处理

我们常常希望在多个操作完成时就处理它们的结果,而不必等待最慢的那个。Java 课程用两种方式做到这一点:为每个 [CompletableFuture] 附加一个后续操作,或者把任务委托给 [ExecutorCompletionService],它按任务完成的顺序交付 [Future] 。使用协程,同样有两种方式:在产生结果的协程内部使用该结果,或者通过 通道 ([Channel],即协程之间的队列)传递结果。程序 [Async14.kt] 使用这两种方法处理五个“文件”,每个文件需要 100 到 900 毫秒来处理:

// 按操作完成的顺序处理结果
package async14

import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

var start = 0L
val durations = listOf(900L, 300L, 700L, 100L, 500L)

fun main() = runBlocking {
    // 1 - 每个文件一个协程:每个协程一拿到结果就使用它
    start = System.nanoTime()
    coroutineScope {
        durations.forEachIndexed { i, duration ->
            launch { display(process("file$i.txt", duration)) }
        }
    } // coroutineScope 等待这五个协程结束
    display("1 - all the files have been processed")

    // 2 - 协程把结果发送到一个通道中,由单个协程使用它们
    start = System.nanoTime()
    val results = Channel<String>()
    durations.forEachIndexed { i, duration ->
        launch { results.send(process("file$i.txt", duration)) }
    }
    // receive() 挂起协程,直到下一个结果到达
    repeat(durations.size) {
        display(results.receive())
    }
    display("2 - all the files have been processed")
}

// 模拟处理一个持续 [duration] 毫秒的文件
suspend fun process(file: String, duration: Long): String {
    delay(duration)
    return "$file processed in $duration ms"
}

// 显示,附带自 [start] 以来经过的时间
fun display(message: String) = println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

结果:

> gradlew -q run -Pmain=async14.Async14Kt
  133 ms : file3.txt processed in 100 ms
  326 ms : file1.txt processed in 300 ms
  525 ms : file4.txt processed in 500 ms
  725 ms : file2.txt processed in 700 ms
  922 ms : file0.txt processed in 900 ms
  923 ms : 1 - all the files have been processed
  176 ms : file3.txt processed in 100 ms
  373 ms : file1.txt processed in 300 ms
  573 ms : file4.txt processed in 500 ms
  775 ms : file2.txt processed in 700 ms
  976 ms : file0.txt processed in 900 ms
  976 ms : 2 - all the files have been processed

说明:

  • 第 36–39 行:模拟对一个文件的处理,它耗时指定的时间;
  • 第 14–21 行:每个处理操作都在各自的协程中启动,协程一旦有结果就显示它:文件 3(100 毫秒)最先显示,文件 0(900 毫秒)最后显示(结果的第 2–6 行)。这相当于附加在每个 [CompletableFuture] 上的后续操作,但处理和显示是一前一后写出来的:[display(process(...))]。[coroutineScope] 块等待五个协程全部结束;它取代了 Java 程序中的 [allOf] 。函数 [forEachIndexed] 遍历列表 [durations],同时返回索引和元素;
  • 第 23–33 行:五个协程把结果发送到一个通道([Channel<String>]),使用的是挂起函数 [send];主协程使用挂起函数 [receive()] 逐个接收它们,该函数会等待下一个可用的结果。因此它按处理完成的顺序接收结果(第 8–12 行):这相当于 Java 的 [CompletionService],但不阻塞任何线程。由 [Channel<String>()] 创建的通道没有缓冲区:每个 [send] 都要等待某个协程接收这个值(这是一种“会合”)。通道将在本章后面详细讨论;
  • 在这两种情况下,整个过程都持续 900 毫秒——即最长操作的耗时——并且每个结果都尽早得到处理。当每个结果可以独立于其他结果处理时,第一种方法适用;当必须由单独一段代码接收所有结果时,例如汇总它们或在图形用户界面中显示它们,第二种方法适用。

9.6. 协程中的异常

9.6.1. try/catch,以及结构化并发中的传播

使用 [CompletableFuture] 时,异常不会被抛回给发起操作的代码:它存储在 [CompletableFuture] 中,沿着后续操作链传播,并通过专门的方法来处理([exceptionally]、[handle]、[whenComplete])。使用挂起函数时,问题要简单得多:挂起函数就像普通函数一样抛出异常,并用 [try / catch] 拦截它们,即使异常是在挂起之后在另一个线程上抛出的。只有一件新东西需要学习:当由 [launch] 或 [async] 启动的协程失败时会发生什么。程序 [Async15.kt] 考察了各种不同的情况:

// 协程中的异常:普通的 try / catch,结构化并发中的传播
package async15

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.Deferred
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.supervisorScope

fun main() = runBlocking<Unit> {
    // 1 - 挂起函数像普通函数一样抛出异常
    try {
        val value = readValue("twelve")
        println("value = $value")
    } catch (e: NumberFormatException) {
        println("1 - readValue throws ${name(e)} : ${e.message}")
    }

    // 2 - 失败时的替代值:try 是一个表达式
    val value = try {
        readValue("thirteen")
    } catch (_: NumberFormatException) {
        -1
    }
    println("2 - replacement value: $value")

    // 3 - catch 处理失败,finally 在所有情况下都会运行
    for (text in listOf("14", "fifteen")) {
        val report = try {
            "value ${readValue(text)}"
        } catch (e: NumberFormatException) {
            "failure, ${name(e)}"
        } finally {
            println("3 - finally: the reading of [$text] is finished")
        }
        println("3 - report: $report")
    }

    // 4 - 参数错误走同样的路径
    try {
        readValue(" ")
    } catch (e: IllegalArgumentException) {
        println("4 - readValue throws ${name(e)} : ${e.message}")
    }

    // 5 - coroutineScope 中的多个操作:第一个失败会取消其他操作
    val texts = listOf("1", "two", "3", "four")
    val readings = mutableListOf<Deferred<Int>>()
    try {
        coroutineScope {
            texts.forEach { text -> readings += async { readValue(text) } }
            println("5 - results: ${readings.awaitAll()}")
        }
    } catch (e: NumberFormatException) {
        println("5 - coroutineScope throws ${name(e)} : ${e.message}")
    }
    // 每个操作都保留了它的结果或异常
    readings.forEachIndexed { i, reading -> println("      [${texts[i]}] : ${outcome(reading)}") }

    // 6 - 捕获 await() 的异常是不够的:子协程的失败已经到达了父协程
    try {
        coroutineScope {
            val reading = async { readValue("six") }
            val result = try {
                reading.await()
            } catch (e: NumberFormatException) {
                println("6 - await() threw ${name(e)}, caught")
                -1
            }
            println("6 - the code continues with $result…")
        }
    } catch (e: NumberFormatException) {
        println("6 - … but coroutineScope rethrows ${name(e)} : ${e.message}")
    }

    // 7 - supervisorScope:子协程的失败只影响该子协程
    supervisorScope {
        val readings7 = texts.map { text -> async { readValue(text) } }
        readings7.forEachIndexed { i, reading -> println("7 - [${texts[i]}] : ${outcome(reading)}") }
    }
}

// 一个操作,如果字符串不是整数则失败;每个字符耗时 100 毫秒
suspend fun readValue(text: String): Int {
    // 检查参数
    require(text.isNotBlank()) { "the text must not be empty" }
    delay(100L * text.length)
    return text.toInt()
}

// 操作的结局:它的结果、它的异常,或它的取消
suspend fun outcome(reading: Deferred<Int>): String = try {
    "success, result = ${reading.await()}"
} catch (e: CancellationException) {
    "cancelled (${name(e)})"
} catch (e: NumberFormatException) {
    "failure, ${name(e)} : ${e.message}"
}

// 异常所属类的简单名称
fun name(e: Throwable): String = e.javaClass.simpleName

结果:

> gradlew -q run -Pmain=async15.Async15Kt
1 - readValue throws NumberFormatException : For input string: "twelve"
2 - replacement value: -1
3 - finally: the reading of [14] is finished
3 - report: value 14
3 - finally: the reading of [fifteen] is finished
3 - report: failure, NumberFormatException
4 - readValue throws IllegalArgumentException : the text must not be empty
5 - coroutineScope throws NumberFormatException : For input string: "two"
      [1] : success, result = 1
      [two] : failure, NumberFormatException : For input string: "two"
      [3] : success, result = 3
      [four] : cancelled (JobCancellationException)
6 - await() threw NumberFormatException, caught
6 - the code continues with -1…
6 - … but coroutineScope rethrows NumberFormatException : For input string: "six"
7 - [1] : success, result = 1
7 - [two] : failure, NumberFormatException : For input string: "two"
7 - [3] : success, result = 3
7 - [four] : failure, NumberFormatException : For input string: "four"

说明:

  • 第 86–91 行:被测试的函数。它首先使用 [require] (第 3 章)检查它的参数,如果条件为假,就抛出 [IllegalArgumentException] 。然后它对文本的每个字符等待 100 毫秒,并转换整个文本,如果它不是数字,就会触发 [NumberFormatException] ;
  • 第 14–19 行:正常情况。挂起之后由 [toInt()] 抛出的异常被调用者的 [try / catch] 原样捕获:既不使用 [CompletionException],也不使用 [ExecutionException],也不用 [cause] 方法来追溯到原始异常(结果的第 2 行);
  • 第 22–28 行:[try] 是一个 Kotlin 表达式:它的值是 [try] 块的值或 [catch] 块的值。这相当于 [exceptionally] 方法,它属于 [CompletableFuture] (第 3 行)。参数 [_] 表示不使用该异常;
  • 第 30–39 行:[catch] 把失败转换为结果(相当于 [handle]),[finally] 在所有情况下都会执行(相当于 [whenComplete]):第 4 行到第 7 行。使用的是常规的工具;
  • 第 42–46 行:在 Java 中,返回 [CompletableFuture] 的方法可能以两种方式失败——在被调用时抛出异常(参数验证),或者返回一个失败的操作——调用者必须为这两种情况都做好准备。挂起函数只有一种失败方式:抛出异常(第 8 行);
  • 第 49–58 行:在 *[async] 作用域 *[coroutineScope]* 内用 [awaitAll()] 发起四次读取并等待它们。对 ["two"] 的读取操作在 300 毫秒后失败。根据结构化并发的规则,一个子协程的失败会使它的父协程,即该作用域,以及它的所有其他子协程失效:对 ["four"] 的读取操作,本应持续 400 毫秒,也就失效了。[coroutineScope] 随后抛出失败子协程的异常(第 9 行)。第 55 行永远不会执行:[awaitAll()]* 同样抛出该异常;
  • 第 61 行:每个 [Deferred] 都保留了它的结果,函数 [outcome] (第 94–100 行)通过调用 [await()] 来检查它:对于已完成的操作,[await()] 立即返回其结果或抛出其异常,而对于被回滚的操作,它抛出 [CancellationException]。结果的第 10 行到第 13 行显示了两个成功的操作(["1"] 和 ["3"],它们在失败之前完成)、失败,以及 ["four"] 的取消。在大多数情况下这就是期望的行为:如果得出结果所需的任何一个操作失败,结果就无法产生,继续执行其他操作也就没有意义了;
  • 第 63–76 行:一个经典的陷阱。由 [await()] 抛出的异常被捕获并替换为默认值,代码继续执行(第 14 行和第 15 行);但是子协程的失败已经传播给了它的 父协程,该父协程已被取消:在其代码块结束时,[coroutineScope] 无论如何都会抛出异常(第 16 行)。为了防止失败影响父协程,要么 在 失败的协程内部捕获它([async { try { readValue("six") } catch (e: NumberFormatException) { -1 } }]),要么使用监督作用域;
  • 第 79–82 行:[supervisorScope { … }] 创建一个 监督作用域:与 [coroutineScope] 一样,它等待它的所有子协程,并在自己被中止时中止它们,但某个子协程的失败只影响它自己:它既不会中止该作用域,也不会中止其他子协程。每个读取操作都运行到结束,调用者检查每个操作的结果(第 17–20 行):这一次,对 ["four"] 的读取操作是失败而不是被取消。当各个操作相互独立时,这正是所需要的:例如,即使有一个城市没有响应,也要显示六个城市的温度。

Java 课程得出的结论是,虚拟线程中的异常与普通代码中的异常处理方式相同,只是在两个线程的边界处例外;这对协程同样成立,而且结构化并发解决了边界问题:子协程的失败会自动传播回父协程。

9.6.2. 被遗忘的协程、CoroutineExceptionHandler、SupervisorJob 和 GlobalScope

Java 课程展示过,一个没有人等待的操作所产生的异常会丢失,没有任何消息。在结构化并发中,协程不可能真正被遗忘:它的作用域会等待它,并且在普通作用域中,它的失败会传播给父协程。但是监督作用域不会取消父协程,而且有办法在任何结构之外启动协程:在这种情况下,异常会怎样?程序 [Async16.kt] 演示了这一点:

// 没有人等待其结果的协程:它们的异常去了哪里?
package async16

import kotlinx.coroutines.CoroutineExceptionHandler
import kotlinx.coroutines.CoroutineName
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.DelicateCoroutinesApi
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.GlobalScope
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.async
import kotlinx.coroutines.cancel
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.supervisorScope

// 处理没有任何协程捕获的异常的处理程序
val handler = CoroutineExceptionHandler { context, e ->
    println("CoroutineExceptionHandler: ${e.message} (coroutine ${context[CoroutineName]?.name})")
}

@OptIn(DelicateCoroutinesApi::class)
fun main() {
    // 线程的未捕获异常处理程序
    Thread.setDefaultUncaughtExceptionHandler { thread, e ->
        println("uncaught exception in [${thread.name}] : ${e.message}")
    }
    runBlocking {
        supervisorScope {
            // 1 - 被等待的 Deferred:它的异常被捕获
            val a = async { save("a") }
            try {
                a.await()
            } catch (e: IllegalStateException) {
                println("1 - awaited Deferred: exception caught: ${e.message}")
            }

            // 2 - 没有人等待的 Deferred:它的异常保留在对象中
            async { save("b") }
            println("2 - forgotten Deferred: the coroutine is launched")

            // 3 - Job 没有可存放异常的结果:异常交给线程的处理程序
            launch { save("c") }
            println("3 - launch without a handler: the coroutine is launched")

            // 4 - ……或者交给协程上下文中存在的 CoroutineExceptionHandler
            launch(handler + CoroutineName("saver-d")) { save("d") }
            println("4 - launch with a CoroutineExceptionHandler: the coroutine is launched")

            // 5 - 启动后不等待,但自己处理失败
            launch {
                try {
                    save("e")
                } catch (e: IllegalStateException) {
                    println("5 - failure handled by the coroutine itself: ${e.message}")
                }
            }

            // 程序继续它的工作……
            for (i in 1..3) {
                delay(100)
                println("the program is working ($i)")
            }
        } // supervisorScope 等待它所有的子协程,即使是被"遗忘"的

        // 6 - 应用程序某个组件专属的作用域,使用 SupervisorJob
        val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default + handler)
        scope.launch(CoroutineName("saver-f")) { save("f") }
        scope.launch(CoroutineName("counter")) {
            repeat(3) {
                delay(100)
                println("6 - the counter continues its work despite the failure of its sibling ($it)")
            }
        }
        delay(400)
        // 组件结束:其作用域启动的一切都被取消
        scope.cancel()

        // 7 - GlobalScope:在任何结构之外启动的协程,没有人等待它
        GlobalScope.launch { save("g") }
        GlobalScope.launch {
            delay(1000)
            println("7 - this message will never be displayed")
        }
        delay(300)
    }
    println("normal end of the program")
}

// 一个在 200 毫秒后失败的操作
suspend fun save(data: String) {
    delay(200)
    throw IllegalStateException("failure saving [$data]")
}

结果:

> gradlew -q run -Pmain=async16.Async16Kt
1 - awaited Deferred: exception caught: failure saving [a]
2 - forgotten Deferred: the coroutine is launched
3 - launch without a handler: the coroutine is launched
4 - launch with a CoroutineExceptionHandler: the coroutine is launched
the program is working (1)
uncaught exception in [main] : failure saving [c]
CoroutineExceptionHandler: failure saving [d] (coroutine saver-d)
5 - failure handled by the coroutine itself: failure saving [e]
the program is working (2)
the program is working (3)
6 - the counter continues its work despite the failure of its sibling (0)
CoroutineExceptionHandler: failure saving [f] (coroutine saver-f)
6 - the counter continues its work despite the failure of its sibling (1)
6 - the counter continues its work despite the failure of its sibling (2)
uncaught exception in [DefaultDispatcher-worker-1] : failure saving [g]
normal end of the program

说明:

  • 第 91–94 行:所有情形都使用的操作,它在 200 毫秒后失败;
  • 第 26–27 行:与 Java 程序一样,我们设置了当线程中的异常未被任何代码捕获时调用的处理器。没有它,JVM 会把异常的堆栈跟踪打印到错误输出;
  • 第 18–20 行:*[CoroutineExceptionHandler] 是一个上下文元素,它接收没有任何协程处理过的异常;它由一个接收失败协程的上下文和异常的 lambda 创建。[context[CoroutineName]] 返回上下文中的 [CoroutineName] 元素,如果不存在则返回 [null]* :上下文被用作以元素类型为索引的关联数组;
  • 情形 1 至 5 中的所有协程都在 *[supervisorScope]* 中启动:其中一个协程的失败不会传播到父级,因此必须由其他地方来处理它;
  • 第 31–36 行:使用 [await()] 等待该操作;其异常被正常拦截(结果的第 2 行);
  • 第 39–41 行:由 [async] 启动的协程,没有人对它调用 [await()]。它的异常被存储在 [Deferred] 中,而该对象被忽略:异常就此丢失,就像被遗忘的 [CompletableFuture] 的异常一样,没有任何地方会显示它。[async] 协程本来就是为了被等待而设计的;如果不需要它的结果,请使用 [launch];
  • 第 43–45 行:由 [launch] 启动的协程没有用来存放其异常的结果。如果它的父级不处理该异常(在监督作用域中就是这种情况),异常会被传递给上下文中的 [CoroutineExceptionHandler],若没有它,则传递给执行该协程的线程的未捕获异常处理器,此处为 [main] (第 7 行)。不过线程并不会停止:它会继续执行其他协程;
  • 第 47–49 行:同一个协程,但上下文中带有 [CoroutineExceptionHandler] :接收异常的正是它(第 8 行);
  • 第 51–56 行:启动一个操作而不等待其结果的最佳方式:协程使用 [try / catch] 自行处理其失败(第 9 行);
  • 第 60–65 行:程序继续执行其工作;在代码块结束时,[supervisorScope] 会等待它的所有子协程,包括那些我们以为已被“遗忘”的协程;
  • 第 67–78 行:应用程序组件(屏幕、服务、连接)如果启动的协程要与组件本身存活一样长的时间——而不仅仅是一次函数调用的时间——就需要有自己的作用域。它通过函数 [CoroutineScope(context)] 创建,通常搭配 [SupervisorJob()](一种 *[Job]*,其中一个子协程的失败不会终止其他子协程,相当于以这种方式创建的作用域的 *[supervisorScope] )、一个调度器和一个异常处理器。由 [scope.launch { … }] 启动的协程是 [SupervisorJob] 的子协程:[saver-f] 的失败被交给处理器(第 13 行),并不会妨碍 [counter] 继续工作(第 12–15 行)。当组件消失时,[scope.cancel()] 会取消该作用域启动的一切:没有任何协程能比它的组件活得更久。框架的作用域就是这样工作的,例如 Android 上的 [viewModelScope] 和 [lifecycleScope]* ;
  • 第 80–86 行:[GlobalScope] 是一个没有 [Job] 的全局作用域,在程序的整个生命周期内都存在。由 [GlobalScope.launch] 启动的协程没有父级:没有人等待它,没有人取消它,其异常被传递给执行它的线程的处理器(此处是 [Dispatchers.Default] 的一个线程,即 [GlobalScope] 的默认调度器:第 16 行)。本应在一秒后显示一条消息的第二个协程则被直接丢弃:[runBlocking] 并不等待它,程序在没有它的情况下结束(第 17 行);
  • 第 23 行:[GlobalScope] 带有 [@DelicateCoroutinesApi] 注解:使用它会触发编译器警告,而在我们项目的 [allWarningsAsErrors] 选项下,该警告会变成错误:
warning: this is a delicate API and its use requires care. Make sure you fully read and understand documentation of the declaration that is marked as a delicate API.
  • 放在函数上的 [@OptIn(DelicateCoroutinesApi::class)] 注解告诉编译器我们知道自己在做什么,从而使警告消失。Kotlin 库使用这种 “选择加入”(opt-in) 机制来标记那些棘手或仍处于实验阶段的 API。

规则与 Java 中相同,但结构化并发使它几乎成为自动的:每个协程都必须属于一个会等待它的作用域,并且它的失败必须得到处理——要么由协程自己处理,要么由它的父级处理,要么由 [CoroutineExceptionHandler] 处理。我们避免使用 [GlobalScope],只有极少数确实需要与程序活得一样久的协程除外;相反,我们为每个组件创建一个作用域,并在其生命周期结束时销毁它。

9.7. 取消与超时

9.7.1. 协作式取消

长时间运行的操作必须能够被取消:用户点击了 [Cancel],服务器的某个客户端断开了连接,应用程序窗口被关闭,或者超过了超时时间。Java 为此使用线程中断:[interrupt()] 设置一个标志;阻塞式等待会通过抛出 [InterruptedException] 而被中断;而计算则必须自行检查该标志。Java 课程还指出了一个陷阱:[cancel] 方法在 [CompletableFuture] 上并不会中断任何东西,因为 [CompletableFuture] 并不知道是哪个线程在为它工作。

协程有自己的机制,它同样是协作式的,但已集成在库中:

  • [cancel()] 方法作用于 [Job] (或 [Deferred])时,会将其设置为“正在取消”状态;它不会强行终止协程,也不会让调用者等待。[join()] 随后等待协程结束;[cancelAndJoin()] 则两者兼做;
  • 如果协程挂起在 kotlinx.coroutines 的某个挂起函数中([delay]、[await]、[join]、[receive]、[withContext]……),该函数会立即恢复协程,并让它抛出 [CancellationException]。如果协程在已被取消时调用这些函数之一,情况也一样。所有这些函数都被称为可取消的;
  • 该异常像普通异常一样沿调用栈向上传播,途中会执行 [finally] 块和 [use] 函数,从而干净地释放资源。到达协程顶部时,它会使协程以“已取消”状态结束;这并不是失败:[CancellationException] 永远不会传递给父级或异常处理器;
  • 只进行计算而从不调用挂起函数的协程不受影响:它必须使用 [isActive] (只要没有被取消就为 true)、[ensureActive()] (如果已被取消,则抛出 [CancellationException] )或 [yield()] (它把线程让给其他协程,并顺便检查是否已被取消)来检查自身状态;
  • 取消一个 [Job] 会取消它的子协程,正如我们在结构化并发中所见。

程序 [Async17.kt] 以多种方式取消一个模拟下载和一个模拟计算:

// 取消协程:cancel、协作式取消、finally 和 NonCancellable
package async17

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.NonCancellable
import kotlinx.coroutines.cancelAndJoin
import kotlinx.coroutines.currentCoroutineContext
import kotlinx.coroutines.delay
import kotlinx.coroutines.isActive
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withContext
import kotlinx.coroutines.yield

var start = 0L

fun main() = runBlocking {
    // 1 - 由 delay 等待组成的下载可以被取消,无需任何特殊处理
    start = System.nanoTime()
    val downloading = launch { download(10) }
    delay(1000)
    // cancel() 请求取消,join() 等待协程完全停止
    downloading.cancel()
    downloading.join()
    display("1 - isCancelled=${downloading.isCancelled}, isCompleted=${downloading.isCompleted}")

    // 2 - 从不挂起的计算会忽略取消请求
    start = System.nanoTime()
    val computation2 = launch(Dispatchers.Default) { compute(checkCancellation = false) }
    delay(300)
    display("2 - cancellation request of the computation")
    computation2.cancelAndJoin()
    display("2 - isCancelled=${computation2.isCancelled}")

    // 3 - 定期检查自己是否已被取消的计算
    start = System.nanoTime()
    val computation3 = launch(Dispatchers.Default) { compute(checkCancellation = true) }
    delay(300)
    display("3 - cancellation request of the computation")
    computation3.cancelAndJoin()
    display("3 - isCancelled=${computation3.isCancelled}")

    // 4 - 在 runBlocking 线程上,yield() 让其他协程工作
    start = System.nanoTime()
    val computation4 = launch {
        var rounds = 0L
        while (true) {
            rounds++
            // 每一千万轮就让出一次线程(并检查取消)
            if (rounds % 10_000_000 == 0L) yield()
        }
    }
    delay(300)
    display("4 - the main coroutine was able to take over again: cancellation of the computation")
    computation4.cancelAndJoin()
    display("4 - isCancelled=${computation4.isCancelled}")

    // 5 - 被取消协程的清理:finally,如果必须挂起则使用 NonCancellable
    start = System.nanoTime()
    val downloading5 = launch {
        try {
            download(10)
        } finally {
            // 被取消的协程不能再挂起:delay 会立即抛出异常……
            try {
                delay(100)
            } catch (e: CancellationException) {
                display("  finally: delay throws ${e.javaClass.simpleName}")
            }
            // ……在使用 NonCancellable 上下文执行的块中除外
            withContext(NonCancellable) {
                display("  finally: closing the connection…")
                delay(200)
                display("  finally: connection closed")
            }
        }
    }
    delay(700)
    downloading5.cancelAndJoin()
    display("5 - end of the cancelled download")
}

// 模拟下载 [nbBlocks] 个数据块(每 300 毫秒一个块)
suspend fun download(nbBlocks: Int) {
    try {
        for (i in 1..nbBlocks) {
            // 如果协程在等待期间被取消,delay 会抛出 CancellationException
            delay(300)
            display("  block $i/$nbBlocks received")
        }
    } catch (e: CancellationException) {
        display("  download cancelled (${e.javaClass.simpleName})")
        // 被捕获的 CancellationException 必须重新抛出
        throw e
    }
}

// 一个长时间的计算;如有需要,它每一千万轮检查一次其协程是否仍处于活动状态
suspend fun compute(checkCancellation: Boolean) {
    var sum = 0L
    for (i in 1..1_000_000_000L) {
        if (checkCancellation && i % 10_000_000 == 0L && !currentCoroutineContext().isActive) {
            display("  computation interrupted at round $i")
            return
        }
        sum += i % 7
    }
    display("  computation finished, sum = $sum")
}

// 显示,附带自 [start] 以来经过的时间
fun display(message: String) = println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

结果:

> gradlew -q run -Pmain=async17.Async17Kt
  322 ms :   block 1/10 received
  647 ms :   block 2/10 received
  947 ms :   block 3/10 received
 1022 ms :   download cancelled (JobCancellationException)
 1027 ms : 1 - isCancelled=true, isCompleted=true
  314 ms : 2 - cancellation request of the computation
 1237 ms :   computation finished, sum = 3000000003
 1240 ms : 2 - isCancelled=true
  301 ms : 3 - cancellation request of the computation
  306 ms :   computation interrupted at round 170000000
  307 ms : 3 - isCancelled=true
  323 ms : 4 - the main coroutine was able to take over again: cancellation of the computation
  324 ms : 4 - isCancelled=true
  301 ms :   block 1/10 received
  602 ms :   block 2/10 received
  700 ms :   download cancelled (JobCancellationException)
  705 ms :   finally: delay throws JobCancellationException
  707 ms :   finally: closing the connection…
  908 ms :   finally: connection closed
  909 ms : 5 - end of the cancelled download

说明:

  • 第 84–95 行:模拟下载每 300 毫秒接收一个数据块。它无需任何特殊措施就能被取消:[delay] 是可取消的。我们拦截 [CancellationException] 以报告取消,然后将其重新抛出:被拦截的 [CancellationException] 必须始终重新抛出;否则,协程会若无其事地继续运行,即使它已被取消(而且它随后调用的任何可取消函数都会立即抛出新的异常)。出于同样的原因,要警惕 ***[catch (e: Exception)]**,它也会拦截 *[CancellationException]*,以及标准库函数 [runCatching]*,它会拦截一切;
  • 第 19–26 行:一秒后,程序用 *[cancel()] 取消下载,然后用 *[join()] 等待它结束。下载在等待第四个数据块的过程中立即停止(结果的第 2–5 行);被取消并已终止的协程具有 [isCancelled=true] 和 [isCompleted=true] (第 6 行)。与 [cancel] 或 [CompletableFuture] 不同,被停止的是操作本身,而不仅仅是对其结果的等待;
  • 第 99–109 行:对某个任意计算进行十亿次迭代。如有需要,该计算每一千万次迭代检查一次其协程是否仍处于活动状态:[currentCoroutineContext()] 返回当前协程的上下文,其扩展属性 [isActive] 指示与该上下文关联的 [Job] 是否处于活动状态。我们本可以改为编写 [currentCoroutineContext().ensureActive()],如果协程已被取消,它会抛出 [CancellationException] ;
  • 第 28–34 行:计算在 [Dispatchers.Default] 上启动,且不做任何检查。300 毫秒时的取消请求(第 7 行)对它没有影响:它一直运行到结束(第 8 行),而 [cancelAndJoin()] 等待它结束。尽管如此,[Job] 仍处于已取消状态(第 9 行);
  • 第 36–42 行:同样的计算,但带有检查:它在取消请求之后几毫秒就停止了(第 10–12 行);
  • 第 44–57 行:启动一个无限计算,这次是在 [runBlocking] 的线程上,它与主协程共享该线程。如果没有 [yield()],它会独占该线程:主协程在 [delay(300)] 之后将永远无法恢复,因此也无法取消该计算,程序也就永远不会结束。[yield()] 挂起协程并把它重新放回其调度器的队列中,从而让线程可供其他协程使用;如果协程在此期间已被取消,[yield()] 会抛出 [CancellationException],从而终止循环(第 13 和 14 行);
  • 第 59–81 行:在 [finally] 块中清理被取消的协程。关闭连接可能需要调用挂起函数;然而,已被取消的协程无法再挂起自身:任何可取消函数都会立即抛出 [CancellationException],如 [delay(100)] 在 [finally] 块中所示(第 18 行)。为了仍然执行需要挂起的代码,要用 [withContext(NonCancellable) { … }] 来执行它:[NonCancellable] 是一个永远不会被取消的 [Job] ,代码块会正常运行直至结束(第 19 和 20 行)。该代码块必须简短:它会推迟取消的完成,而 [cancelAndJoin()] 正在等待取消完成(第 21 行)。

请注意,取消并不是突然的中断:它是一个在挂起点抛出的异常,沿代码回溯并执行 [finally] 块。任何用可取消的挂起函数编写的代码都可以毫不费力地被取消;而长时间的计算则必须定期检查 [isActive] ,或调用 [ensureActive()] 或 [yield()]。

9.7.2. 多个进程,多种结果

程序 [Async18.kt] 沿用了那个 Java 程序:它启动五个持续 1 到 5 秒的处理,其中 3 号处理抛出异常,4 号处理被取消。它在每个处理结束时立即处理其结果,不论其结束方式如何,并且始终知道那是哪一个处理:

// 五个耗时 1 到 5 秒的处理:3 号抛出异常,4 号被取消
package async18

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.async
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.selects.select
import kotlinx.coroutines.supervisorScope

// 一个处理的结果
data class ProcessingResult(val duration: Int, val actualDuration: Double)

var start = 0L

fun main() = runBlocking {
    start = System.nanoTime()
    // supervisorScope:一个处理的失败不会取消其他处理
    supervisorScope {
        val processings = List(5) { number -> async { sleep(number, number + 1) } }
        // 4 号处理在 2.5 秒后被取消
        launch {
            delay(2500)
            processings[4].cancel()
        }
        display("the ${processings.size} processings are launched")

        // 每个处理一结束就被使用,无论它以何种方式结束
        val inProgress = processings.withIndex().toMutableList()
        while (inProgress.isNotEmpty()) {
            // select 返回第一个结束的处理及其编号
            val finished = select {
                inProgress.forEach { processing -> processing.value.onJoin { processing } }
            }
            inProgress.remove(finished)
            val (number, processing) = finished
            // 处理已结束:await() 立即返回其结果或抛出其异常
            val report = try {
                val result = processing.await()
                "finished: scheduled duration %d s, actual duration %.1f s"
                    .format(result.duration, result.actualDuration)
            } catch (_: CancellationException) {
                "cancelled"
            } catch (e: IllegalStateException) {
                "encountered the following error: ${e.message}"
            }
            display("processing $number $report")
        }
    }
}

// 处理:休眠 [duration] 秒,按一秒一片进行
suspend fun sleep(number: Int, duration: Int): ProcessingResult {
    val processingStart = System.nanoTime()
    // 3 号处理的异常
    check(number != 3) { "test...." }
    repeat(duration) { delay(1000) }
    // 返回给调用者的结果
    return ProcessingResult(duration, (System.nanoTime() - processingStart) / 1e9)
}

// 显示,附带自开始以来经过的时间,单位为秒
fun display(message: String) = println("%4.1f s : %s".format((System.nanoTime() - start) / 1e9, message))

结果:

1
2
3
4
5
6
7
> gradlew -q run -Pmain=async18.Async18Kt
 0.0 s : the 5 processings are launched
 0.1 s : processing 3 encountered the following error: test....
 1.1 s : processing 0 finished: scheduled duration 1 s, actual duration 1.0 s
 2.1 s : processing 1 finished: scheduled duration 2 s, actual duration 2.0 s
 2.6 s : processing 4 cancelled
 3.1 s : processing 2 finished: scheduled duration 3 s, actual duration 3.0 s

说明:

  • 第 53–60 行:处理本身。3 号处理立即失败:如果条件为 false,函数 [check] (第 3 章)会抛出 [IllegalStateException] 。其他处理借助 [duration] 秒,以一秒为增量通过 [delay] “睡眠”(它可以被取消),并返回一个结果——一个数据类([ProcessingResult],第 13 行),其中包含预定的持续时间和实际的持续时间;
  • 第 20 行:各处理相互独立:在监督作用域内,3 号处理的失败不会取消其他处理;
  • 第 21 行:这五个处理由 [async] 启动;由五个 [Deferred<ProcessingResult>] 组成的列表由 [List(5) { number -> … }] 构造;
  • 第 22–25 行:一个协程会在 2.5 秒后取消 4 号处理,尽管它还要睡眠 2.5 秒。Java 程序为此需要一个 *[ScheduledExecutorService]*;而在这里,一个以 *[delay]* 开头的协程就足够了;
  • 第 30 行:[withIndex()] 以 [IndexedValue] 对象(一个有两个属性 [index] 和 [value] 的数据类)的形式,把每个任务与其编号关联起来,并存储在一个由进行中的处理组成的可变列表中;
  • 第 33–36 行:只要还有进行中的处理,[select] 就等待第一个结束的处理,不论它如何结束:[onJoin] 子句一旦 [Job] 完成就会被选中——无论是成功、失败还是被取消。该子句返回该处理的 [IndexedValue] ,随后将其从列表中移除;
  • 第 37 行:解构赋值把编号与处理分开;
  • 第 39–46 行:使用 [await()] 检查处理的结果,它此时不再阻塞执行:它返回结果、抛出处理的异常,或者在处理被取消时抛出 [CancellationException]。[catch] 的顺序很重要:[CancellationException] 派生自 [IllegalStateException] (它是 JDK 的子类),因此必须先拦截它。在这里,拦截 *[CancellationException]* 而不重新抛出是合理的,因为它来自另一个 *[Job]*——被取消的处理——而不是来自拦截它的协程;
  • 结果显示,3 号处理立即失败,0、1、2 号处理分别在 1、2、3 秒后结束,4 号处理在 2.5 秒时被取消。Java 程序使用 [Future] 的 [switch] 来检查 [Future.State] 的常量,以此判断其状态;而使用协程时,处理的结果自然地通过 [try / catch] 来读取。

9.7.3. 限制等待时长:withTimeout 和 withTimeoutOrNull

Kotlinx.coroutines 提供了两个用于限制代码块持续时间的挂起函数:

  • [withTimeout(timeout) { … }] 执行代码块并返回其值;如果代码块没有在时限内完成,它会被取消,随后 [withTimeout] 抛出 [TimeoutCancellationException](一个派生自 [CancellationException] 的类);
  • [withTimeoutOrNull(timeout) { … }] 做同样的事,但返回 [null] 而不是抛出异常。

超时时间以毫秒或持续时间([withTimeout(2.seconds)])表示。程序 [Async19.kt] 演示了这两个函数、它们的局限(阻塞代码),以及如何组合两种终止条件:

// 限制等待的时长:withTimeout、withTimeoutOrNull、runInterruptible
package async19

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.TimeoutCancellationException
import kotlinx.coroutines.cancelAndJoin
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.runInterruptible
import kotlinx.coroutines.withContext
import kotlinx.coroutines.withTimeout
import kotlinx.coroutines.withTimeoutOrNull

var start = 0L

fun main() = runBlocking {
    // 1 - withTimeout:我们等待不超过一秒,并且操作被取消
    start = System.nanoTime()
    try {
        display("1 - answer: ${withTimeout(1000) { query("slow-server", 3000) }}")
    } catch (e: TimeoutCancellationException) {
        display("1 - ${e.javaClass.simpleName} : ${e.message}")
    }

    // 2 - withTimeoutOrNull:超过一秒后,我们满足于一个默认答案
    start = System.nanoTime()
    val answer = withTimeoutOrNull(1000) { query("slow-server", 3000) } ?: "default answer"
    display("2 - $answer")

    // 3 - 阻塞代码会忽略取消:withTimeout 一直等到它结束
    start = System.nanoTime()
    try {
        withTimeout(1000) {
            withContext(Dispatchers.IO) { queryBlocking("slow-server", 3000) }
        }
    } catch (e: TimeoutCancellationException) {
        display("3 - ${e.javaClass.simpleName}, but after three seconds")
    }

    // 4 - runInterruptible:协程的取消会中断执行阻塞代码的线程
    start = System.nanoTime()
    try {
        withTimeout(1000) {
            runInterruptible(Dispatchers.IO) { queryBlocking("slow-server", 3000) }
        }
    } catch (e: TimeoutCancellationException) {
        display("4 - ${e.javaClass.simpleName} after one second")
    }

    // 5 - 两个停止原因:每个处理自己的超时和一个总的停止
    start = System.nanoTime()
    val all = launch {
        launch { processWithTimeout("fast", 500, 1000) }
        launch { processWithTimeout("slow", 3000, 1000) }
        launch { processWithTimeout("medium", 1500, 2000) }
    }
    // 调用者在 1,200 毫秒后请求总的停止
    delay(1200)
    display("5 - general stop requested")
    all.cancelAndJoin()
}

// 一个限制为 [timeout] 毫秒的处理,调用者也可以取消它
suspend fun processWithTimeout(name: String, duration: Long, timeout: Long) {
    val message = try {
        withTimeout(timeout) { query(name, duration) }
    } catch (_: TimeoutCancellationException) {
        "$name: timeout of $timeout ms exceeded"
    } catch (e: CancellationException) {
        display("5 - $name: stopped at the caller's request")
        throw e
    }
    display("5 - $message")
}

// 模拟一个在 [duration] 毫秒后应答的服务器
suspend fun query(server: String, duration: Long): String {
    try {
        delay(duration)
        return "$server answered in $duration ms"
    } catch (e: CancellationException) {
        display("  $server: operation cancelled")
        throw e
    }
}

// 同一个操作,以阻塞方式编写
fun queryBlocking(server: String, duration: Long): String {
    try {
        Thread.sleep(duration)
        display("  $server has finished its work")
        return "$server answered in $duration ms"
    } catch (e: InterruptedException) {
        display("  $server was interrupted")
        throw e
    }
}

// 显示,附带自 [start] 以来经过的时间
fun display(message: String) = println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

结果:

> gradlew -q run -Pmain=async19.Async19Kt
 1009 ms :   slow-server: operation cancelled
 1028 ms : 1 - TimeoutCancellationException : Timed out waiting for 1000 ms
 1001 ms :   slow-server: operation cancelled
 1002 ms : 2 - default answer
 3014 ms :   slow-server has finished its work
 3022 ms : 3 - TimeoutCancellationException, but after three seconds
 1001 ms :   slow-server was interrupted
 1003 ms : 4 - TimeoutCancellationException after one second
  504 ms : 5 - fast answered in 500 ms
 1004 ms :   slow: operation cancelled
 1005 ms : 5 - slow: timeout of 1000 ms exceeded
 1201 ms : 5 - general stop requested
 1204 ms :   medium: operation cancelled
 1204 ms : 5 - medium: stopped at the caller's request

说明:

  • 第 78–85 行:模拟服务器,它会报告自己被取消;
  • 第 19–24 行:我们等待响应的时间不超过一秒。一秒后,代码块被取消:操作确实停止了(结果的第 2 行),随后 [withTimeout] 抛出 [TimeoutCancellationException],其消息提到了超时(第 3 行)。这与 [orTimeout] 方法(属于 [CompletableFuture])有显著区别,后者放弃了等待,却让操作白白继续运行;
  • 第 27–30 行:如果超过了超时时间,[withTimeoutOrNull] 返回 [null] ;随后 Elvis 运算符 [?:] 用默认响应替换 [null] (第 4 和 5 行)。这相当于 [completeOnTimeout],但更简短,而且,操作同样会被真正终止;
  • 第 32–39 行:协作式取消的局限。限时一秒的代码块执行一个阻塞函数([queryBlocking],第 89–97 行),运行在 [Dispatchers.IO] 上,该函数用 [Thread.sleep] 睡眠三秒。一秒后,协程确实被取消了,但没有任何东西能够停止 [Thread.sleep]:该函数一直运行到结束(第 6 行),直到三秒后 [withContext] 返回时,[TimeoutCancellationException] 才被抛出(第 7 行)。这段延迟毫无意义;
  • 第 42–49 行:为了确保取消协程能够停止阻塞代码,使用 [runInterruptible(dispatcher) { … }] 来执行它:该函数在指定的调度器上执行代码块,如果协程被取消,就用 Java 的 中断执行它的线程,使用的是 [interrupt()] 方法。[Thread.sleep] 随后抛出 [InterruptedException] (第 8 行),[runInterruptible] 再将其转换为 [CancellationException]。这在协程取消与线程中断之间架起了一座桥梁:操作在一秒后停止(第 9 行)。这仅适用于可中断的阻塞代码([Thread.sleep]、[java.util.concurrent] 中的等待、[java.nio] 中的通道……);
  • 第 65–75 行:一个可能因两个原因而被停止的处理——它自己的超时,或调用者发出的总体停止请求。两者都以异常的形式出现:超时对应 [TimeoutCancellationException] ,由 [withTimeout] 触发;协程被[CancellationException] 所取消则对应调用者的取消。超时是处理的一种正常结果,被转换为一条消息;而取消则是先报告,然后重新抛出。两个 [catch] 子句必须按此顺序排列,因为 [TimeoutCancellationException] 派生自 [CancellationException];
  • 第 52–62 行:三个处理,是同一个协程 [all] 的子协程。对于总体终止,Java 程序必须额外创建一个 [CompletableFuture] ,并给它附加一个取消每个等待的后续操作;在这里,总体终止就是简单地取消父协程,而父协程又会取消它的子协程。处理 [fast] 正常结束(第 10 行),[slow] 处理超过了其一秒的超时(第 11 和 12 行),而 [medium] 处理被分配了 2 秒,却在 1200 毫秒时被总体关闭所终止(第 13–15 行)。

9.8. 报告进度

长时间运行的操作往往需要报告其进度(进度条、百分比)。最简单的做法是给它传递一个接收进度更新的回调函数 。在 Java 中,这是一个 [Consumer<T>];在 Kotlin 中,它就是一个函数式参数(第 7 章),即 [(Progress) -> Unit]。操作在每一步调用该函数;它对进度报告将如何显示一无所知。

在图形应用程序中会出现线程问题:图形组件只能由 UI 线程更新。使用协程,答案很简单:如果执行操作的协程是在 *[Dispatchers.Main] 上启动的,那么报告就在 UI 线程上输出,回调函数可以直接更新组件;如果操作的一部分工作在别处执行(使用 [withContext(Dispatchers.IO)]),它就在该代码块之外报告其结果,或者让回调函数通过 [withContext(Dispatchers.Main)] 回到界面线程(此时回调函数本身就是一个挂起函数,类型为 [suspend (Progress) -> Unit])。在控制台程序中,它可以直接显示输出。程序 [Async20.kt] 模拟一次文件复制,用户可以通过键入 [Enter]* 来取消它:

// 用回调函数报告操作的进度;用户可以取消它
package async20

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.async
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import kotlin.concurrent.thread

// 一个进度报告
data class Progress(val percentage: Int, val file: String)

fun main() = runBlocking {
    println("Copy in progress, press [Enter] to cancel it")
    // 复制由一个协程执行;display 函数显示它的报告
    val copy = async { copyFiles(8, ::display) }
    // 一个守护线程等待用户按 [Enter] 来取消复制
    thread(isDaemon = true) {
        // 如果标准输入已关闭,readlnOrNull 返回 null:不会取消任何东西
        if (readlnOrNull() != null) {
            copy.cancel()
        }
    }
    try {
        println("Copy finished: ${copy.await()} files copied")
    } catch (_: CancellationException) {
        println("Copy cancelled by the user")
    }
}

// 操作不知道它的进度如何显示:它只负责报告
suspend fun copyFiles(nbFiles: Int, progress: ((Progress) -> Unit)? = null): Int {
    for (i in 1..nbFiles) {
        // 复制一个文件
        delay(300)
        // 进度报告,如果调用者需要的话
        progress?.invoke(Progress(100 * i / nbFiles, "file$i.dat"))
    }
    return nbFiles
}

// 在控制台中显示进度报告:一个 20 个字符的进度条
fun display(progress: Progress) {
    val nbHashes = progress.percentage / 5
    val bar = "#".repeat(nbHashes) + ".".repeat(20 - nbHashes)
    println("[%s] %3d %% %s".format(bar, progress.percentage, progress.file))
}

未取消时的结果(标准输入已关闭:[readlnOrNull()] 立即返回 [null]):

> gradlew -q run -Pmain=async20.Async20Kt
Copy in progress, press [Enter] to cancel it
[##..................]  12 % file1.dat
[#####...............]  25 % file2.dat
[#######.............]  37 % file3.dat
[##########..........]  50 % file4.dat
[############........]  62 % file5.dat
[###############.....]  75 % file6.dat
[#################...]  87 % file7.dat
[####################] 100 % file8.dat
Copy finished: 8 files copied

用户在复制操作进行约一秒半后键入 [Enter] 时的结果(键入的空行不会显示:输入是通过重定向其标准输入提供给程序的):

1
2
3
4
5
6
7
> gradlew -q run -Pmain=async20.Async20Kt
Copy in progress, press [Enter] to cancel it
[##..................]  12 % file1.dat
[#####...............]  25 % file2.dat
[#######.............]  37 % file3.dat
[##########..........]  50 % file4.dat
Copy cancelled by the user

说明:

  • 第 11 行:一个进度报告,一个包含百分比和文件名的数据类;
  • 第 31–39 行:操作本身,一个挂起函数。它的参数 [progress] 的类型为 [((Progress) -> Unit)?]:一个接受 [Progress] 且不返回任何值的函数,或者如果调用者不需要报告,则为 [null] ,这是默认值。每处理完一个文件,它就通过 [progress?.invoke(...)] 报告进度:如果 [?.] 所作用的 [progress] 为 [null],该调用什么也不做(不能写成 [progress?(...)]:必须使用函数式类型的 [invoke] 方法)。用 [delay] 进行的 300 毫秒等待,使操作变得可取消;
  • 第 42–46 行:显示一个报告:用 [repeat] 构造的 20 个字符的进度条。函数引用 [::display] (第 16 行)就是传递给该操作的回调函数;
  • 第 16 行:复制由 [runBlocking] 线程上的一个协程执行;
  • 第 17–21 行:一个线程等待用户键入 [Enter],然后取消复制。[readlnOrNull()] 是从标准输入进行的阻塞读取,无法被取消。因此,它不能在 [runBlocking] 作用域内的协程中执行:结构化并发会迫使 [runBlocking] 等待这个协程结束——也就是等待用户键入内容——即使复制已经完成。因此它在由函数 [thread] 通过 [isDaemon = true] 创建的线程中执行:这是一个守护线程,程序结束时会将其丢弃。这是一种必须有意脱离结构化并发的情形;这是通过显式的工具(守护线程)完成的,而不是使用 [GlobalScope]。[cancel()] 方法可以从任何线程调用,它属于 [Job] ;
  • 第 24–27 行:程序等待复制结束。取消会导致 [CancellationException] 由 [await()] 抛出。与 [Async18.kt] 中一样,可以拦截它而不重新抛出,因为它源自另一个协程——复制操作——的取消;相反,复制操作的失败会传播到 [runBlocking] 并终止程序。

回调函数适用于简单的报告。本章接下来将介绍一种更通用的工具,用于异步地生成一系列值:流 ([Flow]):返回 [Flow<Progress>] 的操作会在结果可用时逐个报告,而调用者在其选择的调度器上使用 [collect] 收集它们。

9.9. 异步输入/输出

9.9.1. 文件

I/O 正是异步存在的根本原因。对于文件,JDK 提供了两类类,Kotlin 可以直接使用:

  • “经典的”阻塞式类:[Files]、[BufferedReader]、[BufferedWriter],以及 Kotlin 为它们添加的扩展函数(第 5 章):[readLines]、[readText]、[useLines]、[bufferedWriter]、[writeText]、[appendText]……在协程程序中,这些操作在专用于阻塞操作的 [Dispatchers.IO] 调度器上执行,借助 [withContext(Dispatchers.IO) { … }]:调用方协程被挂起——但其线程不会被阻塞——而由 [IO] 调度器的一个线程执行该操作;
  • [AsynchronousFileChannel] 类(Java 7),其操作返回 [Future] 或调用 [CompletionHandler]。它很少被使用:在 Linux 上,它实际上是在 JVM 内部的线程池上执行阻塞读取,而且它的接口很笨拙。它借助 [suspendCancellableCoroutine] 适配到协程,例如程序 [Async02.kt] 中的 TCP 客户端。

程序 [Async21.kt] 通过在主线程中读取位于项目根目录的税率档文件 [TaxData.txt],展示这两类类:

1
2
3
4
5
6
7
4962:0:0
8382:0.068:291.09
14753:0.191:1322.92
23888:0.283:2668.39
38868:0.374:4846.98
47932:0.426:6883.66
0:0.481:9505.54

每一行包含税率档阈值、系数 [coeffR] 和系数 [coeffN],以字符 [:] 分隔,并用小数点书写(税率表是 2003 年收入适用的 2004 年税率表,本财政年度原样沿用)。程序在 [09-async] 文件夹中运行(这是 [gradlew run] 的当前文件夹),并在当前文件夹中查找它的文件。文件 [taxpayers.txt] 将用于本章末尾的练习,放在同一位置。

// 文件输入 / 输出:适配为挂起函数的 AsynchronousFileChannel,
// 然后是交给 IO 调度器的普通阻塞 I/O
package async21

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.suspendCancellableCoroutine
import kotlinx.coroutines.withContext
import java.math.BigDecimal
import java.nio.ByteBuffer
import java.nio.channels.AsynchronousFileChannel
import java.nio.channels.CompletionHandler
import java.nio.file.Path
import java.nio.file.StandardOpenOption
import kotlin.coroutines.resume
import kotlin.coroutines.resumeWithException
import kotlin.io.path.appendText
import kotlin.io.path.bufferedWriter
import kotlin.io.path.deleteExisting
import kotlin.io.path.readLines
import kotlin.io.path.readText
import kotlin.io.path.useLines
import kotlin.time.measureTimedValue

val data: Path = Path.of("TaxData.txt")
val report: Path = Path.of("report-21.txt")

fun main() = runBlocking {
    // 1 - AsynchronousFileChannel(Java 7):带回调的读取,转换为挂起函数
    val content = readAsynchronously(data)
    println("1 - AsynchronousFileChannel: ${content.trimEnd().lines().size} lines")

    // 2 到 7 - 普通阻塞 I/O,在 IO 调度器上执行
    processFiles()

    // 8 - 并行读取多个文件:每个文件一个协程,在 IO 调度器上
    val files = listOf("TaxData.txt", "taxpayers.txt", "TaxData.txt").map { Path.of(it) }
    val (nbLines, duration) = measureTimedValue {
        files.map { file -> async { readSlowly(file) } }.awaitAll()
    }
    println("8 - lines read in parallel: $nbLines in ${duration.inWholeMilliseconds} ms")
}

// 用 AsynchronousFileChannel 读取整个(小)文件,不阻塞线程
suspend fun readAsynchronously(file: Path): String =
    AsynchronousFileChannel.open(file, StandardOpenOption.READ).use { channel ->
        val buffer = ByteBuffer.allocate(channel.size().toInt())
        // 协程被挂起;回调方法将恢复它
        val nbBytes = suspendCancellableCoroutine { continuation ->
            channel.read(buffer, 0, Unit, object : CompletionHandler<Int, Unit> {
                override fun completed(nbBytes: Int, attachment: Unit) = continuation.resume(nbBytes)
                override fun failed(e: Throwable, attachment: Unit) = continuation.resumeWithException(e)
            })
        }
        String(buffer.array(), 0, nbBytes, Charsets.UTF_8)
    }

// 阻塞 I/O:withContext 让 IO 调度器的一个线程来执行它
suspend fun processFiles() = withContext(Dispatchers.IO) {
    // 2 - 一次操作读取整个文件
    val lines = data.readLines()
    println("2 - readLines: ${lines.size} lines [${Thread.currentThread().name}]")

    // 3 - 逐行读取:useLines 提供一个行序列并关闭文件
    val brackets = data.useLines { sequence -> sequence.map(TaxBracket::parse).toList() }
    println("3 - useLines: ${brackets.size} brackets, 2nd: ${brackets[1]}")

    // 4 - 行序列按需读取:文件不会被加载到内存中
    println("4 - useLines + count: ${data.useLines { it.count() }} lines")

    // 5 - 用 BufferedWriter 写入,由 use 关闭
    report.bufferedWriter().use { writer ->
        writer.write("Brackets of the tax scale (exercise: 2004 tax scale on 2003 income)")
        writer.newLine()
        brackets.forEachIndexed { i, bracket ->
            val limit = if (bracket.limit.signum() == 0) "above"
            else "up to %,d €".format(bracket.limit.toInt())
            writer.write("bracket %d : %-18s rate %.1f %%".format(i + 1, limit,
                bracket.coeffR * BigDecimal(100)))
            writer.newLine()
        }
    }

    // 6 - 将整个文件读取为字符串
    print("5 and 6 - content of [$report]:\n${report.readText()}")

    // 7 - 追加到文件末尾,然后删除
    report.appendText("end of the report\n")
    println("7 - last line: ${report.readLines().last()}")
    report.deleteExisting()
}

// 一个持续 500 毫秒的阻塞读取(例如慢速磁盘上的文件)
suspend fun readSlowly(file: Path): Int = withContext(Dispatchers.IO) {
    Thread.sleep(500)
    file.readLines().size
}

// 一个税率档;文件使用小数点,BigDecimal 能够理解
data class TaxBracket(val limit: BigDecimal, val coeffR: BigDecimal, val coeffN: BigDecimal) {
    companion object {
        fun parse(line: String): TaxBracket {
            val (limit, coeffR, coeffN) = line.split(":").map(::BigDecimal)
            return TaxBracket(limit, coeffR, coeffN)
        }
    }
}

结果:

> gradlew -q run -Pmain=async21.Async21Kt
1 - AsynchronousFileChannel: 7 lines
2 - readLines: 7 lines [DefaultDispatcher-worker-1]
3 - useLines: 7 brackets, 2nd: TaxBracket(limit=8382, coeffR=0.068, coeffN=291.09)
4 - useLines + count: 7 lines
5 and 6 - content of [report-21.txt]:
Brackets of the tax scale (exercise: 2004 tax scale on 2003 income)
bracket 1 : up to 4,962 €      rate 0.0 %
bracket 2 : up to 8,382 €      rate 6.8 %
bracket 3 : up to 14,753 €     rate 19.1 %
bracket 4 : up to 23,888 €     rate 28.3 %
bracket 5 : up to 38,868 €     rate 37.4 %
bracket 6 : up to 47,932 €     rate 42.6 %
bracket 7 : above              rate 48.1 %
7 - last line: end of the report
8 - lines read in parallel: [7, 7, 7] in 519 ms

说明:

  • 第 47–57 行:使用 [AsynchronousFileChannel] 读取,呈现为一个返回文件内容的挂起函数。该通道是一个 [Closeable]:[use] 函数(第 3 章)在代码块结束时关闭它,不论结果如何,包括协程被取消的情况。这与程序 [Async02.kt] 中使用的技术相同:[suspendCancellableCoroutine] 挂起协程,并把控制权交还给代码块;读取操作带着一个回调对象启动,该对象用读取的字节数([resume])或异常([resumeWithException])恢复协程。Java 程序必须自己构造并完成一个 [CompletableFuture],然后在 [whenComplete] 后续操作中关闭通道;在这里,代码是自上而下阅读的。对于小文件,一次读取就足够了;大文件则需要连续多次读取,只需把它们写在协程的循环中即可;
  • 第 33 行:Kotlin 函数 [lines()] 把字符串拆分成行;如果字符串以换行符结尾,列表就以一个空字符串结束(与 Java 方法 [lines()] 不同)。[trimEnd()] 去掉这最后一个换行符;
  • 第 61 行:其他操作都是普通的阻塞式 I/O 操作,被归入挂起函数 [processFiles] 中,它的整个函数体由 [withContext(Dispatchers.IO)] 执行。结果第 3 行显示的线程名([DefaultDispatcher-worker-…])表明运行代码的已经不再是主线程。Java 程序把这些操作委托给一个虚拟线程,并且必须拦截 [IOException] ,拦截位置在 [Runnable] 的 lambda 内;在 Kotlin 中没有受检异常,[IOException] 如果在 [withContext] 代码块内抛出,会在调用方协程中重新抛出;
  • 第 63 行:[readLines()] 是 [Path] 的扩展函数(包 [kotlin.io.path]),它读取整个文件并返回其行的列表(默认使用 UTF-8);
  • 第 67 行:[useLines] 打开文件,把文件各行的序列([Sequence<String>],按需读取)传给代码块,并在代码块结束时关闭文件:这相当于 Java 程序中的 [readLine()] 循环,而无需处理 [null] 或带资源的 [try] 。每一行由数据类的伴生对象的 [parse] 函数(第 102–106 行)转换为 [TaxBracket] 。它用 [split] 拆分该行,使用构造函数引用 [::BigDecimal] 把三个字段转换为 [BigDecimal],并通过解构赋值取出它们。[BigDecimal] 的构造函数要求使用小数点,与机器的语言无关。数据类的 [toString] 方法生成的表示形式出现在结果的第 4 行;
  • 第 71 行:行序列不会把整个文件加载到内存中;这是处理大文件的首选方式。它只能在 [useLines] 代码块内使用,因为退出代码块时文件就被关闭了;
  • 第 73–82 行:使用 [BufferedWriter] 写入,它通过 [bufferedWriter()] 扩展函数获得,并由 [use] 关闭(因而刷新到磁盘)。[%,d] 格式会插入与机器语言相关的千位分隔符(英语中是逗号,法语中是细的不间断空格);乘积 [bracket.coeffR * BigDecimal(100)] 使用 Kotlin 标准库为 [*] 运算符针对 [BigDecimal] 定义的运算符(扩展函数 [times],第 4 章);
  • 第 86–92 行:[readText()] 重新读取写入的文件,[appendText] 向其中追加一行,[last()] 返回列表的最后一个元素,然后 [deleteExisting()] 删除该文件;
  • 第 38–43 行:并行读取多个文件。每个读取操作由一个协程([async])处理,而 [awaitAll()] 等待三个结果。函数 [readSlowly] (第 96–98 行)模拟在慢速磁盘上 500 毫秒的阻塞读取;由于它在 [IO] 调度器上运行,这三次读取占用三个不同的线程,总共耗时 500 毫秒,而不是 1.5 秒(结果第 16 行)。请注意,这些协程由 [async] 启动,没有指定调度器:由被调用的函数通过 [withContext] 选择适合其任务的调度器。这就是应当遵循的规则:阻塞式挂起函数必须自己通过 IO 调度器运行,这样调用者就可以从任何线程调用它,而无需采取任何特殊的预防措施。

默认情况下,[IO] 调度器把同时活动的线程数限制为 64(程序 [Async12.kt])。若要同时读取数千个文件,可以使用虚拟线程创建一个调度器(程序 [Async09.kt]);但要记住 Java 课程中提到的限制:文件的读写在操作期间会把虚拟线程固定在其宿主线程上。对于本地文件,这很少是问题;对于网络操作,虚拟线程和协程在等待期间确实会释放其线程。

9.9.2. 网络:HttpClient

JDK 的 HTTP 客户端 [java.net.http.HttpClient] (Java 11)提供两种方式:[send],它是阻塞的并返回响应;以及 [sendAsync],它立即返回一个包含响应的 [CompletableFuture] 。在协程中,我们使用来自 [kotlinx.coroutines.future] 包的挂起函数 [await()] 来等待这个 [CompletableFuture],我们已经在程序 [Async04.kt] 中遇到过它:协程会被挂起,直到收到响应,而不会阻塞任何线程。第 12 章将详细研究这个客户端;程序 [Async22.kt] 只是通过查询一个本地的小型 HTTP 服务器来比较这两种方法,该服务器需要一秒钟才能返回一个城市的“温度”:

// HttpClient:异步 HTTP 请求(sendAsync + await)或阻塞请求(在 IO 调度器上 send)
// 发往一个小型本地 HTTP 服务器
package async22

import com.sun.net.httpserver.HttpServer
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.future.await
import kotlinx.coroutines.runBlocking
import java.net.InetAddress
import java.net.InetSocketAddress
import java.net.URI
import java.net.URLDecoder
import java.net.URLEncoder
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.util.concurrent.Executors

const val PORT = 27510
val cities = listOf("Angers", "Brest", "Colmar", "Dijon", "Évry", "Foix")
var start = System.nanoTime()

fun main() = runBlocking {
    // 一个 HTTP 服务器,需要一秒钟才给出某个城市的"温度"
    val server = HttpServer.create(InetSocketAddress(InetAddress.getLoopbackAddress(), PORT), 0)
    server.createContext("/temperature") { exchange ->
        // 请求的形式为 /temperature?city=xxx
        val city = URLDecoder.decode(exchange.requestURI.rawQuery.removePrefix("city="), Charsets.UTF_8)
        Thread.sleep(1000)
        val response = "$city : ${10 + city.length} °C".toByteArray()
        exchange.sendResponseHeaders(200, response.size.toLong())
        exchange.responseBody.use { it.write(response) }
    }
    // 收到的每个请求由一个虚拟线程处理
    server.executor = Executors.newVirtualThreadPerTaskExecutor()
    server.start()

    try {
        HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build().use { client ->
            // 先发一个请求,让 JVM 在测量之前加载客户端类
            client.sendAsync(request("Paris"), HttpResponse.BodyHandlers.discarding()).await()

            // 1 - 每个城市一个协程;每个协程被挂起直到收到响应
            start = System.nanoTime()
            val responses = cities.map { city -> async { readTemperature(client, city) } }.awaitAll()
            display("1 - sendAsync + await: $responses")

            // 2 - send 是阻塞的:从 IO 调度器调用它
            start = System.nanoTime()
            val responses2 = cities.map { city ->
                async(Dispatchers.IO) {
                    client.send(request(city), HttpResponse.BodyHandlers.ofString()).body()
                }
            }.awaitAll()
            display("2 - send on the IO dispatcher: $responses2")
        }
    } finally {
        server.stop(0)
    }
}

// 城市的温度:sendAsync 返回一个 CompletableFuture,
// await() 挂起协程直到收到响应,而不阻塞线程
suspend fun readTemperature(client: HttpClient, city: String): String =
    client.sendAsync(request(city), HttpResponse.BodyHandlers.ofString()).await().body()

// 请求某个城市温度的 GET 请求
fun request(city: String): HttpRequest {
    val parameter = URLEncoder.encode(city, Charsets.UTF_8)
    return HttpRequest.newBuilder(URI.create("http://localhost:$PORT/temperature?city=$parameter")).build()
}

// 显示,附带自 [start] 以来经过的时间
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

结果:

1
2
3
> gradlew -q run -Pmain=async22.Async22Kt
 1056 ms : 1 - sendAsync + await: [Angers : 16 °C, Brest : 15 °C, Colmar : 16 °C, Dijon : 15 °C, Évry : 14 °C, Foix : 14 °C]
 1047 ms : 2 - send on the IO dispatcher: [Angers : 16 °C, Brest : 15 °C, Colmar : 16 °C, Dijon : 15 °C, Évry : 14 °C, Foix : 14 °C]

说明:

  • 第 26–38 行:服务器。JVM 自带一个小型 HTTP 服务器,即 [HttpServer] 类,位于 [jdk.httpserver] 模块([com.sun.net.httpserver] 包)。它在本地地址([getLoopbackAddress()])和端口 27510 上创建;[createContext] 把一个处理器——一个接收 HTTP 交换对象的 lambda——与路径 [/temperature] 关联起来(Java 接口 [HttpHandler] 只有一个方法:Kotlin lambda 会被转换为它;这就是 SAM 转换,第 7 章)。处理器从请求的地址中解码 [city] 参数([removePrefix] 去掉开头的部分 [city=]),等待一秒,然后发送响应;[toByteArray()] 把字符串编码为 UTF-8。第 37 行让每个请求由一个虚拟线程处理:以这种方式配置的服务器可以为数千个等待中的客户端提供服务。请注意 [server.executor = …] 这种写法:Kotlin 把 Java 方法对 [getExecutor] / [setExecutor] 呈现为一个属性,就像 [getRequestURI()] 变成 [requestURI] 、[getResponseBody()] 变成 [responseBody] 一样;
  • 第 41 行:客户端由一个构造器([newBuilder])创建,这里设置了协议版本。从 Java 21 开始,它实现了 [AutoCloseable]:函数 [use] 在代码块结束时关闭它。第一次请求用于“预热” JVM:客户端的首次使用会加载大量的类,这会使随后的测量出现数百毫秒的偏差;
  • 第 64–67 行:挂起函数 [readTemperature]。[sendAsync(request, handler)] 发送请求并立即返回一个 [CompletableFuture<HttpResponse<String>>];响应体处理器 [BodyHandlers.ofString()] 指定响应体必须作为字符串读取。[await()] 挂起协程,直到响应到达,然后取得响应体([body()])。Java 程序链接了一个后续操作([thenApply(HttpResponse::body)]),而我们只需把这些调用依次写下来;
  • 第 45–48 行:六个协程,每个城市一个,同时发送它们的请求;它们的响应在一秒后一起到达(结果第 2 行)。在等待期间,没有任何线程在等待响应:客户端通过一个“选择器”线程监视它的连接,该线程会完成 [CompletableFuture];随后由 [runBlocking] 的调度器,即主线程,负责恢复这些协程。Java 程序必须用 [CompletableFuture] 与 [allOf] 组合起来,然后使用 [resultNow] 读取它们的结果;[awaitAll()] 则两件事一并完成;
  • 第 50–57 行:[send] 是阻塞的;它由在 [IO] 调度器上运行的六个协程调用,每个协程在等待时都占用一个线程。结果是一样的:六个请求耗时一秒(第 3 行)。这种方式适用于少量请求;对于数千个请求,[sendAsync] 和 [await()] 在等待期间不占用任何线程;
  • 第 59–60 行:服务器在程序结束时关闭,不论结果如何;[stop] 的参数是允许进行中的交换完成的秒数;
  • 第 70–72 行:GET 请求。[URLEncoder.encode] 对不能原样出现在地址中的字符(Évry 中的 [É] )进行编码,而服务器使用 [URLDecoder.decode] 对它们解码;
  • 变量 [start] (第 23 行)是一个可修改的顶层变量([var]),在每次测量之前重置为当前时间;函数 [display] 显示自 [start] 起经过的时间,与之前的程序一样。

请记住以下规则:遇到返回 CompletableFuture 的 Java API 时,协程用 await()** 等待它;遇到阻塞式 API 时,它在 [IO] 调度器上调用它。在这两种情况下,协程的代码都保持顺序执行。

9.10. 异步值流

异步操作在一段时间之后返回一个结果。序列([Sequence],第 5 章)或迭代器返回按需生成的值序列。有时需要把两者结合起来:一个值的序列,其中每个值在生成之前都需要等待。大文件中的行、SQL 查询结果中的行、通过网络连接到达的消息、传感器读数等等,都属于这种情况。Java 课程介绍了两种模型:“拉取”模型,即消费者请求下一个值并等待其到达(一个其中每个值都会阻塞、由虚拟线程读取的 [Stream] ),以及“推送”模型,即生产者把值发送给它的订阅者,由订阅者控制吞吐量(Java 9 中的 [java.util.concurrent.Flow] 接口和 [SubmissionPublisher] 类)。

Kotlinx.coroutines 提供了涵盖这两种模型的两种工具:

  • 流 ([Flow<T>],包 [kotlinx.coroutines.flow]):由挂起函数在消费者的请求下生成的值序列。它是序列的异步等价物,其运算符([map]、[filter]、[take]……)本身就是挂起函数。流是冷的:在有人收集它之前什么都不会生成,而且每次收集都会重新开始生成;
  • 通道 ([Channel<T>]),我们已经在程序 [Async14.kt] 中遇到过:协程之间的队列,生产者发送([send]),消费者接收([receive]),如果另一方跟不上,各自都会被挂起。通道是“热的”:生产者独立于消费者运行。共享流([SharedFlow]、[StateFlow])同样是热的。

C# 为同样的目的提供了异步流 [IAsyncEnumerable<T>],由 [yield return] 生成,由 [await foreach] 消费:Kotlin 的 [Flow] 就是其等价物。

9.10.1. 流

流由函数 [flow { … }] 创建,它的代码块是一个挂起函数,发出它的值,使用 [emit(value)];流由挂起函数 [collect { value -> … }] 消费,该函数对每个发出的值执行其代码块。程序 [Async23.kt] 吸收了那个生成测量值(每 200 毫秒一个)的 Java 程序,其形式为 [Stream<Measurement>]:

// 一个带等待地产生的值序列:kotlinx.coroutines 的 Flow
package async23

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.cancelAndJoin
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.filter
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.flow.flow
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.onEach
import kotlinx.coroutines.flow.take
import kotlinx.coroutines.flow.toList
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import java.text.NumberFormat

var start = System.nanoTime()

fun main() = runBlocking {
    // 1 - 每个值一产生就被处理
    start = System.nanoTime()
    readMeasurements("sensor-1", 4).collect { measurement -> display("1 - received $measurement") }

    // 2 - 收集可以在结束之前停止:生产者不再产生后面的值
    start = System.nanoTime()
    val hot = readMeasurements("sensor-2", 100)
        .onEach { measurement -> display("2 - received $measurement") }
        .first { measurement -> measurement.value >= 22 }
    display("2 - first measurement of at least 22 °C: $hot")

    // 3 - 取消:收集 Flow 的协程在 700 毫秒后被取消
    start = System.nanoTime()
    val reader = launch {
        try {
            readMeasurements("sensor-3", 100).collect { measurement -> display("3 - received $measurement") }
        } catch (e: CancellationException) {
            display("3 - reading cancelled")
            throw e
        }
    }
    delay(700)
    reader.cancelAndJoin()

    // 4 - 操作符转换 Flow:过滤、转换、限制
    start = System.nanoTime()
    val high = readMeasurements("sensor-4", 100)
        .filter { measurement -> measurement.value > 21 }
        .map { measurement -> format(measurement.value) }
        .take(4)
        .toList()
    display("4 - measurements greater than 21: ${high.joinToString(" ; ", "[", "]")}")
}

// 一个生产者:每 200 毫秒一次测量,只在收集器请求时才产生
fun readMeasurements(sensor: String, count: Int): Flow<Measurement> = flow {
    try {
        for (i in 1..count) {
            // 等待下一次测量
            delay(200)
            // emit 挂起生产者,直到收集器处理完该值
            emit(Measurement(sensor, i, 19.5 + i * 0.75))
        }
    } finally {
        // 在正常结束、收集停止后或取消时执行
        println("          $sensor: end of production")
    }
}

// 一次测量
data class Measurement(val sensor: String, val number: Int, val value: Double) {
    override fun toString() = "$sensor no. $number : ${format(value)} °C"
}

// 一个采用本机语言格式的实数,不带无用的小数
fun format(value: Double): String = NumberFormat.getInstance().format(value)

// 显示,附带自 [start] 以来经过的时间
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

结果:

> gradlew -q run -Pmain=async23.Async23Kt
  413 ms : 1 - received sensor-1 no. 1 : 20.25 °C
  615 ms : 1 - received sensor-1 no. 2 : 21 °C
  816 ms : 1 - received sensor-1 no. 3 : 21.75 °C
 1020 ms : 1 - received sensor-1 no. 4 : 22.5 °C
          sensor-1: end of production
  241 ms : 2 - received sensor-2 no. 1 : 20.25 °C
  451 ms : 2 - received sensor-2 no. 2 : 21 °C
  652 ms : 2 - received sensor-2 no. 3 : 21.75 °C
  859 ms : 2 - received sensor-2 no. 4 : 22.5 °C
          sensor-2: end of production
  864 ms : 2 - first measurement of at least 22 °C: sensor-2 no. 4 : 22.5 °C
  242 ms : 3 - received sensor-3 no. 1 : 20.25 °C
  450 ms : 3 - received sensor-3 no. 2 : 21 °C
  651 ms : 3 - received sensor-3 no. 3 : 21.75 °C
          sensor-3: end of production
  744 ms : 3 - reading cancelled
          sensor-4: end of production
 1262 ms : 4 - measurements greater than 21: [21.75 ; 22.5 ; 23.25 ; 24]

说明:

  • 第 57–67 行:生产者。函数 [readMeasurements] 不是阻塞函数:它立即返回一个 [Flow<Measurement>] ,而不生成任何内容。[flow] 的代码块只有在消费者收集该流时才会执行。它用 [delay] 等待 200 毫秒,然后用 [emit] 发出一个测量值;[emit] 是一个挂起函数,它调用消费者的 [collect] 代码块,直到该值被处理完才返回控制权:每个测量值都在下一个被生成之前处理完毕。[finally] 块就是“生产者的 [finally]”:它取代了 Java 的 [onClose] 动作(属于 [Stream] 块),不论收集如何结束都会执行;
  • 第 24 行:每个测量值在生成后立即被处理:每 200 毫秒一个(结果第 2–5 行;第一个稍晚到达,因为 JVM 要加载流相关的类),然后生产者结束(第 6 行)。没有需要关闭的流:数据收集的结束就标志着生成的结束;
  • 第 26–31 行:[onEach] 运算符对经过的每个值执行一个动作,而挂起函数 [first { condition }] 收集流直到第一个满足条件的值,返回该值,并停止收集。生产者不会生成剩下的 96 个测量值:它的 [emit] 抛出了一个内部的取消异常,使其中断并执行了它的 [finally] (结果第 11 行)。为了达到同样的结果,Java 程序必须使用其迭代器遍历流,并通过 [break] 退出;
  • 第 33–44 行:取消。流由另一个协程收集,主协程在 700 毫秒后用 [cancelAndJoin()] 取消它。第四个测量值的 [delay] 被取消:它抛出一个 [CancellationException] ,该异常穿过生产者(它的 [finally] 被执行,结果第 16 行),然后穿过 [collect],最后到达读取方的 [catch] (第 17 行),后者按预期重新抛出它。不需要线程中断:这是协作式的协程取消;
  • 第 46–53 行:运算符 [filter]、[map] 和 [take] 转换流并返回一个新的流;它们的名称取自集合和序列的函数(第 5 章)。挂起函数 [toList()] 把流收集到一个列表中。[take(4)] 在四个值之后停止收集:设置为 100 个测量值的生产者在第六个时就停止了(结果在大约 6 × 200 毫秒后可用)。Java 程序收集了六个测量值并对其进行过滤;在这里,流可以是无限的;
  • 第 72–77 行:数据类 [Measurement] 的 [toString] 方法被重新定义,以获得更紧凑的显示;[NumberFormat.getInstance()] 根据机器的语言格式化实数,不带多余的小数位([21]、[21.75])。

区分流 API 中两种类型的函数很重要:

  • 中间运算符 ([map]、[filter]、[take]、[onEach]、[flowOn]、[buffer]、[catch]……)不是挂起函数:它们立即返回一个新的流,该流描述一个过程,而不执行任何内容;
  • 终端运算符 ([collect]、[toList]、[first]、[single]、[reduce]、[fold]、[count]……)是挂起函数:它们触发生成并等待其完成。

这就是 Kotlin 序列(以及 Java 的 [Stream])所使用的模型,只不过现在每一步都可以在不阻塞线程的情况下等待。程序 [Async20.kt] 通过回调函数报告操作的进度;操作也可以返回一个 [Flow<Progress>] 并实时报告其进度,由调用者使用 [collect] 收集这些报告。

9.10.2. 冷流、flowOn、buffer 和 catch

程序 [Async24.kt] 演示了流的四个特性:它们是冷的,它们的生产者可以切换调度器,缓冲区可以使生产者与消费者解耦,以及上游异常可以被拦截:

// Flow 是冷的;flowOn、buffer 和 catch
package async24

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.buffer
import kotlinx.coroutines.flow.catch
import kotlinx.coroutines.flow.flow
import kotlinx.coroutines.flow.flowOn
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.onEach
import kotlinx.coroutines.flow.toList
import kotlinx.coroutines.runBlocking
import kotlin.time.measureTime

var start = System.nanoTime()

fun main() = runBlocking {
    // 1 - Flow 是冷的:创建它不产生任何东西;每次收集都会重新开始生产
    start = System.nanoTime()
    val values = counter("A", 3)
    display("1 - flow created")
    display("1 - 1st collection: ${values.toList()}")
    display("1 - 2nd collection: ${values.toList()}")

    // 2 - flowOn:生产者(以及 flowOn 之前的部分)在另一个调度器上运行
    start = System.nanoTime()
    counter("B", 2)
        .map { value -> "$value (transformed by ${threadName()})" }
        .flowOn(Dispatchers.Default)
        .collect { value -> display("2 - received $value, collected by ${threadName()}") }

    // 3 - 没有缓冲:生产(200 毫秒)和处理(300 毫秒)依次进行
    val withoutBuffer = measureTime {
        counter("C", 5, trace = false).collect { delay(300) }
    }
    println("3 - without a buffer: ${withoutBuffer.inWholeMilliseconds} ms")
    // 有缓冲:生产者在收集器处理的同时工作
    val withBuffer = measureTime {
        counter("D", 5, trace = false).buffer().collect { delay(300) }
    }
    println("3 - with a buffer: ${withBuffer.inWholeMilliseconds} ms")

    // 4 - catch 拦截上游的异常,并且可以发出一个替代值
    start = System.nanoTime()
    readings()
        .onEach { value -> display("4 - received $value") }
        .catch { e ->
            display("4 - error caught: ${e.message}")
            emit(-1)
        }
        .collect { value -> display("4 - collected $value") }
}

// 一个包含 [count] 个整数的 Flow,每 200 毫秒一个
fun counter(name: String, count: Int, trace: Boolean = true): Flow<Int> = flow {
    if (trace) display("    $name: start of production, by ${threadName()}")
    for (i in 1..count) {
        delay(200)
        emit(i)
    }
}

// 一个在两个值之后失败的 Flow
fun readings(): Flow<Int> = flow {
    emit(10)
    emit(20)
    throw IllegalStateException("sensor unplugged")
}

fun threadName(): String = Thread.currentThread().name

// 显示,附带自 [start] 以来经过的时间
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

结果:

> gradlew -q run -Pmain=async24.Async24Kt
    3 ms : 1 - flow created
   45 ms :     A: start of production, by main
  673 ms : 1 - 1st collection: [1, 2, 3]
  673 ms :     A: start of production, by main
 1275 ms : 1 - 2nd collection: [1, 2, 3]
   37 ms :     B: start of production, by DefaultDispatcher-worker-1
  247 ms : 2 - received 1 (transformed by DefaultDispatcher-worker-1), collected by main
  448 ms : 2 - received 2 (transformed by DefaultDispatcher-worker-1), collected by main
3 - without a buffer: 2513 ms
3 - with a buffer: 1712 ms
   26 ms : 4 - received 10
   27 ms : 4 - collected 10
   27 ms : 4 - received 20
   27 ms : 4 - collected 20
   27 ms : 4 - error caught: sensor unplugged
   27 ms : 4 - collected -1

说明:

  • 第 57–61 行:测试流:每 200 毫秒一个整数。参数 [trace] (默认值 [true])会显示生产的开始以及执行它的线程;
  • 第 20–25 行:创建流不会产生任何内容(结果第 2 行:没有生产者的踪迹)。每次收集([toList()])都会从头重新执行 [flow] 的代码块(第 3 行和第 5 行):流是一份生产配方,而不是一个已经在传输中的值的来源。这是它与通道的区别,通道将在后面讨论;
  • 第 27–32 行:默认情况下,生产者在收集者的协程中、在其调度器上运行:结果第 3 行显示第 1 部分中的生产者运行在 [main] 线程上。运算符 [flowOn(dispatcher)] 使它之前的所有内容(生产者和 [map])在另一个调度器上运行,此处是 [Dispatchers.Default],而收集仍然留在 [main] 线程上(第 7–9 行)。这是图形应用程序的工具:生产(从数据库或网络读取)发生在 [Dispatchers.IO] 或 [Default] 上,而数据收集(显示)发生在界面线程上。绝对不要在 [flow] 的代码块中围绕 [withContext] [emit] 来切换调度器:库会检测到这一点并抛出 [IllegalStateException];[flowOn] 是唯一正确的方式;
  • 第 34–43 行:没有缓冲区时,[emit] 要等待收集者处理完该值:生产(200 毫秒)和处理(300 毫秒)依次进行,五个值耗时 5 × 500 = 2500 毫秒(结果第 10 行)。[buffer()] 运算符在生产者和收集者之间放置一个通道,二者随后在两个不同的协程中运行:生产者在收集者处理前一个值的同时准备下一个值,整个过程耗时 200 + 5 × 300 = 1700 毫秒(第 11 行)。标准库的 [measureTime] 函数用于测量一个代码块的持续时间。缓冲区有容量(默认 64 个值;要使用其他值,请使用 [buffer(10)] ):缓冲区满时,生产者被挂起,直到有空位可用。这就是响应式流的背压 ,无需任何请求协议即可实现:被挂起的生产者不再生产;
  • 第 66–69 行:一个在两个值之后失败的流;
  • 第 45–53 行:运算符 [catch] 捕获上游抛出的异常(由生产者和前面的运算符抛出,此处是 [onEach])。它的代码块接收该异常,可以显示它、返回替代值(此处是 [-1],结果第 17 行),或者抛出另一个异常。它不会拦截下游异常(来自 [collect] 代码块的异常):对于这些异常,要把收集操作包在标准的 [try / catch] 中,它同样会拦截上游异常。与 [catch (e: Exception)] 不同,[catch] 运算符允许来自收集该流的协程的终止异常通过:它不会阻止终止。

其他运算符也经常有用:[transform] (对每个接收到的值发出零个、一个或多个值)、[onCompletion] (流结束时的动作,如有原因则附带其原因)、[retry] (出错后恢复生产)、[distinctUntilChanged] (忽略与前一个值相等的值)、[conflate] (慢速收集者只接收最新的值)、[scan] (累积的连续结果)、[combine] 和 [zip] (组合两个流)。

9.10.3. 通道:一个生产者,一个消费者

流是“冷的”:它的生产由消费者负责。当数据源按自己的节奏生产,不论是否有人在读取(传感器、接收到的消息、事件)时,就需要一个“热”流。最简单的是通道([Channel<T>],包 [kotlinx.coroutines.channels]),一个供协程使用的队列:它相当于 [BlockingQueue] (第 8 章),其中原先会阻塞线程的操作([put]、[take])变成了挂起函数([send]、[receive])。它的容量在创建时设定:

  • [Channel<T>()] ([Channel.RENDEZVOUS]):没有缓冲区;每个 [send] 都要等待一个 [receive] (程序 [Async14.kt]);
  • [Channel<T>(n)]:一个包含 [n] 个值的缓冲区;[send] 仅在缓冲区已满时才等待;
  • [Channel<T>(Channel.UNLIMITED)]:无限缓冲区;[send] 从不等待(有填满内存的风险);
  • [Channel<T>(Channel.CONFLATED)]:单个槽位;新值会替换尚未被读取的值。

程序 [Async25.kt] 让一个慢速消费者读取来自生产者的测量值,而该生产者无需等待它就启动:

// 生产者和消费者之间的通道(Channel):一个带缓冲的热 Flow
package async25

import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.channels.ReceiveChannel
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import java.text.NumberFormat

var start = System.nanoTime()

fun main() = runBlocking {
    // 1 - 无论是否有人读取通道,生产者都立即开始
    start = System.nanoTime()
    val measurements = produceMeasurements("sensor-1", 5)
    delay(700)
    display("consumer: start of reading")
    // for 循环逐个接收值,直到通道关闭
    for (measurement in measurements) {
        display("consumer: received $measurement")
        // 消费者比生产者慢
        delay(500)
    }
    display("1 - the channel is closed: end of reading")

    // 2 - 消费者停止读取:cancel() 关闭通道,生产者停止
    start = System.nanoTime()
    val measurements2 = produceMeasurements("sensor-2", 100)
    repeat(2) { display("2 - received ${measurements2.receive()}") }
    measurements2.cancel()
    display("2 - reading abandoned")
}

// 在调用者的作用域中启动一个生产者,并返回它发送测量值的通道
fun CoroutineScope.produceMeasurements(sensor: String, count: Int): ReceiveChannel<Measurement> {
    // 一个最多可容纳 2 个已发送但尚未接收的值的通道
    val channel = Channel<Measurement>(capacity = 2)
    launch {
        try {
            for (i in 1..count) {
                delay(200)
                // 只要缓冲区已满,send 就挂起生产者
                channel.send(Measurement(sensor, i, 19.5 + i * 0.75))
                display("    producer: measurement no. $i sent")
            }
        } finally {
            // 关闭是向消费者发出信号,表示不会再有值了
            channel.close()
            display("    producer: end of production")
        }
    }
    return channel
}

// 一次测量
data class Measurement(val sensor: String, val number: Int, val value: Double) {
    override fun toString() = "$sensor no. $number : ${NumberFormat.getInstance().format(value)} °C"
}

// 显示,附带自 [start] 以来经过的时间
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

结果:

> gradlew -q run -Pmain=async25.Async25Kt
  232 ms :     producer: measurement no. 1 sent
  501 ms :     producer: measurement no. 2 sent
  715 ms : consumer: start of reading
  739 ms : consumer: received sensor-1 no. 1 : 20.25 °C
  739 ms :     producer: measurement no. 3 sent
 1240 ms : consumer: received sensor-1 no. 2 : 21 °C
 1240 ms :     producer: measurement no. 4 sent
 1740 ms : consumer: received sensor-1 no. 3 : 21.75 °C
 1741 ms :     producer: measurement no. 5 sent
 1743 ms :     producer: end of production
 2261 ms : consumer: received sensor-1 no. 4 : 22.5 °C
 2762 ms : consumer: received sensor-1 no. 5 : 23.25 °C
 3263 ms : 1 - the channel is closed: end of reading
  202 ms :     producer: measurement no. 1 sent
  206 ms : 2 - received sensor-2 no. 1 : 20.25 °C
  409 ms :     producer: measurement no. 2 sent
  409 ms : 2 - received sensor-2 no. 2 : 21 °C
  419 ms : 2 - reading abandoned
  614 ms :     producer: end of production

说明:

  • 第 37–54 行:生产者。函数 [produceMeasurements] 是 [CoroutineScope] 的扩展:它在调用者的作用域内启动一个协程([launch] 作用于隐式接收者 [this],即该作用域),并立即返回该协程将向其发送测量值的通道。这是 kotlinx.coroutines 的约定:启动协程并且不等待它们就返回的函数,是 CoroutineScope 的扩展;而等待其工作完成的函数则是挂起函数。返回的类型 [ReceiveChannel<Measurement>] 是通道的“接收”部分:调用者只能接收;
  • 第 39 行:一个容量为 2 的通道;
  • 第 45 行:[send] 把测量值放入缓冲区,或者在缓冲区已满时挂起生产者;
  • 第 49–50 行:在生产结束时——不论是否正常——生产者都会关闭通道。关闭通道并不会清除缓冲区中的值:消费者仍会接收到它们,然后得知通道已关闭;
  • 第 17–19 行:生产者立即启动,而消费者要在 700 毫秒之后才会读取通道。在此期间,1 号和 2 号测量值填满了缓冲区(结果第 2–3 行);3 号测量值在大约 600 毫秒时准备就绪,无法提交:[send] 挂起了生产者。消费者一接收到 1 号测量值,就有了一个空位,3 号测量值随即提交(第 5–6 行)。接下来,生产者与消费者保持同步,每 500 毫秒发送一个测量值:这就是背压,只需通过挂起 [send] 即可实现;
  • 第 21–26 行:使用 [for] 循环处理通道,它逐个接收值,并在通道关闭且为空时结束。生产者在 1743 毫秒时结束(结果第 11 行);消费者仍会从缓冲区中读取那两个测量值(第 12–13 行),然后才退出循环(第 14 行);
  • 第 28–33 行:[receive()] 每次接收一个值;在两个测量值之后,消费者用 [cancel()] 停止读取,它会关闭通道并清空其缓冲区。生产者的下一个 [send] 随后会抛出一个 [CancellationException],使其协程在执行 [finally] 之后终止(结果的最后一行)。如果没有这个 [cancel()],被已满的缓冲区阻塞的生产者将永远不会终止,正在等待其子协程的 [runBlocking] 也永远不会终止。你也可以使用 [channel.consumeEach { … }] 遍历通道,它在退出代码块时会取消通道,不论原因如何。

Kotlinx.coroutines 提供了一个函数 [produce],它做的事情与 [produceMeasurements] 相同(启动一个向通道写入的协程并返回该通道),但它仍被标记为实验性:使用它会触发这一警告,因此在我们项目的 [allWarningsAsErrors] 选项下会出现错误:

1
2
3
4
error: warnings found and -Werror specified
T.kt:4:13: warning: this declaration needs opt-in. Its usage should be marked with '@kotlinx.coroutines.ExperimentalCoroutinesApi' or '@OptIn(kotlinx.coroutines.ExperimentalCoroutinesApi::class)'
    val c = produce(capacity = 2) { send(1); send(2) }
            ^^^^^^^

在本课程中,我们不使用实验性 API(必须使用 [@OptIn(ExperimentalCoroutinesApi::class)] 注解显式接受它,而且它在未来的版本中可能会改变):通道加上手写的 [launch] 只需寥寥几行就能做同样的事情。

通道把每个值交付给唯一的一个消费者:如果多个协程读取同一个通道,它们会分享这些值。这正是在工作者之间分配工作所需要的(我们将在关于受限并行的部分看到这一点),但不适用于向多个订阅者广播值。

9.10.4. 共享流:多个订阅者

为了把每个值广播给所有订阅者,kotlinx.coroutines 提供了共享流:[MutableSharedFlow<T>],发布者使用 [emit] 进行广播,订阅者把它看作 [SharedFlow<T>],并像收集任何其他流一样收集它。这相当于 Java 课程中的 [SubmissionPublisher] ,而 [Async26.kt] 程序使用同样的示例:向两个订阅者发布六个测量值,一个是在温度超过 22 °C 时取消订阅的快速显示器,另一个是慢速归档:

// 广播给多个订阅者的热 Flow:MutableSharedFlow(相当于 SubmissionPublisher)
package async26

import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.filterNotNull
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.flow.takeWhile
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import java.text.NumberFormat

val start = System.nanoTime()

fun main() = runBlocking {
    // 每个发出的值都会传递给所有订阅者;最慢的订阅者有 2 个值的缓冲区
    // null 值表示发布结束
    val publisher = MutableSharedFlow<Measurement?>(extraBufferCapacity = 2)

    // 速度快的屏幕在某次测量达到 22 °C 时立即取消订阅
    launch {
        publisher.untilTheEnd().first { measurement ->
            display("  screen: received $measurement")
            measurement.value >= 22
        }
        display("  screen: threshold reached, unsubscribing")
    }
    // 速度慢的归档程序处理每次测量需要 500 毫秒
    launch {
        publisher.untilTheEnd().collect { measurement ->
            display("  archive: received $measurement")
            delay(500)
        }
        display("  archive: end of the flow")
    }

    // 我们等待两个订阅者都注册好:共享 Flow 不会为缺席者保留任何东西
    publisher.subscriptionCount.first { count -> count == 2 }
    for (i in 1..6) {
        delay(200)
        // 如果最慢订阅者的缓冲区没有空间了,emit 会挂起发布者
        publisher.emit(Measurement("sensor-1", i, 19.5 + i * 0.75))
        display("publisher: measurement no. $i published")
    }
    display("publisher: end of publication")
    publisher.emit(null)
}

// 共享 Flow 永远不会结束:收集在 null 值处停止
fun Flow<Measurement?>.untilTheEnd(): Flow<Measurement> = takeWhile { it != null }.filterNotNull()

// 一次测量
data class Measurement(val sensor: String, val number: Int, val value: Double) {
    override fun toString() = "$sensor no. $number : ${NumberFormat.getInstance().format(value)} °C"
}

// 显示,附带自开始以来经过的时间
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

结果:

> gradlew -q run -Pmain=async26.Async26Kt
  443 ms : publisher: measurement no. 1 published
  504 ms :   screen: received sensor-1 no. 1 : 20.25 °C
  505 ms :   archive: received sensor-1 no. 1 : 20.25 °C
  688 ms : publisher: measurement no. 2 published
  688 ms :   screen: received sensor-1 no. 2 : 21 °C
  894 ms : publisher: measurement no. 3 published
  895 ms :   screen: received sensor-1 no. 3 : 21.75 °C
 1005 ms :   archive: received sensor-1 no. 2 : 21 °C
 1096 ms : publisher: measurement no. 4 published
 1096 ms :   screen: received sensor-1 no. 4 : 22.5 °C
 1096 ms :   screen: threshold reached, unsubscribing
 1506 ms :   archive: received sensor-1 no. 3 : 21.75 °C
 1507 ms : publisher: measurement no. 5 published
 2008 ms :   archive: received sensor-1 no. 4 : 22.5 °C
 2008 ms : publisher: measurement no. 6 published
 2008 ms : publisher: end of publication
 2509 ms :   archive: received sensor-1 no. 5 : 23.25 °C
 3010 ms :   archive: received sensor-1 no. 6 : 24 °C
 3511 ms :   archive: end of the flow

说明:

  • 第 19 行:发布者,一个测量值的共享流。参数 [extraBufferCapacity = 2] 为它提供一个容纳 2 个值的缓冲区:发布者最多可以领先最慢的订阅者 2 个值。值的类型是 [Measurement?]:值 [null] 将用于标志发布的结束;
  • 第 21–27 行:屏幕是一个协程,它使用 [first] (程序 [Async23.kt])收集数据流,直到第一个至少为 22 °C 的读数:订阅随数据收集开始,随数据收集结束。这里没有 [onSubscribe],没有 [request(1)],也没有 [cancel()]:整个响应式数据流协议就是收集数据,然后停止;
  • 第 29–35 行:归档处理每个测量值需要 500 毫秒。在这段处理期间,数据收集不会继续:这就是调节吞吐量的方式,就像 Java 订阅者的 [request(1)] 一样;
  • 第 51 行:共享流永远不会结束:从中收集的订阅者会无限期地等待后续的值,直到其协程被取消。没有与 Java 发布者的 [close()] 方法等价的东西。要标志结束,就发出一个预定义的值——此处是 [null]。扩展函数 [untilTheEnd] 在这个值处停止收集([takeWhile]),并返回一个 [Flow<Measurement>]([filterNotNull] 改变值的类型,从 [Measurement?] 变为 [Measurement]);
  • 第 39 行:共享流不会为缺席的订阅者保留任何内容:在没有人订阅时发布的值会丢失(除非指示该流使用参数 [replay] 向新订阅者重放其中的几个值)。属性 [subscriptionCount] 是订阅者数量的流:我们等到它达到 2 才发布。如果没有这一预防措施,由 [launch] 启动的两个订阅者在第一次广播时还没有开始收集数据;
  • 第 40–47 行:发布者每 200 毫秒发布一个测量值。[emit] 是一个挂起函数:当最慢的订阅者的缓冲区已满时,它会等待有空位可用。5 号测量值在大约 1300 毫秒时准备就绪,直到 1507 毫秒才发布(结果第 14 行),此时归档已取走 3 号测量值。这就是背压:发布者被减慢到最慢订阅者的节奏;
  • 结果与 Java 程序的相同:屏幕在每个测量值发布后立即处理它,并在 4 号测量值处取消订阅(第 11–12 行),而每个测量值需要 500 毫秒的归档则落在后面,收到全部六个测量值,随后是流的结束(第 20 行)。当两个订阅者都完成时,程序终止:它们是 [runBlocking] 的子协程,后者会等待它们。

有一种特殊类型的共享流被广泛使用:状态流 ([MutableStateFlow<T>] / [StateFlow<T>])。它始终有一个值——当前值——可以通过其属性 [value] 读取和修改([state.value = "connected"]);它的订阅者在订阅时立即收到当前值,随后收到每一个新值(与前一个值相等的值不会被发出,慢速订阅者只会收到最新的值)。这是图形应用程序和 Android 应用程序用来表示屏幕状态的工具:业务逻辑修改状态,用户界面收集状态,每次变化时屏幕都会重绘。这是第 7 章讨论的可观察属性的异步等价物。

要点:

工具
用途
[Flow] (冷)
为消费者按需生成的值序列:文件中的行、查询结果、API 的页面
[Channel] (热)
协程之间的队列:每个值只被一个消费者接收(生产者/消费者、负载均衡)
[SharedFlow] (热)
广播:每个值被所有当前的订阅者接收(事件、消息)
[StateFlow] (热)
可观察状态:一个当前值及其变化

9.11. 缓存、回到正确的线程,以及自行完成操作

9.11.1. 异步操作的缓存

[Deferred] 和 [CompletableFuture] 一样是一个对象:每次调用返回它的函数,都会在堆上至少分配一个对象,垃圾回收器之后必须回收它。对于持续数毫秒的 I/O,这可以忽略不计。事实上,挂起函数相对于 [CompletableFuture] 对象有一个优势:已经拥有结果的挂起函数会直接返回它,而无需挂起协程,无需切换线程,也无需创建 [Deferred] 对象;同样,对已经完成的 [await()] 调用 [Deferred] 会返回其值而不挂起。这正是其他语言用“轻量级”类型实现的效果(例如 C# 中的 [ValueTask] 结构)。

当你希望对同一个值的多个并发请求共享同一个正在进行的操作时,最佳实践仍然是缓存 [Deferred] 对象本身:已知的值由一个已完成的 [Deferred] 返回,而正在计算的值由该计算对应的 [Deferred] 返回。[Async27.kt] 程序把这一做法应用到 Java 程序的汇率服务上:

// Deferred 的缓存:一个异步操作,大多数时候已经有了结果
package async27

import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.CoroutineStart
import kotlinx.coroutines.Deferred
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.async
import kotlinx.coroutines.cancel
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import java.math.BigDecimal
import java.text.NumberFormat
import java.util.concurrent.ConcurrentHashMap
import java.util.concurrent.atomic.AtomicInteger
import kotlin.time.measureTimedValue

fun main() = runBlocking<Unit> {
    RateService().use { service ->
        // 1 - 连续读取:只有第一次读取某种货币时才会查询服务器
        for (code in listOf("EUR", "USD", "EUR", "EUR", "USD", "GBP", "EUR")) {
            val (rate, duration) = measureTimedValue { service.readRate(code).await() }
            println("%s : %6s read in %3d ms".format(code, format(rate), duration.inWholeMilliseconds))
        }
        println("1 - server accesses: ${service.nbServerAccesses}, reads: ${service.nbReads}")

        // 2 - 对同一种货币的三个同时读取:它们共享同一个操作
        val reads = List(3) { service.readRate("CHF") }
        println("2 - same object: ${reads[0] === reads[2]}, rate: ${format(reads[0].await())}" +
                ", server accesses: ${service.nbServerAccesses}, reads: ${service.nbReads}")

        // 3 - 失败的操作不会保留在缓存中
        try {
            service.readRate("XYZ").await()
        } catch (e: IllegalArgumentException) {
            println("3 - ${e.message}, currencies in cache: ${service.currenciesInCache()}")
        }
    }
}

class RateService : AutoCloseable {
    // 读取的作用域:它属于服务,一个读取的失败不会取消其他读取
    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)

    // 缓存包含 Deferred 本身,无论已完成还是进行中
    private val cache = ConcurrentHashMap<String, Deferred<BigDecimal>>()
    private val serverAccesses = AtomicInteger()
    private val reads = AtomicInteger()
    val nbServerAccesses get() = serverAccesses.get()
    val nbReads get() = reads.get()

    fun readRate(code: String): Deferred<BigDecimal> {
        reads.incrementAndGet()
        // 如果货币在缓存中,则返回已有的 Deferred:不创建任何对象
        return cache.computeIfAbsent(code, ::readServerRate).also { it.start() }
    }

    // 惰性读取:只有在存入缓存后调用 start() 才会开始
    private fun readServerRate(code: String): Deferred<BigDecimal> =
        scope.async(start = CoroutineStart.LAZY) {
            serverAccesses.incrementAndGet()
            try {
                // 模拟查询远程服务器(300 毫秒)
                delay(300)
                when (code) {
                    "EUR" -> BigDecimal.ONE
                    "USD" -> BigDecimal("1.17")
                    "GBP" -> BigDecimal("0.87")
                    "CHF" -> BigDecimal("0.94")
                    else -> throw IllegalArgumentException("unknown currency: $code")
                }
            } catch (e: Exception) {
                // 失败时,该读取会从缓存中移除:之后的读取将会重试
                cache.remove(code)
                throw e
            }
        }

    fun currenciesInCache() = cache.keys.sorted()

    // 关闭服务会取消进行中的读取
    override fun close() = scope.cancel()
}

// 一个采用本机语言格式的实数,不带无用的小数
fun format(value: BigDecimal): String = NumberFormat.getInstance().format(value)

结果:

> gradlew -q run -Pmain=async27.Async27Kt
EUR :      1 read in 391 ms
USD :   1.17 read in 301 ms
EUR :      1 read in   0 ms
EUR :      1 read in   0 ms
USD :   1.17 read in   0 ms
GBP :   0.87 read in 300 ms
EUR :      1 read in   0 ms
1 - server accesses: 3, reads: 7
2 - same object: true, rate: 0.94, server accesses: 4, reads: 10
3 - unknown currency: XYZ, currencies in cache: [CHF, EUR, GBP, USD]

说明:

  • 第 44 行:服务启动的协程(读取操作)必须能够比请求它们的协程活得更久:由一个调用者请求的读取会与后续的调用者共享。因此,它们不能属于某个调用者的作用域;它们属于服务自己的作用域——一个组件作用域 (程序 [Async16.kt])。它的 [SupervisorJob] 确保一次读取的失败不会取消其他读取;它的调度器是 [Dispatchers.Default];
  • 第 83 行:服务实现了 [AutoCloseable];关闭它会取消作用域,从而取消所有正在进行的读取。主程序在 [use] 块中使用该服务(第 20 行):没有任何协程能比它存活更久;
  • 第 47 行:缓存把每个货币代码与其汇率的 [Deferred] 关联起来,不论它是已完成还是仍在进行中。这是一个 [ConcurrentHashMap] (第 8 章),因为它可能被多个线程同时使用(主线程,以及执行读取的 [Default] 调度器的线程);
  • 第 50–51 行:计数器是私有的 [AtomicInteger] 对象,通过两个只读属性向外公开,其访问器 [get()] 读取当前值(第 4 章);
  • 第 53–56 行:如果键存在,[computeIfAbsent(key, function)] 返回与该键关联的值;否则,它调用该函数(此处是引用 [::readServerRate]),把结果存入字典并返回。对于 [ConcurrentHashMap],这个操作是原子的:两个同时请求某个尚不存在的货币的协程只会触发一次服务器访问。[readRate] 不是挂起函数:它返回一个 [Deferred],调用者可以在任何时候用 [await()] 等待它;
  • 第 60–61 行:读取操作由 [async] 使用选项 [start = CoroutineStart.LAZY] 启动:协程被创建但不会开始;它将在第一次调用 [start()] 或 [await()] 时开始。[readRate] 通过 [.also { it.start() }] 启动它,这发生在 [computeIfAbsent] 把它存入缓存之后([start()] 对已经启动或已经结束的协程没有任何效果)。这一预防措施确保读取操作不可能在它被存入缓存之前就完成——或试图把自己从缓存中移除;它还避免了在 [computeIfAbsent] 函数内执行任何其他内容,该函数必须简短,因为它运行时字典对该键处于锁定状态;
  • 第 64–71 行:模拟的服务器查询(300 毫秒)。应用于字符串的 [when] 表达式返回汇率,或者对未知的货币抛出异常;
  • 第 73–76 行:如果失败,该操作会从缓存中移除,这样之后对同一货币的请求会再次查询服务器,而不是无限期地返回同一个失败。移除操作是在协程终止之前执行的:通过 [await()] 接收到异常的调用者会发现缓存已经是最新的(Java 程序用 [whenComplete] 实现了同样的保证)。异常会被重新抛出;如果它是 [CancellationException] (服务关闭),同样会被重新抛出,被取消的读取同样不会留在缓存中;
  • 第 21–26 行:对调用者而言,读取与任何其他异步操作一样:它用 [await()] 等待它。函数 [measureTimedValue] 同时返回代码块的结果及其持续时间,并通过解构赋值取出。结果显示了 3 次服务器访问(每次 300 毫秒;第一次稍长一些,其间 JVM 加载所需的类)和 4 次来自缓存的即时响应;
  • 第 28–31 行:对瑞士法郎汇率的三个同时请求获得同一个对象([===] 运算符比较引用),并且只导致一次服务器访问(结果第 10 行);
  • 第 33–37 行:[await()] 重新抛出读取异常,它被标准的 [catch] 捕获(Java 程序收到的是一个包装了原始异常的 [CompletionException] );未知的货币已不在缓存中(第 11 行)。[currenciesInCache] 函数返回排好序的字典键([sorted()])。

当每个值的计算相互独立时,[Deferred] 缓存是合适的。反之,当一次只允许一个协程执行某段挂起代码时,就使用协程锁——具体来说,就是 [Mutex] 类,它来自 [kotlinx.coroutines.sync] 包:[mutex.withLock { … }] 以互斥的方式执行代码块,而发现锁已被持有的协程会被挂起 ,且不阻塞其线程。一个简单的缓存可以用 [suspend fun readRate(code: String) = mutex.withLock { cache.getOrPut(code) { readServerRate(code) } }] 来实现,并配合一个由该锁保护的标准 [MutableMap]。它比 [Deferred] 缓存更简单,但它会导致所有读取——即使是针对不同货币的读取——在每次服务器访问期间都要等待。你不应该在挂起调用周围使用第 8 章中的锁([synchronized]、[ReentrantLock]):它们属于某个线程,而协程可能在获取锁的线程之外的另一个线程上恢复(事实上,在挂起调用周围使用 [synchronized] 会被编译器拒绝)。

9.11.2. 返回 GUI 线程

程序 [Async09.kt] 演示了决定由哪个线程执行协程的是调度器 ——因此也决定了挂起之后由哪个线程运行其余的代码。在 GUI 应用程序中,这一点很重要:GUI 组件只能由 GUI 线程操作。Java 要求程序自己在这个线程上恢复执行(Swing 使用 [SwingUtilities.invokeLater] ,JavaFX 使用 [Platform.runLater] ),而 kotlinx.coroutines 提供了一个专用的调度器 [Dispatchers.Main],它的协程在 UI 线程上运行:

  • 它由特定于图形库的附加模块提供:[kotlinx-coroutines-android] (Android)、[kotlinx-coroutines-javafx] (JavaFX)、[kotlinx-coroutines-swing] (Swing);没有这个模块,使用它会抛出异常:
java.lang.IllegalStateException: Module with the Main dispatcher is missing. Add dependency providing the Main dispatcher, e.g. 'kotlinx-coroutines-android' and ensure it has the same version as 'kotlinx-coroutines-core'
  • 界面代码在 [Dispatchers.Main] 上启动的协程中运行,并在执行耗时任务期间切换到另一个调度器:[val page = withContext(Dispatchers.IO) { download(address) }],然后 [textArea.text = page]。在 [withContext] 之后,协程自动回到了界面线程:无需请求任何东西。这就是 C# 的 [await] 在图形应用程序中所做的事情,它在界面线程上恢复方法的执行;
  • 在 Android 上,组件提供与其生命周期绑定的自有作用域(Activity 使用 [lifecycleScope] ,视图模型使用 [viewModelScope] ),其调度器是 [Dispatchers.Main]:当屏幕被销毁时,作用域被取消,它启动的所有协程也随之被取消。这就是应用于界面的结构化并发;
  • 流的收集者在收集协程的调度器(界面的线程)上运行,而 [flowOn] 让值在别处生成(程序 [Async24.kt])。在 [StateFlow] 上、于 [Dispatchers.Main] 收集,是显示不断变化的状态的标准方式。

规则与 Java 课程中相同:界面线程绝不能阻塞([runBlocking]、[Thread.sleep]、[join()] 一个 [CompletableFuture]、阻塞式 I/O),否则窗口会卡死。但它可以随意挂起 :来自 [Dispatchers.Main] 的协程在等待 [await()] 或 [delay] 时,会把线程归还给图形库,图形库继续处理事件。

9.11.3. 手动结束操作:CompletableDeferred

有时你可能需要使用一个通过监听器(第 7 章)发出事件信号的 API,而其余代码则使用协程编写。Kotlinx.coroutines 为此提供了两种工具:

  • 类 [CompletableDeferred<T>],相当于 [CompletableFuture],由你自己来完成它:这是一个“待定”的 [Deferred<T>],你立即提交它,随后在适当的时候用 [complete(value)] (成功)、[completeExceptionally(exception)] (失败)或 [cancel()] (取消)来完成它。与 [CompletableFuture] 一样,最先完成它的一方获胜:后续的调用没有任何效果([complete] 和 [completeExceptionally] 随后返回 [false]);
  • 函数 [suspendCancellableCoroutine],已在程序 [Async02.kt] 和 [Async21.kt] 中使用过,它把预期的事件转换为一个可取消的挂起函数。

程序 [Async28.kt] 重新实现了那个 Java 程序,它等待一个温度计——每次测量都会通知它的监听器——达到某个温度:

// 自己完成一个操作:CompletableDeferred,然后是 suspendCancellableCoroutine,
// 用来把基于监听器的 API 转换为异步操作
package async28

import kotlinx.coroutines.CompletableDeferred
import kotlinx.coroutines.Deferred
import kotlinx.coroutines.TimeoutCancellationException
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.suspendCancellableCoroutine
import kotlinx.coroutines.withTimeout
import kotlinx.coroutines.withTimeoutOrNull
import java.text.NumberFormat
import java.util.concurrent.CopyOnWriteArrayList
import java.util.concurrent.Executors
import java.util.concurrent.TimeUnit
import kotlin.coroutines.resume

val start = System.nanoTime()

fun main() = runBlocking {
    val thermometer = Thermometer()
    thermometer.start()

    // 1 - 我们等待第一个大于或等于 21 °C 的测量值
    val measurement = awaitTemperature(thermometer, 21.0).await()
    display("1 - temperature reached: ${format(measurement)} °C, listeners: ${thermometer.nbListeners}")

    // 2 - 同样的等待,限制为 600 毫秒:被放弃的是等待,而不是操作
    val waiting = awaitTemperature(thermometer, 30.0)
    val measurement2 = withTimeoutOrNull(600) { waiting.await() }
    display("2 - result: $measurement2, listeners: ${thermometer.nbListeners}")
    // 必须手动取消操作以移除监听器
    waiting.cancel()
    display("2 - after cancel(): listeners: ${thermometer.nbListeners}")

    // 3 - 一个可取消的挂起函数:超时会取消操作本身
    try {
        withTimeout(600) { temperatureReached(thermometer, 30.0) }
    } catch (e: TimeoutCancellationException) {
        display("3 - 30 °C not reached in 600 ms, listeners: ${thermometer.nbListeners}")
    }
    thermometer.stop()
}

// 将温度计的通知转换为一个我们自己来完成的 Deferred
fun awaitTemperature(thermometer: Thermometer, threshold: Double): Deferred<Double> {
    val result = CompletableDeferred<Double>()
    // 达到阈值时,监听器完成该 Deferred
    val listener = { temperature: Double ->
        if (temperature >= threshold) result.complete(temperature)
    }
    thermometer.addListener(listener)
    // 无论以何种方式结束(阈值、失败、取消),监听器都会被移除
    result.invokeOnCompletion { thermometer.removeListener(listener) }
    // Deferred 立即返回;它稍后才会完成
    return result
}

// 同样的事情,作为可取消的挂起函数
suspend fun temperatureReached(thermometer: Thermometer, threshold: Double): Double =
    suspendCancellableCoroutine { continuation ->
        lateinit var listener: (Double) -> Unit
        listener = { temperature ->
            if (temperature >= threshold && continuation.isActive) {
                thermometer.removeListener(listener)
                continuation.resume(temperature)
            }
        }
        thermometer.addListener(listener)
        // 如果协程在等待期间被取消,监听器会被移除
        continuation.invokeOnCancellation { thermometer.removeListener(listener) }
    }

// 一个每 200 毫秒通知其监听器的温度计("老式"API)
class Thermometer {
    private val listeners = CopyOnWriteArrayList<(Double) -> Unit>()
    private val timer = Executors.newSingleThreadScheduledExecutor()
    private var temperature = 19.0
    val nbListeners get() = listeners.size

    fun addListener(listener: (Double) -> Unit) = listeners.add(listener)

    fun removeListener(listener: (Double) -> Unit) = listeners.remove(listener)

    fun start() {
        timer.scheduleAtFixedRate({
            temperature += 0.5
            println("          measurement: ${format(temperature)} °C")
            listeners.forEach { listener -> listener(temperature) }
        }, 200, 200, TimeUnit.MILLISECONDS)
    }

    fun stop() = timer.shutdown()
}

// 一个采用本机语言格式的实数,不带无用的小数
fun format(value: Double): String = NumberFormat.getInstance().format(value)

// 显示,附带自开始以来经过的时间
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

结果:

> gradlew -q run -Pmain=async28.Async28Kt
          measurement: 19.5 °C
          measurement: 20 °C
          measurement: 20.5 °C
          measurement: 21 °C
  961 ms : 1 - temperature reached: 21 °C, listeners: 0
          measurement: 21.5 °C
          measurement: 22 °C
          measurement: 22.5 °C
 1571 ms : 2 - result: null, listeners: 1
 1578 ms : 2 - after cancel(): listeners: 0
          measurement: 23 °C
          measurement: 23.5 °C
          measurement: 24 °C
 2181 ms : 3 - 30 °C not reached in 600 ms, listeners: 0

说明:

  • 第 75–93 行:温度计,一个“老派的”类:[ScheduledExecutorService] 每 200 毫秒把温度升高 0.5 °C,并把它传给它的监听器,监听器的类型是 [(Double) -> Unit]。监听器列表是一个 [CopyOnWriteArrayList],这种列表可以在另一个线程遍历它的同时被一个线程修改(添加或移除监听器)。[nbListeners] 属性将用来验证监听器是否已被正确移除;
  • 第 46–56 行:把通知转换为 [Deferred] 的函数。它创建一个临时的 [CompletableDeferred<Double>],向温度计注册一个监听器,并立即返回尚未结束的 [CompletableDeferred] (被当作 [Deferred<Double>]:调用者自己无法终止它);
  • 第 49–50 行:每次测量时,监听器都会测试阈值。达到阈值时,它以温度作为结果终止 [CompletableDeferred] 。在监听器被移除之前,后续的测量仍会调用 [complete],但没有任何效果;
  • 第 54 行:不论 [Deferred] 如何结束(达到阈值、失败、取消),由 [invokeOnCompletion] 登记的动作都会移除监听器:这就是 Java 程序中的 [whenComplete] 。没有它,一个永远达不到阈值的监听器将一直保持注册状态;
  • 第 24–26 行:对调用者而言,等待温度与任何其他异步操作一样:它用 [await()] 等待它。一旦达到阈值,监听器就已被移除(结果第 6 行:0 个监听器);
  • 第 28–34 行:与 Java 程序有显著区别,在 Java 程序中,[orTimeout] 自己终止 [CompletableFuture] 。在这里,[withTimeoutOrNull] 取消的是等待代码块([await()]),而不是被等待的 [Deferred]:600 毫秒后,等待被放弃([null]),但操作仍在继续,它的监听器仍处于注册状态(结果第 10 行:1 个监听器)。[CompletableDeferred] 不是任何协程的子协程:结构化并发不适用于它,要由它的创建者使用 [cancel()] 来取消它,这会移除监听器(第 11 行);
  • 第 60–71 行:同样的等待,使用 [suspendCancellableCoroutine] 写成一个挂起函数。监听器在移除自身之后,用温度恢复协程([resume])。由于它必须引用自身,因此在初始化之前用 [lateinit var] 声明它:lambda 不能引用正在被赋值的变量。测试 [continuation.isActive] 防止续体被恢复两次(那会触发 [IllegalStateException])。[invokeOnCancellation] 登记协程在等待期间被取消时要执行的动作:移除监听器;
  • 第 36–40 行:这一次,[withTimeout] 取消在 [temperatureReached] 中挂起的协程:动作 [invokeOnCancellation] 移除监听器,不需要再做任何事(第 15 行:0 个监听器)。

因此我们更倾向于第二种形式:用 挂起函数 构建、借助 [suspendCancellableCoroutine] 的方式会参与取消和结构化并发,而 [CompletableDeferred] 是一个独立的对象,其创建者必须记得在所有情况下都终止它。[CompletableDeferred] 对于多个协程期待的值(例如启动信号),或者对于一个协程提供给另一个协程的结果,仍然很有用。有一点需要注意,与 Java 中相同:监听器由温度计的线程执行,处于对其监听器发送通知的过程中;它必须保持简短。这里就是如此:[complete] 和 [resume] 只是把协程的恢复委托给它的调度器(主线程,即 [runBlocking] 的线程)。

9.12. 受限并行

9.12.1. 信号量与 limitedParallelism

[awaitAll] 加上每个操作一个协程,会同时启动所有操作。这并不总是我们想要的:要下载 10000 个网页,你不会想向同一台服务器同时打开 10000 个连接。与虚拟线程一样,协程不做池化(它们非常廉价,每个任务启动一个):要限制的是对稀缺资源的访问。Kotlinx.coroutines 为此提供了两种工具:

  • 协程信号量,即来自 [Semaphore] 类,位于 [kotlinx.coroutines.sync] 包(不要与第 8 章介绍的 [java.util.concurrent] 中的那个混淆):它的许可数代表允许的并发操作数;等待许可的协程会被挂起,而不阻塞任何线程;
  • 调度器的受限视图 ,即 [dispatcher.limitedParallelism(n)],已在程序 [Async09.kt] 中登记:这是一个使用原调度器线程的调度器,但同时使用的线程永远不超过 [n] 个。

程序 [Async29.kt] 沿用了那个下载九个页面(一次不超过三个)的 Java 程序,然后比较这两种工具:

// 以有限数量的同时操作处理一个集合:
// kotlinx.coroutines 的 Semaphore,然后是 limitedParallelism
package async29

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.sync.Semaphore
import kotlinx.coroutines.sync.withPermit
import java.util.concurrent.atomic.AtomicInteger
import kotlin.time.measureTime

val pages = (1..9).map { "page$it.html" }
val inProgress = AtomicInteger()
val maximum = AtomicInteger()
var start = System.nanoTime()

fun main() = runBlocking {
    // 1 - 同一时间最多 3 个下载:一个有 3 个许可的协程信号量
    start = System.nanoTime()
    val permits = Semaphore(3)
    coroutineScope {
        // 每页一个协程:它们很廉价,有多少页就可以启动多少个
        for (page in pages) {
            launch {
                // 协程等待一个许可(它被挂起,而不阻塞线程)
                permits.withPermit { download(page, trace = true) }
            }
        }
    }
    display("1 - the ${pages.size} pages are downloaded")

    // 2 - 在限制为 3 个线程的 IO 调度器视图上进行阻塞下载
    val threeThreads = Dispatchers.IO.limitedParallelism(3)
    maximum.set(0)
    val duration2 = measureTime {
        coroutineScope {
            for (page in pages) launch(threeThreads) { downloadBlocking(page) }
        }
    }
    println("2 - limitedParallelism(3), blocking: ${duration2.inWholeMilliseconds} ms, " +
            "at most ${maximum.get()} in progress")

    // 3 - 同一个视图限制的是线程,而不是被挂起的协程:这里没有限制
    maximum.set(0)
    val duration3 = measureTime {
        coroutineScope {
            for (page in pages) launch(threeThreads) { download(page) }
        }
    }
    println("3 - limitedParallelism(3), suspended: ${duration3.inWholeMilliseconds} ms, " +
            "at most ${maximum.get()} in progress")
}

// 由挂起函数模拟的页面下载
suspend fun download(page: String, trace: Boolean = false) {
    // 同时进行的操作共享的计数器:它被原子地修改
    val n = inProgress.incrementAndGet()
    maximum.accumulateAndGet(n, ::maxOf)
    if (trace) display("start of $page ($n in progress)")
    delay(1000)
    inProgress.decrementAndGet()
    if (trace) display("end of $page")
}

// 同样的下载,由阻塞函数完成
fun downloadBlocking(page: String) {
    val n = inProgress.incrementAndGet()
    maximum.accumulateAndGet(n, ::maxOf)
    Thread.sleep(1000)
    inProgress.decrementAndGet()
}

// 显示,附带自 [start] 以来经过的时间
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

结果:

> gradlew -q run -Pmain=async29.Async29Kt
   39 ms : start of page1.html (1 in progress)
   76 ms : start of page2.html (2 in progress)
   76 ms : start of page3.html (3 in progress)
 1118 ms : end of page1.html
 1122 ms : end of page2.html
 1122 ms : end of page3.html
 1122 ms : start of page4.html (1 in progress)
 1122 ms : start of page5.html (2 in progress)
 1122 ms : start of page6.html (3 in progress)
 2125 ms : end of page4.html
 2126 ms : end of page5.html
 2127 ms : end of page6.html
 2127 ms : start of page7.html (1 in progress)
 2127 ms : start of page8.html (2 in progress)
 2128 ms : start of page9.html (3 in progress)
 3135 ms : end of page7.html
 3142 ms : end of page8.html
 3143 ms : end of page9.html
 3151 ms : 1 - the 9 pages are downloaded
2 - limitedParallelism(3), blocking: 3025 ms, at most 3 in progress
3 - limitedParallelism(3), suspended: 1006 ms, at most 9 in progress

说明:

  • 第 23 行:一个有 3 个许可的协程信号量;
  • 第 24–33 行:每个页面一个协程。[coroutineScope] 块等待所有九个协程结束,类似于 Java 程序中执行器的 [close()] 方法;
  • 第 29 行:每个协程等待一个许可,下载它的页面,然后归还许可。函数 [withPermit] 完成了所有这些:它获取一个许可([acquire()],一个挂起函数),执行代码块,并在 [release()] 的 [finally] 中归还许可,这样即使代码块失败或协程被取消,许可也会被归还。Java 程序必须自己编写 [try / finally],并处理 [InterruptedException] (来自 [acquire]);
  • 第 58–65 行:模拟页面下载,一个等待一秒的挂起函数。由协程共享的 [inProgress] 计数器是一个 [AtomicInteger]:由 [runBlocking] 启动的协程在这里运行在单个线程上,但第 2 和第 3 部分中的协程则运行在多个线程上。计数器 [maximum] 记录并发下载数的最大值:[accumulateAndGet(n, ::maxOf)] 以原子方式用它自身的值与 [n] 中较大的那个替换它(标准库函数 [maxOf],以引用方式传递);
  • 第 1 部分的结果显示了三批、每批三个页面:一个页面一结束,另一个页面就开始,活动下载的数量从不超过 3。整个过程耗时 3 秒,而不是 9 秒。这九个协程由单个线程执行,即 [runBlocking] 的线程;
  • 第 35–43 行:[Dispatchers.IO.limitedParallelism(3)] 是 [IO] 调度器的一个限制为 3 个线程的视图。九个协程在这个视图上启动,并执行一次阻塞下载([Thread.sleep]):同一时间只有三个能运行;其他的要等待有线程可用。整个过程耗时 3 秒,最多同时进行 3 个下载(结果第 21 行)。这是限制阻塞任务(JDBC 库、文件)或计算的合适工具:由 [Dispatchers.IO] 通过 [limitedParallelism] 生成的视图甚至可以超过 [Dispatchers.IO] 的 64 线程上限,这使得可以为每个阻塞资源分配它自己的线程配额(例如,与数据库连接池中的连接数一样多);
  • 第 46–53 行:同样的视图,但下载被暂停 ([delay])。这一次,所有九个下载同时进行,整个过程耗时一秒(第 22 行)。[limitedParallelism] 限制同一时间运行的协程数量——也就是被占用的线程数;被挂起的协程不占用线程,也不计入。因此,要限制进行中的操作数量(连接、查询),就必须使用信号量。

要点:limitedParallelism 限制线程;信号量限制操作。

9.12.2. 生产者/消费者:读取通道的工作者

上一章使用 [BlockingQueue] 介绍了生产者/消费者模型,Java 课程使用虚拟线程实现了它。使用协程时,工具是通道:[send] 取代 [put],通道上的 [for] 循环取代连续的 [take] 调用,[trySend] 取代 [offer] (非阻塞的尝试)。多个读取同一个通道的协程共享它的值:这是限制并行度的另一种方式,即启动固定数量的“工作者”,让它们依次处理任务。程序 [Async30.kt] 有每 50 毫秒生成一个的订单,由两个消费者处理,每个消费者处理一个订单需要 400 毫秒:

// 生产者 / 消费者:"工作者"协程共享一个通道中的订单
package async30

import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.channels.ReceiveChannel
import kotlinx.coroutines.channels.SendChannel
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

val start = System.nanoTime()

fun main() = runBlocking {
    // 一个有界通道:它最多包含 2 个等待处理的订单
    val orders = Channel<Int>(capacity = 2)
    coroutineScope {
        // 生产者和两个消费者同时工作
        launch { produceOrders(orders, 8) }
        launchWorkers(orders, "C1", "C2")
    }
    display("all the orders have been processed")
}

// 生产者:每 50 毫秒一个订单
suspend fun produceOrders(orders: SendChannel<Int>, nbOrders: Int) {
    for (i in 1..nbOrders) {
        delay(50)
        // 如果通道中有空位,trySend 会立即放入订单
        if (orders.trySend(i).isSuccess) {
            display("P  : order $i put")
        } else {
            // 通道已满:send 挂起生产者,直到有空位
            display("P  : channel full, order $i waits")
            orders.send(i)
            display("P  : order $i put")
        }
    }
    // 不会再产生任何东西:通道被关闭
    orders.close()
    display("P  : end of production")
}

// 每个名称启动一个工作者:每个工作者接收通道中的订单,直到通道关闭
fun CoroutineScope.launchWorkers(orders: ReceiveChannel<Int>, vararg names: String) {
    for (name in names) {
        launch {
            // 处理一个订单需要 400 毫秒
            for (order in orders) {
                display("$name : processing order $order")
                delay(400)
            }
            display("$name : no more orders")
        }
    }
}

// 显示,附带自开始以来经过的时间
fun display(message: String) =
    println("%5d ms : %s".format((System.nanoTime() - start) / 1_000_000, message))

结果:

> gradlew -q run -Pmain=async30.Async30Kt
  195 ms : P  : order 1 put
  225 ms : C1 : processing order 1
  271 ms : P  : order 2 put
  271 ms : C2 : processing order 2
  322 ms : P  : order 3 put
  373 ms : P  : order 4 put
  423 ms : P  : channel full, order 5 waits
  625 ms : C1 : processing order 3
  626 ms : P  : order 5 put
  672 ms : C2 : processing order 4
  676 ms : P  : order 6 put
  727 ms : P  : channel full, order 7 waits
 1026 ms : C1 : processing order 5
 1026 ms : P  : order 7 put
 1073 ms : C2 : processing order 6
 1077 ms : P  : order 8 put
 1079 ms : P  : end of production
 1427 ms : C1 : processing order 7
 1473 ms : C2 : processing order 8
 1833 ms : C1 : no more orders
 1874 ms : C2 : no more orders
 1875 ms : all the orders have been processed

说明:

  • 第 17 行:一个容量为 2 的通道:它最多包含 2 个待处理的订单;
  • 第 18–21 行:生产者和两个消费者是 [coroutineScope] 块的三个子协程,该块等待这三个协程全部结束;
  • 第 27–42 行:生产者以 [SendChannel<Int>] 的形式接收通道,即通道的“发送”部分:它只能发送。它尝试用 [trySend] 存入每个订单,该函数从不挂起,并返回一个 [ChannelResult] ,其 [isSuccess] 属性指示值是否已存入。如果通道已满,它会发出提示,并使用 [send] 等待空位:生产者被限速以匹配消费者的节奏(结果第 8–10 行)。这就是有界通道的好处:过快的生产者无法填满内存;
  • 第 41 行:生产完成;生产者关闭通道。Java 程序必须放入一个特定的值——结束标记——每个消费者识别出它,并把它放回队列交给下一个消费者;而通道则知道自己何时被关闭。关闭通道不需要通道中有空位:在最后一个订单放入之后(第 18 行),生产结束的信号立即发出,而在 Java 中,放入结束标记必须等待一个空闲的位置;
  • 第 46–54 行:消费者由 [CoroutineScope] 的一个扩展函数启动(程序 [Async25.kt]),其参数 [vararg names] (第 3 章)接受任意数量的名称。每个工作者使用 [for] 循环遍历通道,该循环在通道关闭且为空时结束。一个订单只会交给一个工作者:订单根据 C1 和 C2 的空闲情况在它们之间分配;
  • 几乎同时显示的两行,其出现顺序在每次运行之间可能不同。

要用 [n] 个工作者处理一个事先已知的列表,我们把元素发送到一个通道中,关闭它,并启动 [n] 个协程从中读取:与为每个元素启动一个协程的信号量不同,这种方式只启动 [n] 个协程,这在处理数百万个元素时会有很大差别。

9.13. 时间

说到协程中的时间,首先要考虑的函数是 [delay]:一种不阻塞线程、可以取消的等待,接受毫秒数或持续时间([Duration]:[delay(500.milliseconds)])。函数 [withTimeout] 和 [withTimeoutOrNull] (程序 [Async19.kt])限制代码块的持续时间。有了这两个工具,编写定时器就很简单了:一个循环的协程,在两次动作之间等待,并通过取消它来停止。Java 课程为此使用了 [ScheduledExecutorService];程序 [Async31.kt] 使用协程实现了这两种周期性定时器,然后复用 Java 程序中依赖于时间的 [Reception] 类:

// 时间:用 delay 编写的定时器,以及注入的时钟(Clock)
package async31

import kotlinx.coroutines.cancelAndJoin
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import java.time.Clock
import java.time.Instant
import java.time.LocalDateTime
import java.time.ZoneOffset
import java.time.format.DateTimeFormatter
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.TimeSource

fun main() = runBlocking {
    // 1 - 每 500 毫秒一个操作:一个操作结束和下一个操作开始之间的固定延迟
    var start = TimeSource.Monotonic.markNow()
    var nbTicks = 0
    val ticks = launch {
        while (true) {
            delay(500)
            nbTicks++
            println("%6d ms : tick no. %d".format(start.elapsedNow().inWholeMilliseconds, nbTicks))
            // 操作本身持续 100 毫秒
            delay(100)
        }
    }
    // 一个在 2.2 秒后执行的单次操作,它会停止滴答
    delay(2200)
    ticks.cancelAndJoin()
    println("%6d ms : 1 - timer stopped after %d ticks"
        .format(start.elapsedNow().inWholeMilliseconds, nbTicks))

    // 2 - 固定间隔:尽管操作有耗时,每个滴答都对齐到计划的时刻
    start = TimeSource.Monotonic.markNow()
    nbTicks = 0
    val ticks2 = launch {
        var next = start + 500.milliseconds
        while (true) {
            // 我们等待到计划时刻之前剩余的时间(如果已经过了则不等待)
            delay(-next.elapsedNow())
            nbTicks++
            println("%6d ms : tick no. %d".format(start.elapsedNow().inWholeMilliseconds, nbTicks))
            delay(100)
            next += 500.milliseconds
        }
    }
    delay(2200)
    ticks2.cancelAndJoin()
    println("%6d ms : 2 - timer stopped after %d ticks"
        .format(start.elapsedNow().inWholeMilliseconds, nbTicks))

    // 3 - Clock:依赖时间的类接收它的时钟,而不是调用 LocalDateTime.now()
    val morning = Clock.fixed(Instant.parse("2026-10-03T09:30:00Z"), ZoneOffset.UTC)
    val evening = Clock.fixed(Instant.parse("2026-10-03T19:45:00Z"), ZoneOffset.UTC)
    println(Reception(morning).greet("Pierre"))
    println(Reception(evening).greet("Pierre"))
    println("${Reception(Clock.systemDefaultZone()).greet("Pierre")} (system clock)")
}

// 一个依赖当前时间的类
class Reception(private val clock: Clock) {
    fun greet(name: String): String {
        val now = LocalDateTime.now(clock)
        val greeting = if (now.hour < 18) "Hello" else "Good evening"
        val date = now.format(DateTimeFormatter.ofPattern("dd/MM/yyyy HH:mm"))
        return "[$date] $greeting $name"
    }
}

结果:

> gradlew -q run -Pmain=async31.Async31Kt
   511 ms : tick no. 1
  1145 ms : tick no. 2
  1746 ms : tick no. 3
  2229 ms : 1 - timer stopped after 3 ticks
   501 ms : tick no. 1
  1000 ms : tick no. 2
  1500 ms : tick no. 3
  2001 ms : tick no. 4
  2201 ms : 2 - timer stopped after 4 ticks
[03/10/2026 09:30] Hello Pierre
[03/10/2026 19:45] Good evening Pierre
[04/10/2026 13:03] Hello Pierre (system clock)

说明:

  • 第 18 行:为了测量持续时间,这里我们使用 Kotlin 标准库的单调计时器:[TimeSource.Monotonic.markNow()] 返回当前时刻的时间戳,而 [start.elapsedNow()] 返回自那时起经过的持续时间([Duration])。这相当于我们迄今为止一直使用的 [System.nanoTime()],只不过使用的是带类型的持续时间;
  • 第 20–31 行:每 500 毫秒执行一次的动作,由一个无限循环的协程([while (true)])执行。这个循环没有风险:每个 [delay] 都是一个取消点。2.2 秒后,主协程取消它并等待它结束([cancelAndJoin()])。变量 [nbTicks] 是一个简单的局部变量([var]),由 [launch] 中的 lambda 修改:Kotlin 允许闭包修改被捕获的变量(第 7 章),而 Java 则需要 [AtomicInteger];这里是安全的,因为所有协程都运行在 [runBlocking] 的单个线程上;
  • 第一个定时器在每个动作之后等待 500 毫秒,而动作本身持续 100 毫秒:定时器每 600 毫秒触发一次(结果第 2–4 行;第一个间隔稍长,因为此时正在加载类)。这就是 [scheduleWithFixedDelay] 方法的行为,该方法属于 [ScheduledExecutorService]:在一次执行结束与下一次执行开始之间有固定的延迟;
  • 第 38–46 行:第二个定时器设置为固定的间隔:500、1000、1500、2000 毫秒(第 6–9 行),与动作的持续时间无关。变量 [next] 是下一次触发的时间戳([start + 500.milliseconds]:时间戳加上持续时间等于时间戳)。只要这个时间还在未来,[next.elapsedNow()] 就是负数:因此 [delay(-next.elapsedNow())] 会等待剩余的时间(负数或零的延迟不会引起等待)。这就是 [scheduleAtFixedRate] 的行为。Kotlinx.coroutines 没有稳定的内置定时器函数([ticker] 函数被标记为已过时):推荐的做法是使用循环;
  • 第 63–68 行:[Reception] 类根据时间说“Hello”或“Good evening”。它在构造函数中接收它的时钟,一个 [java.time.Clock],而不是调用 [LocalDateTime.now()]:这是一个被注入的依赖,就像第 6 章中 [dao] 层被注入到 [business] 层中一样。[now.hour] 是对 Java 方法 [getHour()] 的调用,被当作属性处理;
  • 第 55–59 行:[Clock.fixed(instant, zone)] 返回一个停止的时钟,它总是返回同一个时间:这使我们能够验证[Reception] 在早晨和晚上的行为,而不必等到晚上。最后一行使用系统时钟:因此结果取决于执行时间。

顺便一提,Java 课程中的 [ScheduledExecutorService] 仍然可以在 Kotlin 中使用(程序 [Async28.kt] 中的温度计就使用了一个),但它的任务是由它们自己的线程执行的 [Runnable],位于任何协程之外。在基于协程的程序中,最好使用协程和 [delay],它们会随其作用域一起终止。

协程的计时函数还有另一个优势,对测试尤其重要:[kotlinx-coroutines-test] 模块提供了一个函数 [runTest],它使用虚拟时间来执行协程:[delay] 函数并不真的等待;虚拟时钟瞬间前进,模拟一分钟等待的测试只需几毫秒。

9.14. 协程与虚拟线程

Java 课程在本章的结尾概述了结构化并发,它把一组子任务视为一个整体:它们在一个作用域内启动,作用域等待它们结束,如果其中一个失败,其他的会被中止。在 Kotlin 中,这不只是一个概述——它是协程的根本基础,在本章开头就已介绍([coroutineScope]、[supervisorScope],程序 [Async11.kt]),并且此后在所有示例中都被使用。比较这两种语言很有意思,因为 Java 正朝着同一个方向前进。

9.14.1. StructuredTaskScope(Java)与 coroutineScope(Kotlin)

Java 类 [StructuredTaskScope] 使用虚拟线程实现结构化并发。它自 Java 21 起可用,但在 Java 25 中仍处于“预览”状态:它的 API 仍可能改变,使用它的程序必须带 [--enable-preview] 选项编译和运行。下面是 Java 课程中给出的代码(位于 Java 课程 [09-async] 文件夹中的文件 [preview/StructuredConcurrency.txt]):

// 结构化并发:Java 25 中的预览 API
// 执行:java --enable-preview StructuredConcurrency.java
import java.util.concurrent.StructuredTaskScope.Joiner;
import java.util.concurrent.StructuredTaskScope.Subtask;

void main() throws InterruptedException {
    // 1 - 两个必须都成功的子任务
    try (var scope = StructuredTaskScope.open()) {
        Subtask<Integer> angers = scope.fork(() -> readTemperature("Angers", 1000));
        Subtask<Integer> brest = scope.fork(() -> readTemperature("Brest", 500));
        // join 等待子任务结束;如果其中一个失败,另一个被取消
        // 并且 join 抛出异常
        scope.join();
        IO.println("Angers: " + angers.get() + ", Brest: " + brest.get());
    }
    // 2 - 第一个答案就够了:其他子任务被取消
    try (var scope = StructuredTaskScope.open(Joiner.<Integer>anySuccessfulResultOrThrow())) {
        scope.fork(() -> readTemperature("mirror-paris", 800));
        scope.fork(() -> readTemperature("mirror-lyon", 300));
        IO.println("first answer: " + scope.join());
    }
}

int readTemperature(String city, long duration) throws InterruptedException {
    Thread.sleep(duration);
    return 10 + city.length();
}

结果(使用 JDK 25 运行):

1
2
3
> java --enable-preview StructuredConcurrency.java
Angers: 16, Brest: 15
first answer: 21

[StructuredTaskScope.open()] 打开一个在 [try] 带资源语句中声明的作用域;[fork] 在一个新的虚拟线程中启动一个子任务;[join()] 等待所有子任务结束,如果其中任何一个失败,就终止其他子任务并抛出异常;[Joiner] 可以选择不同的策略,例如“第一个成功的子任务返回结果”。程序 [Async32.kt] 用协程做同样的事情,然后演示协程也可以处理由虚拟线程执行的阻塞代码:

// Kotlin 的结构化并发与 StructuredTaskScope(Java)的比较:
// 同样的子任务,先作为协程,然后作为虚拟线程上的阻塞代码
package async32

import kotlinx.coroutines.async
import kotlinx.coroutines.asCoroutineDispatcher
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.runInterruptible
import kotlinx.coroutines.selects.select
import java.util.concurrent.Executors
import kotlin.time.TimeSource

var start = TimeSource.Monotonic.markNow()

fun main() = runBlocking<Unit> {
    start = TimeSource.Monotonic.markNow()
    // 1 - 两个必须都成功的子任务
    val (angers, brest) = coroutineScope {
        val angers = async { readTemperature("Angers", 1000) }
        val brest = async { readTemperature("Brest", 500) }
        angers.await() to brest.await()
    }
    display("1 - Angers: $angers, Brest: $brest")

    // 2 - 第一个答案就够了:其他子任务被取消
    val first = coroutineScope {
        val mirrors = listOf(
            async { readTemperature("mirror-paris", 800) },
            async { readTemperature("mirror-lyon", 300) })
        select { mirrors.forEach { mirror -> mirror.onAwait { it } } }
            .also { mirrors.forEach { it.cancel() } }
    }
    display("2 - first answer: $first")

    // 3 - 虚拟线程上的阻塞代码:一个子任务的失败会中断另一个
    Executors.newVirtualThreadPerTaskExecutor().asCoroutineDispatcher().use { virtuals ->
        try {
            coroutineScope {
                async(virtuals) { runInterruptible { readTemperatureBlocking("Colmar", 1000) } }
                async(virtuals) { runInterruptible { readTemperatureBlocking("", 200) } }
            }
        } catch (e: IllegalArgumentException) {
            display("3 - failure: ${e.message}")
        }
    }
}

// 一个会挂起协程的读取
suspend fun readTemperature(city: String, duration: Long): Int {
    delay(duration)
    return 10 + city.length
}

// 一个阻塞读取,它会显示自己被中断
fun readTemperatureBlocking(city: String, duration: Long): Int {
    try {
        Thread.sleep(duration)
    } catch (e: InterruptedException) {
        display("    $city: read interrupted, by ${Thread.currentThread()}")
        throw e
    }
    require(city.isNotEmpty()) { "unknown city" }
    return 10 + city.length
}

// 显示,附带自 [start] 以来经过的时间
fun display(message: String) = println("%5d ms : %s".format(start.elapsedNow().inWholeMilliseconds, message))

结果:

1
2
3
4
5
> gradlew -q run -Pmain=async32.Async32Kt
 1023 ms : 1 - Angers: 16, Brest: 15
 1403 ms : 2 - first answer: 21
 1625 ms :     Colmar: read interrupted, by VirtualThread[#22]/runnable@ForkJoinPool-1-worker-2
 1628 ms : 3 - failure: unknown city

说明:

  • 第 19–23 行:[coroutineScope] 块的作用相当于 Java 的作用域:由 [async] 启动的两个子任务是它的子协程;在它们结束之前它不会结束,如果其中一个失败,另一个会被中止,并重新抛出该异常。该代码块返回一个二元组([to],第 3 章),并通过解构赋值解包。整体的持续时间就是最长的子任务的持续时间,即一秒(结果第 2 行)。这里没有 [try] 带资源语句,也没有 [join()] 或 [Subtask.get()]:作用域就是一个代码块,子任务的结果就是 [await()] 的结果;
  • 第 27–33 行:“第一个响应就足够”的策略使用 [select] (程序 [Async13.kt])实现,它等待第一个完成的子任务,然后取消所有其他子任务(取消一个已完成的协程没有任何效果)。如果没有这些取消操作,[coroutineScope] 块就会等待巴黎镜像站结束。响应在 300 毫秒后到达(第 3 行);
  • 第 37–45 行:这一次,子任务在一个线程为虚拟线程的调度器上执行阻塞代码([Thread.sleep])(程序 [Async09.kt])。函数 [runInterruptible] (程序 [Async19.kt])把协程的取消转换为对执行阻塞代码的线程的中断 。第二个子任务在 200 毫秒后失败([require] 抛出 [IllegalArgumentException]);作用域随后取消第一个子任务,[runInterruptible] 中断它的虚拟线程,其 [Thread.sleep] 抛出 [InterruptedException](输出第 4 行:显示该消息的线程是一个 [VirtualThread],挂载在 [ForkJoinPool] 的一个载体线程上)。随后原始异常从 [coroutineScope] 抛出(第 5 行)。这正是 [StructuredTaskScope] 的行为:Kotlin 的结构化并发同样适用于阻塞代码;
  • 虚拟线程调度器在代码块结束时由 [use] 关闭,这会停止它的执行器。

9.14.2. 什么时候该选择哪一种?

虚拟线程和协程解决的是同一个问题:以顺序且易读的方式编写大量等待(I/O)的代码,且在等待时不阻塞系统线程。它们以两种相反的方式做到这一点:

 
虚拟线程(Java 21)
协程(Kotlin)
机制位于何处
在 JVM 中:虚拟线程的栈在等待期间被复制到堆中
在编译器和库中:[suspend] 函数被转换为状态机
挂起的对象
JDK 中任何阻塞操作([Thread.sleep]、套接字、[BlockingQueue]、锁)
只有挂起函数([delay]、[await]、[send]……);阻塞代码必须由 [IO] 调度器来处理
现有代码
无需改动:任何阻塞式库(JDBC、HTTP 客户端)都能不加修改地从中受益
需要 API 的 [suspend] 版本,或者适配器([await()]、[withContext(Dispatchers.IO)])
代码中的标记
无:阻塞方法看起来与其他任何方法一样
关键字 [suspend] 标识可能等待的函数(这些被称为“有色函数”)
结构化并发
[StructuredTaskScope],在 Java 25 中仍处于预览阶段
[coroutineScope]、[supervisorScope]、[Job]:自 2018 年起稳定,是该模型的核心
取消
线程中断([Thread.interrupt]),每个库以各自的方式对其作出反应
协作式取消,沿协程树传播,使用 [CancellationException]、[withTimeout]、[NonCancellable]
值流、通道
阻塞式 [Stream]、[BlockingQueue]、[java.util.concurrent.Flow]
[Flow]、[Channel]、[SharedFlow]、[StateFlow],以及它们的运算符
线程选择
无:虚拟线程可以在任何载体线程上运行
调度器([Main]、[Default]、[IO]、[limitedParallelism])
平台
JVM(21 及更高版本)
JVM、Android(所有版本)、JavaScript、原生(Kotlin Multiplatform)
挂起任务的开销
几百字节到几 KB(被复制的栈)
几十到几百字节(续体对象)

这不是在二者之间择一的问题:它们可以结合使用,如程序 [Async32.kt] 的第 3 部分所示。以下是几个参考要点:

  • 对于编排异步操作(启动、等待、组合、限制、取消和广播值)的 Kotlin 程序,协程 是自然的选择:它们提供结构化并发、取消、流和调度器——这些是仅靠虚拟线程无法(或尚无法)提供的特性;
  • 对于无法重写的阻塞代码(JDBC 驱动程序,执行阻塞式 I/O 的 Java 库),虚拟线程 可以避免耗尽 [IO] 调度器的 64 个线程:把它们用作调度器([Executors.newVirtualThreadPerTaskExecutor().asCoroutineDispatcher()]),或者直接用在由虚拟线程处理每个请求的服务器中(Spring Boot 可以做到这一点);
  • 在 Android 上,或者对于 Kotlin Multiplatform 代码,只有协程可用;
  • 调用 Kotlin 代码的 Java 代码不能直接调用挂起函数:而是为它提供一个返回 [CompletableFuture] 的普通函数(使用程序 [future { … }] 中来自 [Async04.kt] 的函数),或者一个阻塞函数(使用 [runBlocking]),由 Java 在虚拟线程中调用。

9.15. 应用:使用协程计算税款

程序 [Async33.kt] 汇集了本章中与主线中所讲的税款计算相关的若干工具。与 Java 程序一样,它是独立的(不使用第 6 章第 5 版中的各层):它从已经使用过的文件 [TaxData.txt] 中读取税率档,并从同样位于项目根目录的文件 [taxpayers.txt] 中读取纳税人列表:

1
2
3
4
5
6
7
y 2 60000
y 3 60000
n 0 60000
n 2 25000
y 5 120000
x 1 20000
y 1 -5

(每一行包含:已婚 [y/n]、子女数、年薪),为每位纳税人计算税款,并把结果写入文件 [results.txt]。两次读取由两个协程同时执行,整个处理限制在 10 秒内。随后程序计算一百万名虚构纳税人的税款,先是顺序计算,然后是并行计算:

// 应用:使用协程的税款计算
// - 税率档从 [TaxData.txt](或作为参数传入的文件)读取,纳税人
//   从 [taxpayers.txt] 读取:两个读取同时进行,在 IO 调度器上
// - 结果写入 [results.txt]
// - 然后在 Default 调度器上并行计算大量纳税人的税款
package async33

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.TimeoutCancellationException
import kotlinx.coroutines.async
import kotlinx.coroutines.awaitAll
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withContext
import kotlinx.coroutines.withTimeout
import java.io.IOException
import java.math.BigDecimal
import java.math.MathContext
import java.nio.file.Path
import kotlin.io.path.bufferedWriter
import kotlin.io.path.readLines
import kotlin.io.path.readText
import kotlin.io.path.useLines
import kotlin.random.Random
import kotlin.time.Duration.Companion.seconds
import kotlin.time.measureTimedValue

// 一行正确的纳税人数据:已婚(y/n)、子女数、年薪
val TAXPAYER = Regex("""([yn])\s+(\d+)\s+(\d+)""")

fun main(args: Array<String>) = runBlocking<Unit> {
    val results = Path.of("results.txt")
    val brackets = Path.of(args.getOrElse(0) { "TaxData.txt" })
    try {
        // 1 - 整个处理限制在 10 秒内
        val nbResults = withTimeout(10.seconds) {
            process(brackets, Path.of("taxpayers.txt"), results)
        }
        println("$nbResults lines written to [$results]:")
        print(withContext(Dispatchers.IO) { results.readText() })
    } catch (e: TimeoutCancellationException) {
        println("processing abandoned: timeout exceeded")
        return@runBlocking
    } catch (e: IOException) {
        // 读取的错误原样到达这里
        println("error: ${e::class.simpleName} : ${e.message}")
        return@runBlocking
    }

    // 2 - 对大量纳税人进行纯计算:先顺序执行,再并行执行
    val scale = withContext(Dispatchers.IO) { loadBrackets(brackets) }
    val random = Random(2026)
    val crowd = List(1_000_000) {
        Taxpayer(random.nextBoolean(), random.nextInt(0, 5), random.nextInt(10_000, 150_000))
    }
    val (total1, duration1) = measureTimedValue { crowd.sumOf { calculateTax(scale, it).toLong() } }
    println("2 - in sequence: total = %,d €, in %d ms".format(total1, duration1.inWholeMilliseconds))
    val (total2, duration2) = measureTimedValue {
        withContext(Dispatchers.Default) {
            // 每个协程一批纳税人,批数与处理器数相同
            val size = crowd.size / Runtime.getRuntime().availableProcessors() + 1
            crowd.chunked(size)
                .map { batch -> async { batch.sumOf { calculateTax(scale, it).toLong() } } }
                .awaitAll()
                .sum()
        }
    }
    println("2 - in parallel: total = %,d €, in %d ms".format(total2, duration2.inWholeMilliseconds))
}

// 两个文件同时读取;计算等待两个读取完成,然后写入结果
suspend fun process(bracketsFile: Path, taxpayersFile: Path, output: Path): Int = coroutineScope {
    val brackets = async(Dispatchers.IO) { loadBrackets(bracketsFile) }
    val taxpayers = async(Dispatchers.IO) { taxpayersFile.readLines() }
    calculateTaxes(brackets.await(), taxpayers.await(), output)
}

// 读取税率档(limit:coeffR:coeffN,小数点),忽略空行
fun loadBrackets(file: Path): List<TaxBracket> =
    file.useLines { lines -> lines.filter { it.isNotBlank() }.map(TaxBracket::parse).toList() }

// 计算每个纳税人的税款并写入结果(I/O:在 IO 调度器上)
suspend fun calculateTaxes(brackets: List<TaxBracket>, taxpayers: List<String>, output: Path): Int =
    withContext(Dispatchers.IO) {
        output.bufferedWriter().use { writer ->
            for (line in taxpayers) {
                val result = TAXPAYER.matchEntire(line.trim())?.destructured
                    ?.let { (married, children, salary) ->
                        val taxpayer = Taxpayer(married == "y", children.toInt(), salary.toInt())
                        "tax = ${calculateTax(brackets, taxpayer)} €"
                    }
                    ?: "incorrect line"
                writer.write("%-12s : %s".format(line, result))
                writer.newLine()
            }
        }
        taxpayers.size
    }

// 税款计算(2003 年收入适用的 2004 年税率表,为练习而保留)
fun calculateTax(brackets: List<TaxBracket>, taxpayer: Taxpayer): Int {
    val (married, nbChildren, salary) = taxpayer
    var shares = BigDecimal(nbChildren).divide(BigDecimal.TWO) + BigDecimal(if (married) 2 else 1)
    if (nbChildren >= 3) shares += BigDecimal("0.5")
    val income = BigDecimal("0.72") * BigDecimal(salary)
    val quotient = income.divide(shares, MathContext.DECIMAL64)
    // 第一个上限超过家庭商数的税率档,否则取最后一个
    val bracket = brackets.firstOrNull { quotient <= it.limit } ?: brackets.last()
    return (bracket.coeffR * income - bracket.coeffN * shares).toInt()
}

// 一个纳税人
data class Taxpayer(val married: Boolean, val nbChildren: Int, val salary: Int)

// 一个税率档
data class TaxBracket(val limit: BigDecimal, val coeffR: BigDecimal, val coeffN: BigDecimal) {
    companion object {
        fun parse(line: String): TaxBracket {
            val (limit, coeffR, coeffN) = line.split(":").map(::BigDecimal)
            return TaxBracket(limit, coeffR, coeffN)
        }
    }
}

结果:

> gradlew -q run -Pmain=async33.Async33Kt
7 lines written to [results.txt]:
y 2 60000    : tax = 4282 €
y 3 60000    : tax = 2959 €
n 0 60000    : tax = 11519 €
n 2 25000    : tax = 792 €
y 5 120000   : tax = 11109 €
x 1 20000    : incorrect line
y 1 -5       : incorrect line
2 - in sequence: total = 11,374,472,918 €, in 338 ms
2 - in parallel: total = 11,374,472,918 €, in 145 ms

同一个程序,以一个不存在的税率档文件名作为参数(Gradle 任务 [--args] 选项 [run] 把它的参数传给程序):

> gradlew -q run -Pmain=async33.Async33Kt --args="Missing.txt"
Error: NoSuchFileException : Missing.txt

说明:

  • 第 72–75 行:处理是一个挂起函数,其函数体是一个 [coroutineScope] 块。两个输入文件由 [async] 在调度器 [IO] 上启动的两个协程同时读取,使用的是普通的阻塞式读取函数([useLines]、[readLines]);计算使用 [await()] 等待这两次读取。Java 程序必须把计算作为第三个任务启动,该任务在等待两次读取时会阻塞一个虚拟线程;而在这里,计算只是代码的后续部分;
  • 第 35–42 行:主程序使用 [withTimeout] 把处理限制在 10 秒内。超过这个时间,处理就会被取消——也就是两次读取和计算——而无需任何额外的代码:这就是结构化并发。表达式 [return@runBlocking] 退出 [runBlocking] 的 lambda,从而结束程序(第 7 章:带标签的 [return]);
  • 第 44–46 行:错误在一个位置处理,即主程序中。读取错误(文件缺失、数字不正确)会导致读取协程失败;随后 [coroutineScope] 块取消另一个读取操作,并重新抛出原始异常,该异常原样传递给 [catch] (第二个结果)。Java 程序过去收到的这个异常被 [ExecutionException] 包装了两次,必须在循环中把它解包:结构化并发消除了这一缺点,正如 Java 课程中所解释的;
  • 第 33 行:税率档文件的名称是程序的第一个参数(如果有的话);否则,[getOrElse] 返回由 lambda 计算出的值;
  • 第 79–80 行:读取税率档,使用文件的行序列([useLines]),它会跳过空行;
  • 第 83–97 行:纳税人的处理,它要写入文件;因此它把自己交给调度器 [IO],遵循程序 [Async21.kt] 所确立的规则。每一行由第 29 行的正则表达式验证:要么是 [y],要么是 [n],后面跟着两个以空格分隔的正整数([\s+]);原始字符串(["""…"""])避免反斜杠被加倍。如果整行与表达式匹配,[matchEntire] 返回匹配结果,否则返回 [null] ;它的属性 [destructured] 允许在 [let] 中通过解构赋值取出这三个分组。当行不匹配时([?:])Elvis 运算符返回文本“incorrect line”([x] 而不是 [y/n],或工资为负数);
  • 第 101–109 行:税款计算,使用 [BigDecimal],借助运算符 [+]、[*]、[-], 和 [<=], 编写,Kotlin 允许对这种类型使用它们。把收入除以份数可能不精确:这是使用 [divide] 以 16 位有效数字的精度([MathContext.DECIMAL64])完成的,而不是使用运算符 [/],后者会把商舍入到被除数的小数位数。使用 [firstOrNull] 找到第一个上限大于或等于家庭商数的税率档,如果其他税率档都不合适,Elvis 运算符就返回最后一个税率档。[toInt()] 把税款截断到欧元整数。纳税人是一个数据类,通过解构语句拆分;
  • 结果给出了贯穿全课程的对照值:已婚、有 2 个孩子、年薪 60000 欧元的夫妇税款为 4282 欧元,有 3 个孩子时为 2959 欧元,没有孩子的单身人士为 11519 欧元;
  • 第 50–68 行:使用伪随机数生成器([Random])生成一百万名虚构纳税人,其固定的种子(2026)确保结果可复现。他们的税款首先被顺序相加([sumOf],然后用 [Long] 以防止 [Int] 超出容量)。然后他们被分成与机器处理器数量相同的若干批([chunked]);每一批被分配给调度器 [Default] 的一个协程,该调度器的线程数与处理器数相同,而 [awaitAll()] 计算部分和。总和是一样的,而且在这台双处理器的机器上计算更快(表观加速比甚至大于 2,因为第一次测量包含了 JVM 把计算代码编译为机器码所需的时间)。

计算一位纳税人的税款是同步的:它不涉及 I/O,只需几微秒。把它变成挂起函数或委托给另一个线程毫无意义——甚至有害:只有涉及等待的任务才应该被异步化。另一方面,大量相互独立的计算可以分配给各个处理器:这是 [Default] 调度器(或第 8 章讨论的并行流)的职责,而不是 [IO] 调度器或虚拟线程的职责,后者处理的是等待操作。

9.16. 黄金法则

让我们总结一下使用协程进行异步编程的规则:

  • 等待时要挂起,而不是阻塞:在协程中,等待通过挂起函数完成([delay]、[await()]、[send]、[receive]、[withContext]……),绝不通过 [Thread.sleep]、[join()],或来自 [get()] 的 [Future] 完成。[runBlocking] 只属于主程序和测试;
  • 阻塞式挂起函数自己把控制权交给正确的调度器:阻塞代码(文件、JDBC、Java 库)由 [Dispatchers.IO] 通过 [withContext(Dispatchers.IO)] 在阻塞函数内部移交;这样调用者就可以从任何地方调用它。返回 [CompletableFuture] 的 API 与 [await()] 搭配使用;基于回调的 API 与 [suspendCancellableCoroutine] 搭配使用;
  • Dispatchers.Default 用于计算,Dispatchers.IO 用于阻塞式等待,Dispatchers.Main 用于界面;用 [limitedParallelism(n)] 视图为阻塞资源预留一定数量的线程;当存在数千个阻塞式等待时,让虚拟线程充当调度器;
  • 每个协程都有父级:协程在作用域内启动([coroutineScope]、组件的作用域、[viewModelScope]……),绝不在 [GlobalScope] 中启动;作用域等待它的子协程;如果一个子协程失败,其他的会被取消(使用 [supervisorScope] 使它们相互独立),取消父级会取消它的子协程。启动协程而不等待它们的函数是 [CoroutineScope] 的扩展;等待其工作完成的函数是 [suspend] 函数;
  • 先启动,后等待:要同时执行多个相互独立的操作,先把它们全部启动([async]),然后再等待它们([awaitAll()]);
  • 取消是协作式的:协程在它的挂起点处停止;长时间的计算要检查 [isActive] 或调用 [ensureActive()] / [yield()];[CancellationException] 永远不应被吞掉(要小心 [catch (e: Exception)] 和 [runCatching]);必须挂起的已取消协程的清理工作在 [withContext(NonCancellable)] 中执行;
  • 限制等待时间:[withTimeout] 和 [withTimeoutOrNull] 取消的是操作本身,而不仅仅是等待;带超时的 [CompletableDeferred] 必须由其创建者取消;
  • 使用信号量限制并发操作([withPermit]),或使用固定数量的工作者读取 [Channel];[limitedParallelism] 限制的是线程,而不是被挂起的操作;
  • 值的序列就是 Flow:冷的,按需收集,由运算符转换;用 [flowOn] 改变生产者的调度器,用 [buffer] 使生产者和消费者解耦,用 [catch] 处理上游错误。热的数据源有 [Channel] (每个值只交给一个消费者)、[SharedFlow] (所有订阅者)或 [StateFlow] (一种状态);
  • 不要在挂起调用周围使用线程锁:[synchronized] 和 [ReentrantLock] 不得包围挂起调用;请使用 [Mutex],或者更好的做法是避免共享状态(共享的 [Deferred]、通道、不可变数据)。

下表总结了平台线程与阻塞式等待的世界(上一章)、虚拟线程与 [CompletableFuture] 的世界(Java 课程)以及协程的世界之间的对应关系:

线程、阻塞式等待
虚拟线程、CompletableFuture
协程
[Thread.sleep(1000)] (阻塞线程)
[Thread.sleep(1000)] 在虚拟线程上(释放载体线程)
[delay(1000)] (挂起协程)
[thread { … }] 后接 [join()]
[executor.submit { … }] 然后 [get()];[supplyAsync { … }] 然后 [join()]
[launch { … }] 后接 [join()];[async { … }] 后接 [await()]
等待多个线程(在循环中 [join] )
[invokeAll(...)]、[allOf(...)]、[anyOf(...)]
[awaitAll()]、[coroutineScope]、[select]
回调方法([CompletionHandler])
[thenApply]、[thenCompose]、[thenCombine]
挂起调用之后的代码
[try / catch] 围绕 [get()] ([ExecutionException])
[exceptionally]、[handle]、[whenComplete]
[try / catch](常规),[CoroutineExceptionHandler]
[thread.interrupt()]
[future.cancel(true)]
[job.cancel()] (协作式取消,传播给子协程)
[future.get(timeout, unit)]
[orTimeout(...)]、[completeOnTimeout(...)]
[withTimeout(...)]、[withTimeoutOrNull(...)]
固定大小的线程池
[Semaphore] ([java.util.concurrent])
[Semaphore] ([kotlinx.coroutines.sync]),[limitedParallelism(n)]
[BlockingQueue] (阻塞线程)
[BlockingQueue] 在虚拟线程上,[SubmissionPublisher]
[Channel]、[SharedFlow]
[Stream]、[Iterator]
[Stream],由虚拟线程读取的阻塞式流
[Flow]
[synchronized]、[ReentrantLock]
[ReentrantLock]
[Mutex]
[ScheduledExecutorService]
[ScheduledExecutorService]、[delayedExecutor]
[delay] 在循环中
—
[new CompletableFuture<>()]、[complete]
[CompletableDeferred]、[suspendCancellableCoroutine]
—
[StructuredTaskScope] (预览)
[coroutineScope]、[supervisorScope]

接下来的各章将应用这些规则:使用 JDBC(第 10 章)和 Hibernate(第 11 章)访问数据库,其中的 API 调用是阻塞的,并在 [IO] 调度器上(或在虚拟线程上)从协程中使用;TCP 服务器,它通过虚拟线程或协程为每个客户端提供服务;以及 [HttpClient] 客户端(第 12 章),还有 Spring Boot Web 服务及其客户端(第 13 章)。