弃用无 receiver 的事件扩展函数, 增加其 EventChannel receiver 版本替换

[Him188]

动机

• EventChannel 在 2.0 增加, 但原函数均不支持 EventChannel
• 降低 API 复杂度

变更

弃用

逐渐弃用如下 8 个 top-level 函数:

• nextEvent
• nextEventAsync
• nextEventOrNull
• nextEventOrNullAsync
• syncFromEvent
• asyncFromEvent
• syncFromEventOrNull
• asyncFromEventOrNull

增加

新增 2 个 EventChannel 的扩展函数 nextEvent 和 syncFromEvent:

public suspend inline fun <reified E : Event> EventChannel<*>.nextEvent(
    priority: EventPriority = EventPriority.NORMAL,
    noinline filter: suspend E.(E) -> Boolean = { true } 
): E = coroutineScope { nextEventImpl(this@nextEvent, E::class, this@coroutineScope, priority, filter) }

public suspend inline fun <reified E : Event, R : Any> EventChannel<*>.syncFromEvent(
    priority: EventPriority = EventPriority.NORMAL,
    crossinline mapper: suspend (E) -> R? // 删除了 receiver E
): R = coroutineScope { this@syncFromEvent.syncFromEventImpl(E::class, this, priority, mapper) }

注意, 默认的优先级为 NORMAL 而不是原来的 MONITOR

迁移方案

最终上述 8 个方法将简化为两个基础标准函数 (Extensions.kt) (见上 "变更").

超时, Async 和 OrNull 通过协程库的 CoroutineScope.async, withTimeout, withTimeoutOrNull 完成. 示例:

withTimeout(3000) { GlobalEventChannel.nextEvent<MessageEvent>() } // 相当于原来的 syncFromEvent<MessageEvent>(3000)

自动迁移

• nextEvent: 替换为 EventChannel.nextEvent + withTimeout
• nextEventAsync: 无替换
• nextEventOrNull: 替换为 EventChannel.nextEvent + withTimeoutOrNull
• nextEventOrNullAsync: 无替换
• syncFromEvent: 替换为 EventChannel.syncFromEvent + withTimeout
• asyncFromEvent: 无替换
• syncFromEventOrNull: 替换为 EventChannel.syncFromEvent + withTimeoutOrNull
• asyncFromEventOrNull: 无替换

更新计划

• 2.10: 以 WARNING 等级弃用所有上文提议的函数 (弃用无 receiver 的事件扩展函数, 增加其 EventChannel receiver 版本替换 #1754)
• 2.12: 提升 WARNING 到 ERROR
• 2.13: 提升 ERROR 到 HIDDEN