用途
kp-callback-bridging 用于把基于回调(callback)的 API 包装成 Kotlin 的挂起函数(suspend fun),使调用方能够以符合协程习惯的方式使用这些接口。其核心是 suspendCancellableCoroutine { … },在包装的同时保证协程被取消时能够注销回调。
主要能力
suspendCancellableCoroutine<T> { cont -> … } 是一个协程构建器,它会:
- 挂起调用方协程;
- 提供一个 CancellableContinuation<T>(即 cont);
- 在调用 cont.resume(value) 或 cont.resumeWithException(e) 时恢复调用方;
- 如果父协程被取消,则执行通过 invokeOnCancellation { … } 注册的代码块,从而干净地注销回调。
示例:
suspend fun fetchUser(id: UserId): User = suspendCancellableCoroutine { cont ->
val request = api.fetchUser(id, object : Callback<User> {
override fun onSuccess(user: User) { cont.resume(user) }
override fun onError(e: Throwable) { cont.resumeWithException(e) }
})
cont.invokeOnCancellation { request.cancel() }
}
其中 invokeOnCancellation 钩子是关键:没有它,取消调用方协程会导致回调泄漏,第三方 API 会一直持有引用直到回调触发(也可能永远不触发)。
应优先使用 suspendCancellableCoroutine 而非 suspendCoroutine。两者都存在,但不可取消的变体没有 invokeOnCancellation 钩子,不应被用于任何持有外部资源的场景。
对于事件式(多次触发)的回调,应使用 callbackFlow:
fun sensorReadings(): Flow<Reading> = callbackFlow {
val listener = object : SensorListener {
override fun onReading(r: Reading) { trySend(r) }
}
sensor.register(listener)
awaitClose { sensor.unregister(listener) }
}
callbackFlow 返回一个 Flow<T>,其发射来自回调。awaitClose 代码块在流被取消时执行,注销逻辑就放在这里。
注意:CancellableContinuation 只能被恢复一次,否则会抛出 IllegalStateException。如果回调可能多次触发,说明它是事件流,应使用 callbackFlow 而非 suspendCancellableCoroutine。
使用方式与决策要点
- 一次性回调(成功或失败,只触发一次)→ 使用 suspendCancellableCoroutine。
- 多次触发回调(事件随时间到达)→ 使用 callbackFlow。
- 始终注册取消处理器(invokeOnCancellation / awaitClose)来注销回调。
- 测试包装器时,取消调用方协程并断言底层回调已被注销。
适用场景
- 包装使用回调/监听器的第三方库(Java SDK、网络客户端、硬件 API)。
- 将 Android API(OnClickListener、LocationListener、传感器回调)桥接为协程 API。
- 将一次性 future 风格 API(CompletableFuture、ListenableFuture)转换为 suspend fun。
- 将轮询/事件循环转换为 Flow(每次发射来自一个回调)。
不适用场景
- API 已经返回 Deferred、CompletableFuture 或协程——应使用 .await() 或已有的桥接函数。
- 回调多次触发且需要响应每一次调用——这不是一次性 suspend fun,而是 Flow,应使用 callbackFlow { … }。
限制与反模式
- 忘记 invokeOnCancellation:调用方取消时回调会无限期残留,造成内存泄漏。
- 对持有外部资源的场景使用 suspendCoroutine(不可取消变体):没有机会清理。
- 多次恢复 continuation:会抛出异常并使协程崩溃。
- 用 suspendCancellableCoroutine(一次性)包装事件流:会静默丢弃第一次之后的所有发射。
- 调用在其它线程上执行回调的第三方代码时,未考虑接收协程上下文是否在意(多数不在意,但 UI 线程在意)。
相关技能
- kp-coroutine-scope——拥有被包装调用生命周期的作用域。
- kp-flow-cold-vs-hot——callbackFlow 产生的是冷流。
- kp-anti-patterns——注册回调却不配对注销是典型的 Kotlin 坏味道。
参考资料
- Kotlin Coroutines(Marcin Moskała)——关于 suspendCancellableCoroutine 与桥接的章节。
- Kotlin 协程官方指南——协程取消;callbackFlow 文档。